diff options
81 files changed, 8388 insertions, 6892 deletions
@@ -1,3 +1,118 @@ +2014-12-12 Stephen Davies <sdavies@sdc.com.au> + + Improve comment handling in pretty printing. + + * awk.h (comment_type): New field in the node. + (EOL_COMMENT, FULL_COMMENT): New defines. + * awkgram.y (block_comment): New variable. + (check_comment): New function. + (grammar): Add code to handle comments as needed. + (get_comment): Now takes a flag indicating kind of comment. + (yylex): Collect comments appropriately. + (append_rule): Ditto. + * profile.c (pprint): Smarten up comment handling. + Have printing \n take comments into account. + (end_line): New function. + (pp_func): Better handling of function comments. + +2014-12-10 Arnold D. Robbins <arnold@skeeve.com> + + * dfa.c: Sync with GNU grep. + +2014-11-26 Arnold D. Robbins <arnold@skeeve.com> + + * builtin.c (do_sub): Improve wording of gensub warnings. + +2014-11-25 Arnold D. Robbins <arnold@skeeve.com> + + * builtin.c (do_sub): For gensub, add more warnings for invalid + third argument. + +2014-11-23 Arnold D. Robbins <arnold@skeeve.com> + + * awk.h: Move all inline functions to the bottom of the file. + Keeps modern GCC happier. + +2014-11-22 Arnold D. Robbins <arnold@skeeve.com> + + * awk.h (emalloc, realloc): Redefine in terms of ... + (emalloc_real, eralloc_real): New static inline functions. + (fatal): Move definition up. + * gawkmisc.c (xmalloc): If count is zero, make it one for older + mallocs that require size > 0 (such as z/OS). + +2014-11-21 Arnold D. Robbins <arnold@skeeve.com> + + * main.c: Remove a debugging // comment. + * NOTES: Removed. + + Unrelated: + + Revert changes of 2014-11-20 from Paul Eggert. Causes failures + on z/OS. + + Unrelated: Avoid unnecessary copying of $0. + + * interpret.h (UNFIELD): New macro. + (r_interpret): Use it where *lhs is assigned to. + +2014-11-20 Paul Eggert <eggert@cs.ucla.edu> + + Port to systems where malloc (0) and/or realloc(P, 0) returns NULL. + * gawkmisc.c (xmalloc): + * xalloc.h (realloc): + Do not fail if malloc(0) or realloc(P, 0) returns NULL. + Fail only when the allocator returns null when attempting to + allocate a nonzero number of bytes. + +2014-11-19 Arnold D. Robbins <arnold@skeeve.com> + + Infrastructure upgrades: + + * Automake 1.14.1, Gettext 0.19.3, Libtool 2.4.3. + * compile, extension/build-aux/compile: New files. + +2014-11-19 gettextize <bug-gnu-gettext@gnu.org> + + * configure.ac (AM_GNU_GETTEXT_VERSION): Bump to 0.19.3. + +2014-11-16 Arnold D. Robbins <arnold@skeeve.com> + + * interpret.h: Revert change of 2014-11-11 since it breaks + certain uses. + + Unrelated: + + * dfa.c: Sync with GNU grep. + +2014-11-15 Arnold D. Robbins <arnold@skeeve.com> + + * array.c, awk.h, awkgram.y, builtin.c, dfa.c, eval.c, field.c, + interpret.h, io.c, main.c, mpfr.c, node.c, re.c, regex_internal.h, + replace.c: Remove all uses of MBS_SUPPORT. + * regex_internal.h: Disable wide characters on DJGPP. + * mbsupport.h: Rework to be needed only for DJGPP. + +2014-11-11 Arnold D. Robbins <arnold@skeeve.com> + + Don't let memory used increase linearly in the size of + the input. Problem reported by dragan legic + <dragan.legic@yandex.ru>. + + * field.c (set_record): NUL-terminate the buffer. + * interpret.h (r_interpret): Op_field_spec: if it's $0, increment + the valref. Op_store_var: if we got $0, handle it appropriately. + +2014-11-10 Arnold D. Robbins <arnold@skeeve.com> + + Reorder main.c activities so that we can set a locale on the + command line with the new, for now undocumented, -Z option. + + * main.c (parse_args, set_locale_stuff): New functions. + (stopped_early): Made file level static. + (optlist, optab): Add new argument. + (main): Adjust ordering and move inline code into new functions. + 2014-11-09 Andrew J. Schorr <aschorr@telemetry-investments.com> * gawkapi.c (node_to_awk_value): When the type wanted is AWK_UNDEFINED @@ -106,6 +221,15 @@ more helpful - also used for unmatched [:, [., [=. Thanks to Davide Brini for raising the issue. +2014-10-12 KO Myung-Hun <komh78@gmail.com> + + Fixes for OS/2: + + * Makefile.am (install-exec-hook, uninstall-links): Use $(EXEEXT). + * getopt.h: Redefinitions if using KLIBC. + * io.c (_S_IFDIR, _S_IRWXU): Define if the more standard versions + are available. + 2014-10-12 Arnold D. Robbins <arnold@skeeve.com> * README: Remove Pat Rankin from VMS duties, per his request. diff --git a/Makefile.am b/Makefile.am index afe617ed..9119ad91 100644 --- a/Makefile.am +++ b/Makefile.am @@ -158,14 +158,14 @@ RM = rm -f install-exec-hook: (cd $(DESTDIR)$(bindir); \ $(LN) gawk$(EXEEXT) gawk-$(VERSION)$(EXEEXT) 2>/dev/null ; \ - if [ ! -f awk ]; \ - then $(LN_S) gawk$(EXEEXT) awk; \ + if [ ! -f awk$(EXEEXT) ]; \ + then $(LN_S) gawk$(EXEEXT) awk$(EXEEXT); \ fi; exit 0) # Undo the above when uninstalling uninstall-links: (cd $(DESTDIR)$(bindir); \ - if [ -f awk ] && cmp awk gawk$(EXEEXT) > /dev/null; then rm -f awk; fi ; \ + if [ -f awk$(EXEEXT) ] && cmp awk$(EXEEXT) gawk$(EXEEXT) > /dev/null; then rm -f awk$(EXEEXT); fi ; \ rm -f gawk-$(VERSION)$(EXEEXT); exit 0) uninstall-recursive: uninstall-links diff --git a/Makefile.in b/Makefile.in index e5d872b3..e45c520f 100644 --- a/Makefile.in +++ b/Makefile.in @@ -364,6 +364,7 @@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ POSUB = @POSUB@ +SED = @SED@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ SOCKET_LIBS = @SOCKET_LIBS@ @@ -1165,14 +1166,14 @@ uninstall-am: uninstall-binPROGRAMS uninstall-includeHEADERS install-exec-hook: (cd $(DESTDIR)$(bindir); \ $(LN) gawk$(EXEEXT) gawk-$(VERSION)$(EXEEXT) 2>/dev/null ; \ - if [ ! -f awk ]; \ - then $(LN_S) gawk$(EXEEXT) awk; \ + if [ ! -f awk$(EXEEXT) ]; \ + then $(LN_S) gawk$(EXEEXT) awk$(EXEEXT); \ fi; exit 0) # Undo the above when uninstalling uninstall-links: (cd $(DESTDIR)$(bindir); \ - if [ -f awk ] && cmp awk gawk$(EXEEXT) > /dev/null; then rm -f awk; fi ; \ + if [ -f awk$(EXEEXT) ] && cmp awk$(EXEEXT) gawk$(EXEEXT) > /dev/null; then rm -f awk$(EXEEXT); fi ; \ rm -f gawk-$(VERSION)$(EXEEXT); exit 0) uninstall-recursive: uninstall-links @@ -9,7 +9,8 @@ Changes from 4.1.x to 4.2.0 1. If not in POSIX mode, changes to ENVIRON are reflected into gawk's environment, affecting any programs run by system() - or for piped redirections. + or for piped redirections. This can also affect built-in routines, such + as mktime(), which is typically influenced by the TZ environment variable. 2. The series of numbers returned by rand() should now be "more random" than previously. Gawk's rand() remains repeatable; you will @@ -62,22 +63,26 @@ Changes from 4.1.1 to 4.1.2 5. Indirect function calls now work for both built-in and extension functions. -6. In non-English locales, it was accidentally possible to use "letters" +6. Built-in functions are now included in FUNCTAB. + +7. In non-English locales, it was accidentally possible to use "letters" beside those of the English alphabet in identifiers. This has been fixed. (isalpha and isalnum are NOT our friends.) If you feel that you must have this misfeature, use `configure --help' to see what option to use when configuring gawk to reenable it. -7. The "where" command has been added to the debugger as an alias +8. The "where" command has been added to the debugger as an alias for "backtrace". This will make life easier for long-time GDB users. -8. Gawk no longer explicitly checks the current directory after doing +9. Gawk no longer explicitly checks the current directory after doing a path search of AWKPATH. The default value continues to have "." at the front, so most people should not be affected. If you have your own AWKPATH setting, be sure to put "." in it somewhere. The documentation has been updated and clarified. +10. Infrastructure upgrades: Automake 1.14.1, Gettext 0.19.3, Libtool 2.4.3. + XX. A number of bugs have been fixed. See the ChangeLog. Changes from 4.1.0 to 4.1.1 @@ -978,14 +978,13 @@ cmp_strings(const NODE *n1, const NODE *n2) const unsigned char *cp1 = (const unsigned char *) s1; const unsigned char *cp2 = (const unsigned char *) s2; -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { ret = strncasecmpmbs((const unsigned char *) cp1, (const unsigned char *) cp2, lmin); - } else -#endif - for (ret = 0; lmin-- > 0 && ret == 0; cp1++, cp2++) - ret = casetable[*cp1] - casetable[*cp2]; + } else { + for (ret = 0; lmin-- > 0 && ret == 0; cp1++, cp2++) + ret = casetable[*cp1] - casetable[*cp2]; + } if (ret != 0) return ret; /* @@ -95,13 +95,11 @@ extern int errno; #include "missing_d/gawkbool.h" #endif -#include "mbsupport.h" /* defines MBS_SUPPORT */ - -#if MBS_SUPPORT /* We can handle multibyte strings. */ #include <wchar.h> #include <wctype.h> -#endif + +#include "mbsupport.h" /* defines stuff for DJGPP to fake MBS */ #ifdef STDC_HEADERS #include <float.h> @@ -395,10 +393,8 @@ typedef struct exp_node { size_t slen; long sref; int idx; -#if MBS_SUPPORT wchar_t *wsp; size_t wslen; -#endif } val; } sub; NODETYPE type; @@ -534,6 +530,11 @@ typedef struct exp_node { #define adepth sub.nodep.l.ll #define alevel sub.nodep.x.xl +/* Op_comment */ +#define comment_type sub.val.idx +#define EOL_COMMENT 1 +#define FULL_COMMENT 2 + /* --------------------------------lint warning types----------------------------*/ typedef enum lintvals { LINT_illegal, @@ -1105,11 +1106,7 @@ extern int exit_val; #define do_lint (do_flags & (DO_LINT_INVALID|DO_LINT_ALL)) #define do_lint_old (do_flags & DO_LINT_OLD) #endif -#if MBS_SUPPORT extern int gawk_mb_cur_max; -#else -#define gawk_mb_cur_max (1) -#endif #if defined (HAVE_GETGROUPS) && defined(NGROUPS_MAX) && NGROUPS_MAX > 0 extern GETGROUPS_T *groupset; @@ -1254,46 +1251,11 @@ DEREF(NODE *r) #define cant_happen() r_fatal("internal error line %d, file: %s", \ __LINE__, __FILE__) -#define emalloc(var,ty,x,str) (void)((var=(ty)malloc((size_t)(x))) ||\ - (fatal(_("%s: %s: can't allocate %ld bytes of memory (%s)"),\ - (str), #var, (long) (x), strerror(errno)),0)) -#define erealloc(var,ty,x,str) (void)((var = (ty)realloc((char *)var, (size_t)(x))) \ - ||\ - (fatal(_("%s: %s: can't allocate %ld bytes of memory (%s)"),\ - (str), #var, (long) (x), strerror(errno)),0)) +#define emalloc(var,ty,x,str) (void) (var = (ty) emalloc_real((size_t)(x), str, #var, __FILE__, __LINE__)) +#define erealloc(var,ty,x,str) (void) (var = (ty) erealloc_real((void *) var, (size_t)(x), str, #var, __FILE__, __LINE__)) #define efree(p) free(p) -static inline NODE * -force_string(NODE *s) -{ - if ((s->flags & STRCUR) != 0 - && (s->stfmt == -1 || s->stfmt == CONVFMTidx) - ) - return s; - return format_val(CONVFMT, CONVFMTidx, s); -} - -#ifdef GAWKDEBUG -#define unref r_unref -#define force_number str2number -#else /* not GAWKDEBUG */ - -static inline void -unref(NODE *r) -{ - if (r != NULL && --r->valref <= 0) - r_unref(r); -} - -static inline NODE * -force_number(NODE *n) -{ - return (n->flags & NUMCUR) ? n : str2number(n); -} - -#endif /* GAWKDEBUG */ - #define fatal set_loc(__FILE__, __LINE__), r_fatal extern jmp_buf fatal_tag; @@ -1419,10 +1381,8 @@ extern NODE *do_dcgettext(int nargs); extern NODE *do_dcngettext(int nargs); extern NODE *do_bindtextdomain(int nargs); extern NODE *do_div(int nargs); -#if MBS_SUPPORT extern int strncasecmpmbs(const unsigned char *, const unsigned char *, size_t); -#endif /* eval.c */ extern void PUSH_CODE(INSTRUCTION *cp); extern INSTRUCTION *POP_CODE(void); @@ -1608,7 +1568,6 @@ extern NODE *r_dupnode(NODE *n); extern NODE *make_str_node(const char *s, size_t len, int flags); extern void *more_blocks(int id); extern int parse_escape(const char **string_ptr); -#if MBS_SUPPORT extern NODE *str2wstr(NODE *n, size_t **ptr); extern NODE *wstr2str(NODE *n); #define force_wstring(n) str2wstr(n, NULL) @@ -1622,9 +1581,6 @@ extern wint_t btowc_cache[]; #define btowc_cache(x) btowc_cache[(x)&0xFF] extern void init_btowc_cache(); #define is_valid_character(b) (btowc_cache[(b)&0xFF] != WEOF) -#else -#define free_wstr(NODE) /* empty */ -#endif /* re.c */ extern Regexp *make_regexp(const char *s, size_t len, bool ignorecase, bool dfa, bool canfatal); extern int research(Regexp *rp, char *str, int start, size_t len, int flags); @@ -1793,3 +1749,65 @@ dupnode(NODE *n) return r_dupnode(n); } #endif + +static inline NODE * +force_string(NODE *s) +{ + if ((s->flags & STRCUR) != 0 + && (s->stfmt == -1 || s->stfmt == CONVFMTidx) + ) + return s; + return format_val(CONVFMT, CONVFMTidx, s); +} + +#ifdef GAWKDEBUG +#define unref r_unref +#define force_number str2number +#else /* not GAWKDEBUG */ + +static inline void +unref(NODE *r) +{ + if (r != NULL && --r->valref <= 0) + r_unref(r); +} + +static inline NODE * +force_number(NODE *n) +{ + return (n->flags & NUMCUR) ? n : str2number(n); +} + +#endif /* GAWKDEBUG */ + +static inline void * +emalloc_real(size_t count, const char *where, const char *var, const char *file, int line) +{ + void *ret; + + if (count == 0) + fatal("%s:%d: emalloc called with zero bytes", file, line); + + ret = (void *) malloc(count); + if (ret == NULL) + fatal(_("%s:%d:%s: %s: can't allocate %ld bytes of memory (%s)"), + file, line, where, var, (long) count, strerror(errno)); + + return ret; +} + +static inline void * +erealloc_real(void *ptr, size_t count, const char *where, const char *var, const char *file, int line) +{ + void *ret; + + if (count == 0) + fatal("%s:%d: erealloc called with zero bytes", file, line); + + ret = (void *) realloc(ptr, count); + if (ret == NULL) + fatal(_("%s:%d:%s: %s: can't reallocate %ld bytes of memory (%s)"), + file, line, where, var, (long) count, strerror(errno)); + + return ret; +} @@ -128,6 +128,7 @@ static void check_funcs(void); static ssize_t read_one_line(int fd, void *buffer, size_t count); static int one_line_close(int fd); static void split_comment(void); +static void check_comment(void); static bool want_source = false; static bool want_regexp = false; /* lexical scanning kludge */ @@ -191,8 +192,10 @@ INSTRUCTION *main_beginfile; static INSTRUCTION *comment = NULL; static INSTRUCTION *program_comment = NULL; static INSTRUCTION *function_comment = NULL; +static INSTRUCTION *block_comment = NULL; static bool func_first = true; +static bool first_rule = true; static inline INSTRUCTION *list_create(INSTRUCTION *x); static inline INSTRUCTION *list_append(INSTRUCTION *l, INSTRUCTION *x); @@ -203,7 +206,7 @@ extern double fmod(double x, double y); #define YYSTYPE INSTRUCTION * -#line 207 "awkgram.c" /* yacc.c:339 */ +#line 210 "awkgram.c" /* yacc.c:339 */ # ifndef YY_NULLPTR # if defined __cplusplus && 201103L <= __cplusplus @@ -357,7 +360,7 @@ int yyparse (void); /* Copy the second part of user declarations. */ -#line 361 "awkgram.c" /* yacc.c:358 */ +#line 364 "awkgram.c" /* yacc.c:358 */ #ifdef short # undef short @@ -659,25 +662,25 @@ static const yytype_uint8 yytranslate[] = /* YYRLINE[YYN] -- Source line where rule number YYN was defined. */ static const yytype_uint16 yyrline[] = { - 0, 206, 206, 208, 213, 214, 220, 232, 236, 247, - 253, 258, 266, 274, 276, 281, 289, 291, 297, 305, - 315, 341, 354, 367, 374, 384, 396, 398, 400, 406, - 411, 412, 416, 451, 450, 484, 486, 491, 497, 525, - 530, 531, 535, 537, 539, 546, 636, 678, 720, 833, - 840, 847, 857, 866, 875, 884, 895, 911, 910, 934, - 946, 946, 1044, 1044, 1077, 1107, 1113, 1114, 1120, 1121, - 1128, 1133, 1145, 1159, 1161, 1169, 1174, 1176, 1184, 1186, - 1195, 1196, 1204, 1209, 1209, 1220, 1224, 1232, 1233, 1236, - 1238, 1243, 1244, 1253, 1254, 1259, 1264, 1270, 1272, 1274, - 1281, 1282, 1288, 1289, 1294, 1296, 1301, 1303, 1311, 1316, - 1325, 1332, 1334, 1336, 1352, 1362, 1369, 1371, 1376, 1378, - 1380, 1388, 1390, 1395, 1397, 1402, 1404, 1406, 1456, 1458, - 1460, 1462, 1464, 1466, 1468, 1470, 1484, 1489, 1494, 1519, - 1525, 1527, 1529, 1531, 1533, 1535, 1540, 1544, 1576, 1578, - 1584, 1590, 1603, 1604, 1605, 1610, 1615, 1619, 1623, 1638, - 1651, 1656, 1692, 1710, 1711, 1717, 1718, 1723, 1725, 1732, - 1749, 1766, 1768, 1775, 1780, 1788, 1798, 1810, 1819, 1823, - 1827, 1831, 1835, 1839, 1842, 1844, 1848, 1852, 1856 + 0, 209, 209, 211, 216, 217, 223, 235, 239, 250, + 256, 261, 269, 277, 279, 284, 292, 294, 300, 308, + 318, 348, 362, 376, 384, 395, 407, 409, 411, 417, + 422, 423, 427, 462, 461, 495, 497, 502, 508, 536, + 541, 542, 546, 548, 550, 557, 647, 689, 731, 844, + 851, 858, 868, 877, 886, 895, 906, 922, 921, 945, + 957, 957, 1055, 1055, 1088, 1118, 1124, 1125, 1131, 1132, + 1139, 1144, 1156, 1170, 1172, 1180, 1185, 1187, 1195, 1197, + 1206, 1207, 1215, 1220, 1220, 1231, 1235, 1243, 1244, 1247, + 1249, 1254, 1255, 1264, 1265, 1270, 1275, 1281, 1283, 1285, + 1292, 1293, 1299, 1300, 1305, 1307, 1312, 1314, 1322, 1327, + 1336, 1343, 1345, 1347, 1363, 1373, 1380, 1382, 1387, 1389, + 1391, 1399, 1401, 1406, 1408, 1413, 1415, 1417, 1467, 1469, + 1471, 1473, 1475, 1477, 1479, 1481, 1495, 1500, 1505, 1530, + 1536, 1538, 1540, 1542, 1544, 1546, 1551, 1555, 1587, 1589, + 1595, 1601, 1614, 1615, 1616, 1621, 1626, 1630, 1634, 1649, + 1662, 1667, 1703, 1721, 1722, 1728, 1729, 1734, 1736, 1743, + 1760, 1777, 1779, 1786, 1791, 1799, 1809, 1821, 1830, 1834, + 1838, 1842, 1846, 1850, 1853, 1855, 1859, 1863, 1867 }; #endif @@ -1850,26 +1853,26 @@ yyreduce: switch (yyn) { case 3: -#line 209 "awkgram.y" /* yacc.c:1646 */ +#line 212 "awkgram.y" /* yacc.c:1646 */ { rule = 0; yyerrok; } -#line 1859 "awkgram.c" /* yacc.c:1646 */ +#line 1862 "awkgram.c" /* yacc.c:1646 */ break; case 5: -#line 215 "awkgram.y" /* yacc.c:1646 */ +#line 218 "awkgram.y" /* yacc.c:1646 */ { next_sourcefile(); if (sourcefile == srcfiles) process_deferred(); } -#line 1869 "awkgram.c" /* yacc.c:1646 */ +#line 1872 "awkgram.c" /* yacc.c:1646 */ break; case 6: -#line 221 "awkgram.y" /* yacc.c:1646 */ +#line 224 "awkgram.y" /* yacc.c:1646 */ { rule = 0; /* @@ -1878,19 +1881,19 @@ yyreduce: */ /* yyerrok; */ } -#line 1882 "awkgram.c" /* yacc.c:1646 */ +#line 1885 "awkgram.c" /* yacc.c:1646 */ break; case 7: -#line 233 "awkgram.y" /* yacc.c:1646 */ +#line 236 "awkgram.y" /* yacc.c:1646 */ { (void) append_rule((yyvsp[-1]), (yyvsp[0])); } -#line 1890 "awkgram.c" /* yacc.c:1646 */ +#line 1893 "awkgram.c" /* yacc.c:1646 */ break; case 8: -#line 237 "awkgram.y" /* yacc.c:1646 */ +#line 240 "awkgram.y" /* yacc.c:1646 */ { if (rule != Rule) { msg(_("%s blocks must have an action part"), ruletab[rule]); @@ -1901,39 +1904,39 @@ yyreduce: } else /* pattern rule with non-empty pattern */ (void) append_rule((yyvsp[-1]), NULL); } -#line 1905 "awkgram.c" /* yacc.c:1646 */ +#line 1908 "awkgram.c" /* yacc.c:1646 */ break; case 9: -#line 248 "awkgram.y" /* yacc.c:1646 */ +#line 251 "awkgram.y" /* yacc.c:1646 */ { in_function = NULL; (void) mk_function((yyvsp[-1]), (yyvsp[0])); yyerrok; } -#line 1915 "awkgram.c" /* yacc.c:1646 */ +#line 1918 "awkgram.c" /* yacc.c:1646 */ break; case 10: -#line 254 "awkgram.y" /* yacc.c:1646 */ +#line 257 "awkgram.y" /* yacc.c:1646 */ { want_source = false; yyerrok; } -#line 1924 "awkgram.c" /* yacc.c:1646 */ +#line 1927 "awkgram.c" /* yacc.c:1646 */ break; case 11: -#line 259 "awkgram.y" /* yacc.c:1646 */ +#line 262 "awkgram.y" /* yacc.c:1646 */ { want_source = false; yyerrok; } -#line 1933 "awkgram.c" /* yacc.c:1646 */ +#line 1936 "awkgram.c" /* yacc.c:1646 */ break; case 12: -#line 267 "awkgram.y" /* yacc.c:1646 */ +#line 270 "awkgram.y" /* yacc.c:1646 */ { if (include_source((yyvsp[0])) < 0) YYABORT; @@ -1941,23 +1944,23 @@ yyreduce: bcfree((yyvsp[0])); (yyval) = NULL; } -#line 1945 "awkgram.c" /* yacc.c:1646 */ +#line 1948 "awkgram.c" /* yacc.c:1646 */ break; case 13: -#line 275 "awkgram.y" /* yacc.c:1646 */ +#line 278 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 1951 "awkgram.c" /* yacc.c:1646 */ +#line 1954 "awkgram.c" /* yacc.c:1646 */ break; case 14: -#line 277 "awkgram.y" /* yacc.c:1646 */ +#line 280 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 1957 "awkgram.c" /* yacc.c:1646 */ +#line 1960 "awkgram.c" /* yacc.c:1646 */ break; case 15: -#line 282 "awkgram.y" /* yacc.c:1646 */ +#line 285 "awkgram.y" /* yacc.c:1646 */ { if (load_library((yyvsp[0])) < 0) YYABORT; @@ -1965,23 +1968,23 @@ yyreduce: bcfree((yyvsp[0])); (yyval) = NULL; } -#line 1969 "awkgram.c" /* yacc.c:1646 */ +#line 1972 "awkgram.c" /* yacc.c:1646 */ break; case 16: -#line 290 "awkgram.y" /* yacc.c:1646 */ +#line 293 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 1975 "awkgram.c" /* yacc.c:1646 */ +#line 1978 "awkgram.c" /* yacc.c:1646 */ break; case 17: -#line 292 "awkgram.y" /* yacc.c:1646 */ +#line 295 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 1981 "awkgram.c" /* yacc.c:1646 */ +#line 1984 "awkgram.c" /* yacc.c:1646 */ break; case 18: -#line 297 "awkgram.y" /* yacc.c:1646 */ +#line 300 "awkgram.y" /* yacc.c:1646 */ { rule = Rule; if (comment != NULL) { @@ -1990,11 +1993,11 @@ yyreduce: } else (yyval) = NULL; } -#line 1994 "awkgram.c" /* yacc.c:1646 */ +#line 1997 "awkgram.c" /* yacc.c:1646 */ break; case 19: -#line 306 "awkgram.y" /* yacc.c:1646 */ +#line 309 "awkgram.y" /* yacc.c:1646 */ { rule = Rule; if (comment != NULL) { @@ -2003,11 +2006,11 @@ yyreduce: } else (yyval) = (yyvsp[0]); } -#line 2007 "awkgram.c" /* yacc.c:1646 */ +#line 2010 "awkgram.c" /* yacc.c:1646 */ break; case 20: -#line 316 "awkgram.y" /* yacc.c:1646 */ +#line 319 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *tp; @@ -2030,14 +2033,18 @@ yyreduce: ((yyvsp[-3])->nexti + 1)->condpair_left = (yyvsp[-3])->lasti; ((yyvsp[-3])->nexti + 1)->condpair_right = (yyvsp[0])->lasti; } - (yyval) = list_append(list_merge((yyvsp[-3]), (yyvsp[0])), tp); + if (comment != NULL) { + (yyval) = list_append(list_merge(list_prepend((yyvsp[-3]), comment), (yyvsp[0])), tp); + comment = NULL; + } else + (yyval) = list_append(list_merge((yyvsp[-3]), (yyvsp[0])), tp); rule = Rule; } -#line 2037 "awkgram.c" /* yacc.c:1646 */ +#line 2044 "awkgram.c" /* yacc.c:1646 */ break; case 21: -#line 342 "awkgram.y" /* yacc.c:1646 */ +#line 349 "awkgram.y" /* yacc.c:1646 */ { static int begin_seen = 0; @@ -2048,13 +2055,14 @@ yyreduce: (yyvsp[0])->in_rule = rule = BEGIN; (yyvsp[0])->source_file = source; + check_comment(); (yyval) = (yyvsp[0]); } -#line 2054 "awkgram.c" /* yacc.c:1646 */ +#line 2062 "awkgram.c" /* yacc.c:1646 */ break; case 22: -#line 355 "awkgram.y" /* yacc.c:1646 */ +#line 363 "awkgram.y" /* yacc.c:1646 */ { static int end_seen = 0; @@ -2065,35 +2073,38 @@ yyreduce: (yyvsp[0])->in_rule = rule = END; (yyvsp[0])->source_file = source; + check_comment(); (yyval) = (yyvsp[0]); } -#line 2071 "awkgram.c" /* yacc.c:1646 */ +#line 2080 "awkgram.c" /* yacc.c:1646 */ break; case 23: -#line 368 "awkgram.y" /* yacc.c:1646 */ +#line 377 "awkgram.y" /* yacc.c:1646 */ { func_first = false; (yyvsp[0])->in_rule = rule = BEGINFILE; (yyvsp[0])->source_file = source; + check_comment(); (yyval) = (yyvsp[0]); } -#line 2082 "awkgram.c" /* yacc.c:1646 */ +#line 2092 "awkgram.c" /* yacc.c:1646 */ break; case 24: -#line 375 "awkgram.y" /* yacc.c:1646 */ +#line 385 "awkgram.y" /* yacc.c:1646 */ { func_first = false; (yyvsp[0])->in_rule = rule = ENDFILE; (yyvsp[0])->source_file = source; + check_comment(); (yyval) = (yyvsp[0]); } -#line 2093 "awkgram.c" /* yacc.c:1646 */ +#line 2104 "awkgram.c" /* yacc.c:1646 */ break; case 25: -#line 385 "awkgram.y" /* yacc.c:1646 */ +#line 396 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *ip; if ((yyvsp[-3]) == NULL) @@ -2102,39 +2113,39 @@ yyreduce: ip = (yyvsp[-3]); (yyval) = ip; } -#line 2106 "awkgram.c" /* yacc.c:1646 */ +#line 2117 "awkgram.c" /* yacc.c:1646 */ break; case 26: -#line 397 "awkgram.y" /* yacc.c:1646 */ +#line 408 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2112 "awkgram.c" /* yacc.c:1646 */ +#line 2123 "awkgram.c" /* yacc.c:1646 */ break; case 27: -#line 399 "awkgram.y" /* yacc.c:1646 */ +#line 410 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2118 "awkgram.c" /* yacc.c:1646 */ +#line 2129 "awkgram.c" /* yacc.c:1646 */ break; case 28: -#line 401 "awkgram.y" /* yacc.c:1646 */ +#line 412 "awkgram.y" /* yacc.c:1646 */ { yyerror(_("`%s' is a built-in function, it cannot be redefined"), tokstart); YYABORT; } -#line 2128 "awkgram.c" /* yacc.c:1646 */ +#line 2139 "awkgram.c" /* yacc.c:1646 */ break; case 29: -#line 407 "awkgram.y" /* yacc.c:1646 */ +#line 418 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2134 "awkgram.c" /* yacc.c:1646 */ +#line 2145 "awkgram.c" /* yacc.c:1646 */ break; case 32: -#line 417 "awkgram.y" /* yacc.c:1646 */ +#line 428 "awkgram.y" /* yacc.c:1646 */ { /* * treat any comments between BOF and the first function @@ -2161,17 +2172,17 @@ yyreduce: /* $4 already free'd in install_function */ (yyval) = (yyvsp[-5]); } -#line 2165 "awkgram.c" /* yacc.c:1646 */ +#line 2176 "awkgram.c" /* yacc.c:1646 */ break; case 33: -#line 451 "awkgram.y" /* yacc.c:1646 */ +#line 462 "awkgram.y" /* yacc.c:1646 */ { want_regexp = true; } -#line 2171 "awkgram.c" /* yacc.c:1646 */ +#line 2182 "awkgram.c" /* yacc.c:1646 */ break; case 34: -#line 453 "awkgram.y" /* yacc.c:1646 */ +#line 464 "awkgram.y" /* yacc.c:1646 */ { NODE *n, *exp; char *re; @@ -2200,28 +2211,28 @@ yyreduce: (yyval)->opcode = Op_match_rec; (yyval)->memory = n; } -#line 2204 "awkgram.c" /* yacc.c:1646 */ +#line 2215 "awkgram.c" /* yacc.c:1646 */ break; case 35: -#line 485 "awkgram.y" /* yacc.c:1646 */ +#line 496 "awkgram.y" /* yacc.c:1646 */ { bcfree((yyvsp[0])); } -#line 2210 "awkgram.c" /* yacc.c:1646 */ +#line 2221 "awkgram.c" /* yacc.c:1646 */ break; case 37: -#line 491 "awkgram.y" /* yacc.c:1646 */ +#line 502 "awkgram.y" /* yacc.c:1646 */ { if (comment != NULL) { (yyval) = list_create(comment); comment = NULL; } else (yyval) = NULL; } -#line 2221 "awkgram.c" /* yacc.c:1646 */ +#line 2232 "awkgram.c" /* yacc.c:1646 */ break; case 38: -#line 498 "awkgram.y" /* yacc.c:1646 */ +#line 509 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[0]) == NULL) { if (comment == NULL) @@ -2249,40 +2260,40 @@ yyreduce: } yyerrok; } -#line 2253 "awkgram.c" /* yacc.c:1646 */ +#line 2264 "awkgram.c" /* yacc.c:1646 */ break; case 39: -#line 526 "awkgram.y" /* yacc.c:1646 */ +#line 537 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2259 "awkgram.c" /* yacc.c:1646 */ +#line 2270 "awkgram.c" /* yacc.c:1646 */ break; case 42: -#line 536 "awkgram.y" /* yacc.c:1646 */ +#line 547 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2265 "awkgram.c" /* yacc.c:1646 */ +#line 2276 "awkgram.c" /* yacc.c:1646 */ break; case 43: -#line 538 "awkgram.y" /* yacc.c:1646 */ +#line 549 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 2271 "awkgram.c" /* yacc.c:1646 */ +#line 2282 "awkgram.c" /* yacc.c:1646 */ break; case 44: -#line 540 "awkgram.y" /* yacc.c:1646 */ +#line 551 "awkgram.y" /* yacc.c:1646 */ { if (do_pretty_print) (yyval) = list_prepend((yyvsp[0]), instruction(Op_exec_count)); else (yyval) = (yyvsp[0]); } -#line 2282 "awkgram.c" /* yacc.c:1646 */ +#line 2293 "awkgram.c" /* yacc.c:1646 */ break; case 45: -#line 547 "awkgram.y" /* yacc.c:1646 */ +#line 558 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *dflt, *curr = NULL, *cexp, *cstmt; INSTRUCTION *ip, *nextc, *tbreak; @@ -2372,11 +2383,11 @@ yyreduce: break_allowed--; fix_break_continue(ip, tbreak, NULL); } -#line 2376 "awkgram.c" /* yacc.c:1646 */ +#line 2387 "awkgram.c" /* yacc.c:1646 */ break; case 46: -#line 637 "awkgram.y" /* yacc.c:1646 */ +#line 648 "awkgram.y" /* yacc.c:1646 */ { /* * ----------------- @@ -2418,11 +2429,11 @@ yyreduce: continue_allowed--; fix_break_continue(ip, tbreak, tcont); } -#line 2422 "awkgram.c" /* yacc.c:1646 */ +#line 2433 "awkgram.c" /* yacc.c:1646 */ break; case 47: -#line 679 "awkgram.y" /* yacc.c:1646 */ +#line 690 "awkgram.y" /* yacc.c:1646 */ { /* * ----------------- @@ -2464,11 +2475,11 @@ yyreduce: } /* else $1 and $4 are NULLs */ } -#line 2468 "awkgram.c" /* yacc.c:1646 */ +#line 2479 "awkgram.c" /* yacc.c:1646 */ break; case 48: -#line 721 "awkgram.y" /* yacc.c:1646 */ +#line 732 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *ip; char *var_name = (yyvsp[-5])->lextok; @@ -2581,44 +2592,44 @@ regular_loop: break_allowed--; continue_allowed--; } -#line 2585 "awkgram.c" /* yacc.c:1646 */ +#line 2596 "awkgram.c" /* yacc.c:1646 */ break; case 49: -#line 834 "awkgram.y" /* yacc.c:1646 */ +#line 845 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_for_loop((yyvsp[-11]), (yyvsp[-9]), (yyvsp[-6]), (yyvsp[-3]), (yyvsp[0])); break_allowed--; continue_allowed--; } -#line 2596 "awkgram.c" /* yacc.c:1646 */ +#line 2607 "awkgram.c" /* yacc.c:1646 */ break; case 50: -#line 841 "awkgram.y" /* yacc.c:1646 */ +#line 852 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_for_loop((yyvsp[-10]), (yyvsp[-8]), (INSTRUCTION *) NULL, (yyvsp[-3]), (yyvsp[0])); break_allowed--; continue_allowed--; } -#line 2607 "awkgram.c" /* yacc.c:1646 */ +#line 2618 "awkgram.c" /* yacc.c:1646 */ break; case 51: -#line 848 "awkgram.y" /* yacc.c:1646 */ +#line 859 "awkgram.y" /* yacc.c:1646 */ { if (do_pretty_print) (yyval) = list_prepend((yyvsp[0]), instruction(Op_exec_count)); else (yyval) = (yyvsp[0]); } -#line 2618 "awkgram.c" /* yacc.c:1646 */ +#line 2629 "awkgram.c" /* yacc.c:1646 */ break; case 52: -#line 858 "awkgram.y" /* yacc.c:1646 */ +#line 869 "awkgram.y" /* yacc.c:1646 */ { if (! break_allowed) error_ln((yyvsp[-1])->source_line, @@ -2627,11 +2638,11 @@ regular_loop: (yyval) = list_create((yyvsp[-1])); } -#line 2631 "awkgram.c" /* yacc.c:1646 */ +#line 2642 "awkgram.c" /* yacc.c:1646 */ break; case 53: -#line 867 "awkgram.y" /* yacc.c:1646 */ +#line 878 "awkgram.y" /* yacc.c:1646 */ { if (! continue_allowed) error_ln((yyvsp[-1])->source_line, @@ -2640,11 +2651,11 @@ regular_loop: (yyval) = list_create((yyvsp[-1])); } -#line 2644 "awkgram.c" /* yacc.c:1646 */ +#line 2655 "awkgram.c" /* yacc.c:1646 */ break; case 54: -#line 876 "awkgram.y" /* yacc.c:1646 */ +#line 887 "awkgram.y" /* yacc.c:1646 */ { /* if inside function (rule = 0), resolve context at run-time */ if (rule && rule != Rule) @@ -2653,11 +2664,11 @@ regular_loop: (yyvsp[-1])->target_jmp = ip_rec; (yyval) = list_create((yyvsp[-1])); } -#line 2657 "awkgram.c" /* yacc.c:1646 */ +#line 2668 "awkgram.c" /* yacc.c:1646 */ break; case 55: -#line 885 "awkgram.y" /* yacc.c:1646 */ +#line 896 "awkgram.y" /* yacc.c:1646 */ { /* if inside function (rule = 0), resolve context at run-time */ if (rule == BEGIN || rule == END || rule == ENDFILE) @@ -2668,11 +2679,11 @@ regular_loop: (yyvsp[-1])->target_endfile = ip_endfile; (yyval) = list_create((yyvsp[-1])); } -#line 2672 "awkgram.c" /* yacc.c:1646 */ +#line 2683 "awkgram.c" /* yacc.c:1646 */ break; case 56: -#line 896 "awkgram.y" /* yacc.c:1646 */ +#line 907 "awkgram.y" /* yacc.c:1646 */ { /* Initialize the two possible jump targets, the actual target * is resolved at run-time. @@ -2687,20 +2698,20 @@ regular_loop: } else (yyval) = list_append((yyvsp[-1]), (yyvsp[-2])); } -#line 2691 "awkgram.c" /* yacc.c:1646 */ +#line 2702 "awkgram.c" /* yacc.c:1646 */ break; case 57: -#line 911 "awkgram.y" /* yacc.c:1646 */ +#line 922 "awkgram.y" /* yacc.c:1646 */ { if (! in_function) yyerror(_("`return' used outside function context")); } -#line 2700 "awkgram.c" /* yacc.c:1646 */ +#line 2711 "awkgram.c" /* yacc.c:1646 */ break; case 58: -#line 914 "awkgram.y" /* yacc.c:1646 */ +#line 925 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[-1]) == NULL) { (yyval) = list_create((yyvsp[-3])); @@ -2721,17 +2732,17 @@ regular_loop: (yyval) = list_append((yyvsp[-1]), (yyvsp[-3])); } } -#line 2725 "awkgram.c" /* yacc.c:1646 */ +#line 2736 "awkgram.c" /* yacc.c:1646 */ break; case 60: -#line 946 "awkgram.y" /* yacc.c:1646 */ +#line 957 "awkgram.y" /* yacc.c:1646 */ { in_print = true; in_parens = 0; } -#line 2731 "awkgram.c" /* yacc.c:1646 */ +#line 2742 "awkgram.c" /* yacc.c:1646 */ break; case 61: -#line 947 "awkgram.y" /* yacc.c:1646 */ +#line 958 "awkgram.y" /* yacc.c:1646 */ { /* * Optimization: plain `print' has no expression list, so $3 is null. @@ -2828,17 +2839,17 @@ regular_print: } } } -#line 2832 "awkgram.c" /* yacc.c:1646 */ +#line 2843 "awkgram.c" /* yacc.c:1646 */ break; case 62: -#line 1044 "awkgram.y" /* yacc.c:1646 */ +#line 1055 "awkgram.y" /* yacc.c:1646 */ { sub_counter = 0; } -#line 2838 "awkgram.c" /* yacc.c:1646 */ +#line 2849 "awkgram.c" /* yacc.c:1646 */ break; case 63: -#line 1045 "awkgram.y" /* yacc.c:1646 */ +#line 1056 "awkgram.y" /* yacc.c:1646 */ { char *arr = (yyvsp[-2])->lextok; @@ -2871,11 +2882,11 @@ regular_print: (yyval) = list_append(list_append((yyvsp[0]), (yyvsp[-2])), (yyvsp[-3])); } } -#line 2875 "awkgram.c" /* yacc.c:1646 */ +#line 2886 "awkgram.c" /* yacc.c:1646 */ break; case 64: -#line 1082 "awkgram.y" /* yacc.c:1646 */ +#line 1093 "awkgram.y" /* yacc.c:1646 */ { static bool warned = false; char *arr = (yyvsp[-1])->lextok; @@ -2901,52 +2912,52 @@ regular_print: fatal(_("`delete' is not allowed with FUNCTAB")); } } -#line 2905 "awkgram.c" /* yacc.c:1646 */ +#line 2916 "awkgram.c" /* yacc.c:1646 */ break; case 65: -#line 1108 "awkgram.y" /* yacc.c:1646 */ +#line 1119 "awkgram.y" /* yacc.c:1646 */ { (yyval) = optimize_assignment((yyvsp[0])); } -#line 2911 "awkgram.c" /* yacc.c:1646 */ +#line 2922 "awkgram.c" /* yacc.c:1646 */ break; case 66: -#line 1113 "awkgram.y" /* yacc.c:1646 */ +#line 1124 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2917 "awkgram.c" /* yacc.c:1646 */ +#line 2928 "awkgram.c" /* yacc.c:1646 */ break; case 67: -#line 1115 "awkgram.y" /* yacc.c:1646 */ +#line 1126 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2923 "awkgram.c" /* yacc.c:1646 */ +#line 2934 "awkgram.c" /* yacc.c:1646 */ break; case 68: -#line 1120 "awkgram.y" /* yacc.c:1646 */ +#line 1131 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2929 "awkgram.c" /* yacc.c:1646 */ +#line 2940 "awkgram.c" /* yacc.c:1646 */ break; case 69: -#line 1122 "awkgram.y" /* yacc.c:1646 */ +#line 1133 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[-1]) == NULL) (yyval) = list_create((yyvsp[0])); else (yyval) = list_prepend((yyvsp[-1]), (yyvsp[0])); } -#line 2940 "awkgram.c" /* yacc.c:1646 */ +#line 2951 "awkgram.c" /* yacc.c:1646 */ break; case 70: -#line 1129 "awkgram.y" /* yacc.c:1646 */ +#line 1140 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2946 "awkgram.c" /* yacc.c:1646 */ +#line 2957 "awkgram.c" /* yacc.c:1646 */ break; case 71: -#line 1134 "awkgram.y" /* yacc.c:1646 */ +#line 1145 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *casestmt = (yyvsp[0]); if ((yyvsp[0]) == NULL) @@ -2958,11 +2969,11 @@ regular_print: bcfree((yyvsp[-2])); (yyval) = (yyvsp[-4]); } -#line 2962 "awkgram.c" /* yacc.c:1646 */ +#line 2973 "awkgram.c" /* yacc.c:1646 */ break; case 72: -#line 1146 "awkgram.y" /* yacc.c:1646 */ +#line 1157 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *casestmt = (yyvsp[0]); if ((yyvsp[0]) == NULL) @@ -2973,17 +2984,17 @@ regular_print: (yyvsp[-3])->case_stmt = casestmt; (yyval) = (yyvsp[-3]); } -#line 2977 "awkgram.c" /* yacc.c:1646 */ +#line 2988 "awkgram.c" /* yacc.c:1646 */ break; case 73: -#line 1160 "awkgram.y" /* yacc.c:1646 */ +#line 1171 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2983 "awkgram.c" /* yacc.c:1646 */ +#line 2994 "awkgram.c" /* yacc.c:1646 */ break; case 74: -#line 1162 "awkgram.y" /* yacc.c:1646 */ +#line 1173 "awkgram.y" /* yacc.c:1646 */ { NODE *n = (yyvsp[0])->memory; (void) force_number(n); @@ -2991,71 +3002,71 @@ regular_print: bcfree((yyvsp[-1])); (yyval) = (yyvsp[0]); } -#line 2995 "awkgram.c" /* yacc.c:1646 */ +#line 3006 "awkgram.c" /* yacc.c:1646 */ break; case 75: -#line 1170 "awkgram.y" /* yacc.c:1646 */ +#line 1181 "awkgram.y" /* yacc.c:1646 */ { bcfree((yyvsp[-1])); (yyval) = (yyvsp[0]); } -#line 3004 "awkgram.c" /* yacc.c:1646 */ +#line 3015 "awkgram.c" /* yacc.c:1646 */ break; case 76: -#line 1175 "awkgram.y" /* yacc.c:1646 */ +#line 1186 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3010 "awkgram.c" /* yacc.c:1646 */ +#line 3021 "awkgram.c" /* yacc.c:1646 */ break; case 77: -#line 1177 "awkgram.y" /* yacc.c:1646 */ +#line 1188 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_push_re; (yyval) = (yyvsp[0]); } -#line 3019 "awkgram.c" /* yacc.c:1646 */ +#line 3030 "awkgram.c" /* yacc.c:1646 */ break; case 78: -#line 1185 "awkgram.y" /* yacc.c:1646 */ +#line 1196 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3025 "awkgram.c" /* yacc.c:1646 */ +#line 3036 "awkgram.c" /* yacc.c:1646 */ break; case 79: -#line 1187 "awkgram.y" /* yacc.c:1646 */ +#line 1198 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3031 "awkgram.c" /* yacc.c:1646 */ +#line 3042 "awkgram.c" /* yacc.c:1646 */ break; case 81: -#line 1197 "awkgram.y" /* yacc.c:1646 */ +#line 1208 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 3039 "awkgram.c" /* yacc.c:1646 */ +#line 3050 "awkgram.c" /* yacc.c:1646 */ break; case 82: -#line 1204 "awkgram.y" /* yacc.c:1646 */ +#line 1215 "awkgram.y" /* yacc.c:1646 */ { in_print = false; in_parens = 0; (yyval) = NULL; } -#line 3049 "awkgram.c" /* yacc.c:1646 */ +#line 3060 "awkgram.c" /* yacc.c:1646 */ break; case 83: -#line 1209 "awkgram.y" /* yacc.c:1646 */ +#line 1220 "awkgram.y" /* yacc.c:1646 */ { in_print = false; in_parens = 0; } -#line 3055 "awkgram.c" /* yacc.c:1646 */ +#line 3066 "awkgram.c" /* yacc.c:1646 */ break; case 84: -#line 1210 "awkgram.y" /* yacc.c:1646 */ +#line 1221 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[-2])->redir_type == redirect_twoway && (yyvsp[0])->lasti->opcode == Op_K_getline_redir @@ -3063,136 +3074,136 @@ regular_print: yyerror(_("multistage two-way pipelines don't work")); (yyval) = list_prepend((yyvsp[0]), (yyvsp[-2])); } -#line 3067 "awkgram.c" /* yacc.c:1646 */ +#line 3078 "awkgram.c" /* yacc.c:1646 */ break; case 85: -#line 1221 "awkgram.y" /* yacc.c:1646 */ +#line 1232 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_condition((yyvsp[-3]), (yyvsp[-5]), (yyvsp[0]), NULL, NULL); } -#line 3075 "awkgram.c" /* yacc.c:1646 */ +#line 3086 "awkgram.c" /* yacc.c:1646 */ break; case 86: -#line 1226 "awkgram.y" /* yacc.c:1646 */ +#line 1237 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_condition((yyvsp[-6]), (yyvsp[-8]), (yyvsp[-3]), (yyvsp[-2]), (yyvsp[0])); } -#line 3083 "awkgram.c" /* yacc.c:1646 */ +#line 3094 "awkgram.c" /* yacc.c:1646 */ break; case 91: -#line 1243 "awkgram.y" /* yacc.c:1646 */ +#line 1254 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3089 "awkgram.c" /* yacc.c:1646 */ +#line 3100 "awkgram.c" /* yacc.c:1646 */ break; case 92: -#line 1245 "awkgram.y" /* yacc.c:1646 */ +#line 1256 "awkgram.y" /* yacc.c:1646 */ { bcfree((yyvsp[-1])); (yyval) = (yyvsp[0]); } -#line 3098 "awkgram.c" /* yacc.c:1646 */ +#line 3109 "awkgram.c" /* yacc.c:1646 */ break; case 93: -#line 1253 "awkgram.y" /* yacc.c:1646 */ +#line 1264 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3104 "awkgram.c" /* yacc.c:1646 */ +#line 3115 "awkgram.c" /* yacc.c:1646 */ break; case 94: -#line 1255 "awkgram.y" /* yacc.c:1646 */ +#line 1266 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3110 "awkgram.c" /* yacc.c:1646 */ +#line 3121 "awkgram.c" /* yacc.c:1646 */ break; case 95: -#line 1260 "awkgram.y" /* yacc.c:1646 */ +#line 1271 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->param_count = 0; (yyval) = list_create((yyvsp[0])); } -#line 3119 "awkgram.c" /* yacc.c:1646 */ +#line 3130 "awkgram.c" /* yacc.c:1646 */ break; case 96: -#line 1265 "awkgram.y" /* yacc.c:1646 */ +#line 1276 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->param_count = (yyvsp[-2])->lasti->param_count + 1; (yyval) = list_append((yyvsp[-2]), (yyvsp[0])); yyerrok; } -#line 3129 "awkgram.c" /* yacc.c:1646 */ +#line 3140 "awkgram.c" /* yacc.c:1646 */ break; case 97: -#line 1271 "awkgram.y" /* yacc.c:1646 */ +#line 1282 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3135 "awkgram.c" /* yacc.c:1646 */ +#line 3146 "awkgram.c" /* yacc.c:1646 */ break; case 98: -#line 1273 "awkgram.y" /* yacc.c:1646 */ +#line 1284 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 3141 "awkgram.c" /* yacc.c:1646 */ +#line 3152 "awkgram.c" /* yacc.c:1646 */ break; case 99: -#line 1275 "awkgram.y" /* yacc.c:1646 */ +#line 1286 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-2]); } -#line 3147 "awkgram.c" /* yacc.c:1646 */ +#line 3158 "awkgram.c" /* yacc.c:1646 */ break; case 100: -#line 1281 "awkgram.y" /* yacc.c:1646 */ +#line 1292 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3153 "awkgram.c" /* yacc.c:1646 */ +#line 3164 "awkgram.c" /* yacc.c:1646 */ break; case 101: -#line 1283 "awkgram.y" /* yacc.c:1646 */ +#line 1294 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3159 "awkgram.c" /* yacc.c:1646 */ +#line 3170 "awkgram.c" /* yacc.c:1646 */ break; case 102: -#line 1288 "awkgram.y" /* yacc.c:1646 */ +#line 1299 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3165 "awkgram.c" /* yacc.c:1646 */ +#line 3176 "awkgram.c" /* yacc.c:1646 */ break; case 103: -#line 1290 "awkgram.y" /* yacc.c:1646 */ +#line 1301 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3171 "awkgram.c" /* yacc.c:1646 */ +#line 3182 "awkgram.c" /* yacc.c:1646 */ break; case 104: -#line 1295 "awkgram.y" /* yacc.c:1646 */ +#line 1306 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_expression_list(NULL, (yyvsp[0])); } -#line 3177 "awkgram.c" /* yacc.c:1646 */ +#line 3188 "awkgram.c" /* yacc.c:1646 */ break; case 105: -#line 1297 "awkgram.y" /* yacc.c:1646 */ +#line 1308 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_expression_list((yyvsp[-2]), (yyvsp[0])); yyerrok; } -#line 3186 "awkgram.c" /* yacc.c:1646 */ +#line 3197 "awkgram.c" /* yacc.c:1646 */ break; case 106: -#line 1302 "awkgram.y" /* yacc.c:1646 */ +#line 1313 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3192 "awkgram.c" /* yacc.c:1646 */ +#line 3203 "awkgram.c" /* yacc.c:1646 */ break; case 107: -#line 1304 "awkgram.y" /* yacc.c:1646 */ +#line 1315 "awkgram.y" /* yacc.c:1646 */ { /* * Returning the expression list instead of NULL lets @@ -3200,52 +3211,52 @@ regular_print: */ (yyval) = (yyvsp[-1]); } -#line 3204 "awkgram.c" /* yacc.c:1646 */ +#line 3215 "awkgram.c" /* yacc.c:1646 */ break; case 108: -#line 1312 "awkgram.y" /* yacc.c:1646 */ +#line 1323 "awkgram.y" /* yacc.c:1646 */ { /* Ditto */ (yyval) = mk_expression_list((yyvsp[-2]), (yyvsp[0])); } -#line 3213 "awkgram.c" /* yacc.c:1646 */ +#line 3224 "awkgram.c" /* yacc.c:1646 */ break; case 109: -#line 1317 "awkgram.y" /* yacc.c:1646 */ +#line 1328 "awkgram.y" /* yacc.c:1646 */ { /* Ditto */ (yyval) = (yyvsp[-2]); } -#line 3222 "awkgram.c" /* yacc.c:1646 */ +#line 3233 "awkgram.c" /* yacc.c:1646 */ break; case 110: -#line 1326 "awkgram.y" /* yacc.c:1646 */ +#line 1337 "awkgram.y" /* yacc.c:1646 */ { if (do_lint && (yyvsp[0])->lasti->opcode == Op_match_rec) lintwarn_ln((yyvsp[-1])->source_line, _("regular expression on right of assignment")); (yyval) = mk_assignment((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3233 "awkgram.c" /* yacc.c:1646 */ +#line 3244 "awkgram.c" /* yacc.c:1646 */ break; case 111: -#line 1333 "awkgram.y" /* yacc.c:1646 */ +#line 1344 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_boolean((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3239 "awkgram.c" /* yacc.c:1646 */ +#line 3250 "awkgram.c" /* yacc.c:1646 */ break; case 112: -#line 1335 "awkgram.y" /* yacc.c:1646 */ +#line 1346 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_boolean((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3245 "awkgram.c" /* yacc.c:1646 */ +#line 3256 "awkgram.c" /* yacc.c:1646 */ break; case 113: -#line 1337 "awkgram.y" /* yacc.c:1646 */ +#line 1348 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[-2])->lasti->opcode == Op_match_rec) warning_ln((yyvsp[-1])->source_line, @@ -3261,11 +3272,11 @@ regular_print: (yyval) = list_append(list_merge((yyvsp[-2]), (yyvsp[0])), (yyvsp[-1])); } } -#line 3265 "awkgram.c" /* yacc.c:1646 */ +#line 3276 "awkgram.c" /* yacc.c:1646 */ break; case 114: -#line 1353 "awkgram.y" /* yacc.c:1646 */ +#line 1364 "awkgram.y" /* yacc.c:1646 */ { if (do_lint_old) warning_ln((yyvsp[-1])->source_line, @@ -3275,91 +3286,91 @@ regular_print: (yyvsp[-1])->expr_count = 1; (yyval) = list_append(list_merge((yyvsp[-2]), (yyvsp[0])), (yyvsp[-1])); } -#line 3279 "awkgram.c" /* yacc.c:1646 */ +#line 3290 "awkgram.c" /* yacc.c:1646 */ break; case 115: -#line 1363 "awkgram.y" /* yacc.c:1646 */ +#line 1374 "awkgram.y" /* yacc.c:1646 */ { if (do_lint && (yyvsp[0])->lasti->opcode == Op_match_rec) lintwarn_ln((yyvsp[-1])->source_line, _("regular expression on right of comparison")); (yyval) = list_append(list_merge((yyvsp[-2]), (yyvsp[0])), (yyvsp[-1])); } -#line 3290 "awkgram.c" /* yacc.c:1646 */ +#line 3301 "awkgram.c" /* yacc.c:1646 */ break; case 116: -#line 1370 "awkgram.y" /* yacc.c:1646 */ +#line 1381 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_condition((yyvsp[-4]), (yyvsp[-3]), (yyvsp[-2]), (yyvsp[-1]), (yyvsp[0])); } -#line 3296 "awkgram.c" /* yacc.c:1646 */ +#line 3307 "awkgram.c" /* yacc.c:1646 */ break; case 117: -#line 1372 "awkgram.y" /* yacc.c:1646 */ +#line 1383 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3302 "awkgram.c" /* yacc.c:1646 */ +#line 3313 "awkgram.c" /* yacc.c:1646 */ break; case 118: -#line 1377 "awkgram.y" /* yacc.c:1646 */ +#line 1388 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3308 "awkgram.c" /* yacc.c:1646 */ +#line 3319 "awkgram.c" /* yacc.c:1646 */ break; case 119: -#line 1379 "awkgram.y" /* yacc.c:1646 */ +#line 1390 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3314 "awkgram.c" /* yacc.c:1646 */ +#line 3325 "awkgram.c" /* yacc.c:1646 */ break; case 120: -#line 1381 "awkgram.y" /* yacc.c:1646 */ +#line 1392 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_assign_quotient; (yyval) = (yyvsp[0]); } -#line 3323 "awkgram.c" /* yacc.c:1646 */ +#line 3334 "awkgram.c" /* yacc.c:1646 */ break; case 121: -#line 1389 "awkgram.y" /* yacc.c:1646 */ +#line 1400 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3329 "awkgram.c" /* yacc.c:1646 */ +#line 3340 "awkgram.c" /* yacc.c:1646 */ break; case 122: -#line 1391 "awkgram.y" /* yacc.c:1646 */ +#line 1402 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3335 "awkgram.c" /* yacc.c:1646 */ +#line 3346 "awkgram.c" /* yacc.c:1646 */ break; case 123: -#line 1396 "awkgram.y" /* yacc.c:1646 */ +#line 1407 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3341 "awkgram.c" /* yacc.c:1646 */ +#line 3352 "awkgram.c" /* yacc.c:1646 */ break; case 124: -#line 1398 "awkgram.y" /* yacc.c:1646 */ +#line 1409 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3347 "awkgram.c" /* yacc.c:1646 */ +#line 3358 "awkgram.c" /* yacc.c:1646 */ break; case 125: -#line 1403 "awkgram.y" /* yacc.c:1646 */ +#line 1414 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3353 "awkgram.c" /* yacc.c:1646 */ +#line 3364 "awkgram.c" /* yacc.c:1646 */ break; case 126: -#line 1405 "awkgram.y" /* yacc.c:1646 */ +#line 1416 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3359 "awkgram.c" /* yacc.c:1646 */ +#line 3370 "awkgram.c" /* yacc.c:1646 */ break; case 127: -#line 1407 "awkgram.y" /* yacc.c:1646 */ +#line 1418 "awkgram.y" /* yacc.c:1646 */ { int count = 2; bool is_simple_var = false; @@ -3406,47 +3417,47 @@ regular_print: max_args = count; } } -#line 3410 "awkgram.c" /* yacc.c:1646 */ +#line 3421 "awkgram.c" /* yacc.c:1646 */ break; case 129: -#line 1459 "awkgram.y" /* yacc.c:1646 */ +#line 1470 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3416 "awkgram.c" /* yacc.c:1646 */ +#line 3427 "awkgram.c" /* yacc.c:1646 */ break; case 130: -#line 1461 "awkgram.y" /* yacc.c:1646 */ +#line 1472 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3422 "awkgram.c" /* yacc.c:1646 */ +#line 3433 "awkgram.c" /* yacc.c:1646 */ break; case 131: -#line 1463 "awkgram.y" /* yacc.c:1646 */ +#line 1474 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3428 "awkgram.c" /* yacc.c:1646 */ +#line 3439 "awkgram.c" /* yacc.c:1646 */ break; case 132: -#line 1465 "awkgram.y" /* yacc.c:1646 */ +#line 1476 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3434 "awkgram.c" /* yacc.c:1646 */ +#line 3445 "awkgram.c" /* yacc.c:1646 */ break; case 133: -#line 1467 "awkgram.y" /* yacc.c:1646 */ +#line 1478 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3440 "awkgram.c" /* yacc.c:1646 */ +#line 3451 "awkgram.c" /* yacc.c:1646 */ break; case 134: -#line 1469 "awkgram.y" /* yacc.c:1646 */ +#line 1480 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3446 "awkgram.c" /* yacc.c:1646 */ +#line 3457 "awkgram.c" /* yacc.c:1646 */ break; case 135: -#line 1471 "awkgram.y" /* yacc.c:1646 */ +#line 1482 "awkgram.y" /* yacc.c:1646 */ { /* * In BEGINFILE/ENDFILE, allow `getline [var] < file' @@ -3460,29 +3471,29 @@ regular_print: _("non-redirected `getline' undefined inside END action")); (yyval) = mk_getline((yyvsp[-2]), (yyvsp[-1]), (yyvsp[0]), redirect_input); } -#line 3464 "awkgram.c" /* yacc.c:1646 */ +#line 3475 "awkgram.c" /* yacc.c:1646 */ break; case 136: -#line 1485 "awkgram.y" /* yacc.c:1646 */ +#line 1496 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_postincrement; (yyval) = mk_assignment((yyvsp[-1]), NULL, (yyvsp[0])); } -#line 3473 "awkgram.c" /* yacc.c:1646 */ +#line 3484 "awkgram.c" /* yacc.c:1646 */ break; case 137: -#line 1490 "awkgram.y" /* yacc.c:1646 */ +#line 1501 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_postdecrement; (yyval) = mk_assignment((yyvsp[-1]), NULL, (yyvsp[0])); } -#line 3482 "awkgram.c" /* yacc.c:1646 */ +#line 3493 "awkgram.c" /* yacc.c:1646 */ break; case 138: -#line 1495 "awkgram.y" /* yacc.c:1646 */ +#line 1506 "awkgram.y" /* yacc.c:1646 */ { if (do_lint_old) { warning_ln((yyvsp[-1])->source_line, @@ -3502,64 +3513,64 @@ regular_print: (yyval) = list_append(list_merge(t, (yyvsp[0])), (yyvsp[-1])); } } -#line 3506 "awkgram.c" /* yacc.c:1646 */ +#line 3517 "awkgram.c" /* yacc.c:1646 */ break; case 139: -#line 1520 "awkgram.y" /* yacc.c:1646 */ +#line 1531 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_getline((yyvsp[-1]), (yyvsp[0]), (yyvsp[-3]), (yyvsp[-2])->redir_type); bcfree((yyvsp[-2])); } -#line 3515 "awkgram.c" /* yacc.c:1646 */ +#line 3526 "awkgram.c" /* yacc.c:1646 */ break; case 140: -#line 1526 "awkgram.y" /* yacc.c:1646 */ +#line 1537 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3521 "awkgram.c" /* yacc.c:1646 */ +#line 3532 "awkgram.c" /* yacc.c:1646 */ break; case 141: -#line 1528 "awkgram.y" /* yacc.c:1646 */ +#line 1539 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3527 "awkgram.c" /* yacc.c:1646 */ +#line 3538 "awkgram.c" /* yacc.c:1646 */ break; case 142: -#line 1530 "awkgram.y" /* yacc.c:1646 */ +#line 1541 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3533 "awkgram.c" /* yacc.c:1646 */ +#line 3544 "awkgram.c" /* yacc.c:1646 */ break; case 143: -#line 1532 "awkgram.y" /* yacc.c:1646 */ +#line 1543 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3539 "awkgram.c" /* yacc.c:1646 */ +#line 3550 "awkgram.c" /* yacc.c:1646 */ break; case 144: -#line 1534 "awkgram.y" /* yacc.c:1646 */ +#line 1545 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3545 "awkgram.c" /* yacc.c:1646 */ +#line 3556 "awkgram.c" /* yacc.c:1646 */ break; case 145: -#line 1536 "awkgram.y" /* yacc.c:1646 */ +#line 1547 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3551 "awkgram.c" /* yacc.c:1646 */ +#line 3562 "awkgram.c" /* yacc.c:1646 */ break; case 146: -#line 1541 "awkgram.y" /* yacc.c:1646 */ +#line 1552 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_create((yyvsp[0])); } -#line 3559 "awkgram.c" /* yacc.c:1646 */ +#line 3570 "awkgram.c" /* yacc.c:1646 */ break; case 147: -#line 1545 "awkgram.y" /* yacc.c:1646 */ +#line 1556 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[0])->opcode == Op_match_rec) { (yyvsp[0])->opcode = Op_nomatch; @@ -3591,37 +3602,37 @@ regular_print: } } } -#line 3595 "awkgram.c" /* yacc.c:1646 */ +#line 3606 "awkgram.c" /* yacc.c:1646 */ break; case 148: -#line 1577 "awkgram.y" /* yacc.c:1646 */ +#line 1588 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 3601 "awkgram.c" /* yacc.c:1646 */ +#line 3612 "awkgram.c" /* yacc.c:1646 */ break; case 149: -#line 1579 "awkgram.y" /* yacc.c:1646 */ +#line 1590 "awkgram.y" /* yacc.c:1646 */ { (yyval) = snode((yyvsp[-1]), (yyvsp[-3])); if ((yyval) == NULL) YYABORT; } -#line 3611 "awkgram.c" /* yacc.c:1646 */ +#line 3622 "awkgram.c" /* yacc.c:1646 */ break; case 150: -#line 1585 "awkgram.y" /* yacc.c:1646 */ +#line 1596 "awkgram.y" /* yacc.c:1646 */ { (yyval) = snode((yyvsp[-1]), (yyvsp[-3])); if ((yyval) == NULL) YYABORT; } -#line 3621 "awkgram.c" /* yacc.c:1646 */ +#line 3632 "awkgram.c" /* yacc.c:1646 */ break; case 151: -#line 1591 "awkgram.y" /* yacc.c:1646 */ +#line 1602 "awkgram.y" /* yacc.c:1646 */ { static bool warned = false; @@ -3634,45 +3645,45 @@ regular_print: if ((yyval) == NULL) YYABORT; } -#line 3638 "awkgram.c" /* yacc.c:1646 */ +#line 3649 "awkgram.c" /* yacc.c:1646 */ break; case 154: -#line 1606 "awkgram.y" /* yacc.c:1646 */ +#line 1617 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[-1])->opcode = Op_preincrement; (yyval) = mk_assignment((yyvsp[0]), NULL, (yyvsp[-1])); } -#line 3647 "awkgram.c" /* yacc.c:1646 */ +#line 3658 "awkgram.c" /* yacc.c:1646 */ break; case 155: -#line 1611 "awkgram.y" /* yacc.c:1646 */ +#line 1622 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[-1])->opcode = Op_predecrement; (yyval) = mk_assignment((yyvsp[0]), NULL, (yyvsp[-1])); } -#line 3656 "awkgram.c" /* yacc.c:1646 */ +#line 3667 "awkgram.c" /* yacc.c:1646 */ break; case 156: -#line 1616 "awkgram.y" /* yacc.c:1646 */ +#line 1627 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_create((yyvsp[0])); } -#line 3664 "awkgram.c" /* yacc.c:1646 */ +#line 3675 "awkgram.c" /* yacc.c:1646 */ break; case 157: -#line 1620 "awkgram.y" /* yacc.c:1646 */ +#line 1631 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_create((yyvsp[0])); } -#line 3672 "awkgram.c" /* yacc.c:1646 */ +#line 3683 "awkgram.c" /* yacc.c:1646 */ break; case 158: -#line 1624 "awkgram.y" /* yacc.c:1646 */ +#line 1635 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[0])->lasti->opcode == Op_push_i && ((yyvsp[0])->lasti->memory->flags & (STRCUR|STRING)) == 0 @@ -3687,11 +3698,11 @@ regular_print: (yyval) = list_append((yyvsp[0]), (yyvsp[-1])); } } -#line 3691 "awkgram.c" /* yacc.c:1646 */ +#line 3702 "awkgram.c" /* yacc.c:1646 */ break; case 159: -#line 1639 "awkgram.y" /* yacc.c:1646 */ +#line 1650 "awkgram.y" /* yacc.c:1646 */ { /* * was: $$ = $2 @@ -3701,20 +3712,20 @@ regular_print: (yyvsp[-1])->memory = make_number(0.0); (yyval) = list_append((yyvsp[0]), (yyvsp[-1])); } -#line 3705 "awkgram.c" /* yacc.c:1646 */ +#line 3716 "awkgram.c" /* yacc.c:1646 */ break; case 160: -#line 1652 "awkgram.y" /* yacc.c:1646 */ +#line 1663 "awkgram.y" /* yacc.c:1646 */ { func_use((yyvsp[0])->lasti->func_name, FUNC_USE); (yyval) = (yyvsp[0]); } -#line 3714 "awkgram.c" /* yacc.c:1646 */ +#line 3725 "awkgram.c" /* yacc.c:1646 */ break; case 161: -#line 1657 "awkgram.y" /* yacc.c:1646 */ +#line 1668 "awkgram.y" /* yacc.c:1646 */ { /* indirect function call */ INSTRUCTION *f, *t; @@ -3747,11 +3758,11 @@ regular_print: (yyval) = list_prepend((yyvsp[0]), t); } -#line 3751 "awkgram.c" /* yacc.c:1646 */ +#line 3762 "awkgram.c" /* yacc.c:1646 */ break; case 162: -#line 1693 "awkgram.y" /* yacc.c:1646 */ +#line 1704 "awkgram.y" /* yacc.c:1646 */ { param_sanity((yyvsp[-1])); (yyvsp[-3])->opcode = Op_func_call; @@ -3765,49 +3776,49 @@ regular_print: (yyval) = list_append(t, (yyvsp[-3])); } } -#line 3769 "awkgram.c" /* yacc.c:1646 */ +#line 3780 "awkgram.c" /* yacc.c:1646 */ break; case 163: -#line 1710 "awkgram.y" /* yacc.c:1646 */ +#line 1721 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3775 "awkgram.c" /* yacc.c:1646 */ +#line 3786 "awkgram.c" /* yacc.c:1646 */ break; case 164: -#line 1712 "awkgram.y" /* yacc.c:1646 */ +#line 1723 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3781 "awkgram.c" /* yacc.c:1646 */ +#line 3792 "awkgram.c" /* yacc.c:1646 */ break; case 165: -#line 1717 "awkgram.y" /* yacc.c:1646 */ +#line 1728 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3787 "awkgram.c" /* yacc.c:1646 */ +#line 3798 "awkgram.c" /* yacc.c:1646 */ break; case 166: -#line 1719 "awkgram.y" /* yacc.c:1646 */ +#line 1730 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 3793 "awkgram.c" /* yacc.c:1646 */ +#line 3804 "awkgram.c" /* yacc.c:1646 */ break; case 167: -#line 1724 "awkgram.y" /* yacc.c:1646 */ +#line 1735 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3799 "awkgram.c" /* yacc.c:1646 */ +#line 3810 "awkgram.c" /* yacc.c:1646 */ break; case 168: -#line 1726 "awkgram.y" /* yacc.c:1646 */ +#line 1737 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_merge((yyvsp[-1]), (yyvsp[0])); } -#line 3807 "awkgram.c" /* yacc.c:1646 */ +#line 3818 "awkgram.c" /* yacc.c:1646 */ break; case 169: -#line 1733 "awkgram.y" /* yacc.c:1646 */ +#line 1744 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *ip = (yyvsp[0])->lasti; int count = ip->sub_count; /* # of SUBSEP-seperated expressions */ @@ -3821,11 +3832,11 @@ regular_print: sub_counter++; /* count # of dimensions */ (yyval) = (yyvsp[0]); } -#line 3825 "awkgram.c" /* yacc.c:1646 */ +#line 3836 "awkgram.c" /* yacc.c:1646 */ break; case 170: -#line 1750 "awkgram.y" /* yacc.c:1646 */ +#line 1761 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *t = (yyvsp[-1]); if ((yyvsp[-1]) == NULL) { @@ -3839,31 +3850,31 @@ regular_print: (yyvsp[0])->sub_count = count_expressions(&t, false); (yyval) = list_append(t, (yyvsp[0])); } -#line 3843 "awkgram.c" /* yacc.c:1646 */ +#line 3854 "awkgram.c" /* yacc.c:1646 */ break; case 171: -#line 1767 "awkgram.y" /* yacc.c:1646 */ +#line 1778 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3849 "awkgram.c" /* yacc.c:1646 */ +#line 3860 "awkgram.c" /* yacc.c:1646 */ break; case 172: -#line 1769 "awkgram.y" /* yacc.c:1646 */ +#line 1780 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_merge((yyvsp[-1]), (yyvsp[0])); } -#line 3857 "awkgram.c" /* yacc.c:1646 */ +#line 3868 "awkgram.c" /* yacc.c:1646 */ break; case 173: -#line 1776 "awkgram.y" /* yacc.c:1646 */ +#line 1787 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 3863 "awkgram.c" /* yacc.c:1646 */ +#line 3874 "awkgram.c" /* yacc.c:1646 */ break; case 174: -#line 1781 "awkgram.y" /* yacc.c:1646 */ +#line 1792 "awkgram.y" /* yacc.c:1646 */ { char *var_name = (yyvsp[0])->lextok; @@ -3871,22 +3882,22 @@ regular_print: (yyvsp[0])->memory = variable((yyvsp[0])->source_line, var_name, Node_var_new); (yyval) = list_create((yyvsp[0])); } -#line 3875 "awkgram.c" /* yacc.c:1646 */ +#line 3886 "awkgram.c" /* yacc.c:1646 */ break; case 175: -#line 1789 "awkgram.y" /* yacc.c:1646 */ +#line 1800 "awkgram.y" /* yacc.c:1646 */ { char *arr = (yyvsp[-1])->lextok; (yyvsp[-1])->memory = variable((yyvsp[-1])->source_line, arr, Node_var_new); (yyvsp[-1])->opcode = Op_push_array; (yyval) = list_prepend((yyvsp[0]), (yyvsp[-1])); } -#line 3886 "awkgram.c" /* yacc.c:1646 */ +#line 3897 "awkgram.c" /* yacc.c:1646 */ break; case 176: -#line 1799 "awkgram.y" /* yacc.c:1646 */ +#line 1810 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *ip = (yyvsp[0])->nexti; if (ip->opcode == Op_push @@ -3898,73 +3909,73 @@ regular_print: } else (yyval) = (yyvsp[0]); } -#line 3902 "awkgram.c" /* yacc.c:1646 */ +#line 3913 "awkgram.c" /* yacc.c:1646 */ break; case 177: -#line 1811 "awkgram.y" /* yacc.c:1646 */ +#line 1822 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_append((yyvsp[-1]), (yyvsp[-2])); if ((yyvsp[0]) != NULL) mk_assignment((yyvsp[-1]), NULL, (yyvsp[0])); } -#line 3912 "awkgram.c" /* yacc.c:1646 */ +#line 3923 "awkgram.c" /* yacc.c:1646 */ break; case 178: -#line 1820 "awkgram.y" /* yacc.c:1646 */ +#line 1831 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_postincrement; } -#line 3920 "awkgram.c" /* yacc.c:1646 */ +#line 3931 "awkgram.c" /* yacc.c:1646 */ break; case 179: -#line 1824 "awkgram.y" /* yacc.c:1646 */ +#line 1835 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_postdecrement; } -#line 3928 "awkgram.c" /* yacc.c:1646 */ +#line 3939 "awkgram.c" /* yacc.c:1646 */ break; case 180: -#line 1827 "awkgram.y" /* yacc.c:1646 */ +#line 1838 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3934 "awkgram.c" /* yacc.c:1646 */ +#line 3945 "awkgram.c" /* yacc.c:1646 */ break; case 182: -#line 1835 "awkgram.y" /* yacc.c:1646 */ +#line 1846 "awkgram.y" /* yacc.c:1646 */ { yyerrok; } -#line 3940 "awkgram.c" /* yacc.c:1646 */ +#line 3951 "awkgram.c" /* yacc.c:1646 */ break; case 183: -#line 1839 "awkgram.y" /* yacc.c:1646 */ +#line 1850 "awkgram.y" /* yacc.c:1646 */ { yyerrok; } -#line 3946 "awkgram.c" /* yacc.c:1646 */ +#line 3957 "awkgram.c" /* yacc.c:1646 */ break; case 186: -#line 1848 "awkgram.y" /* yacc.c:1646 */ +#line 1859 "awkgram.y" /* yacc.c:1646 */ { yyerrok; } -#line 3952 "awkgram.c" /* yacc.c:1646 */ +#line 3963 "awkgram.c" /* yacc.c:1646 */ break; case 187: -#line 1852 "awkgram.y" /* yacc.c:1646 */ +#line 1863 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); yyerrok; } -#line 3958 "awkgram.c" /* yacc.c:1646 */ +#line 3969 "awkgram.c" /* yacc.c:1646 */ break; case 188: -#line 1856 "awkgram.y" /* yacc.c:1646 */ +#line 1867 "awkgram.y" /* yacc.c:1646 */ { yyerrok; } -#line 3964 "awkgram.c" /* yacc.c:1646 */ +#line 3975 "awkgram.c" /* yacc.c:1646 */ break; -#line 3968 "awkgram.c" /* yacc.c:1646 */ +#line 3979 "awkgram.c" /* yacc.c:1646 */ default: break; } /* User semantic actions sometimes alter yychar, and that requires @@ -4192,7 +4203,7 @@ yyreturn: #endif return yyresult; } -#line 1858 "awkgram.y" /* yacc.c:1906 */ +#line 1869 "awkgram.y" /* yacc.c:1906 */ struct token { @@ -4322,7 +4333,6 @@ static const struct token tokentab[] = { {"xor", Op_builtin, LEX_BUILTIN, GAWKX, do_xor, MPF(xor)}, }; -#if MBS_SUPPORT /* Variable containing the current shift state. */ static mbstate_t cur_mbstate; /* Ring buffer containing current characters. */ @@ -4334,10 +4344,6 @@ static int cur_ring_idx; /* This macro means that last nextc() return a singlebyte character or 1st byte of a multibyte character. */ #define nextc_is_1stbyte (cur_char_ring[cur_ring_idx] == 1) -#else /* MBS_SUPPORT */ -/* a dummy */ -#define nextc_is_1stbyte 1 -#endif /* MBS_SUPPORT */ /* getfname --- return name of a builtin function (for pretty printing) */ @@ -4626,11 +4632,9 @@ mk_program() cp = end_block; else cp = list_merge(begin_block, end_block); - /* - * We don't need to clear the comment variables - * since they're not used anymore after this - * function is called. - */ + if (program_comment != NULL) { + (void) list_prepend(cp, program_comment); + } if (comment != NULL) (void) list_append(cp, comment); (void) list_append(cp, ip_atexit); @@ -4678,6 +4682,10 @@ out: /* delete the Op_list, not needed */ tmp = cp->nexti; bcfree(cp); + /* these variables are not used again but zap them anyway. */ + comment = NULL; + function_comment = NULL; + program_comment = NULL; return tmp; #undef begin_block @@ -5239,8 +5247,6 @@ check_bad_char(int c) /* nextc --- get the next input character */ -#if MBS_SUPPORT - static int nextc(bool check_for_bad) { @@ -5311,43 +5317,40 @@ again: } } -#else /* MBS_SUPPORT */ - -int -nextc(bool check_for_bad) -{ - do { - if (lexeof) - return END_FILE; - if (lexptr && lexptr < lexend) { - if (check_for_bad) - check_bad_char(*lexptr); - return ((int) (unsigned char) *lexptr++); - } - } while (get_src_buf()); - return END_SRC; -} - -#endif /* MBS_SUPPORT */ - /* pushback --- push a character back on the input */ static inline void pushback(void) { -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) cur_ring_idx = (cur_ring_idx == 0)? RING_BUFFER_SIZE - 1 : cur_ring_idx - 1; -#endif (! lexeof && lexptr && lexptr > lexptr_begin ? lexptr-- : lexptr); } +/* check_comment --- check for block comment */ -/* get_comment --- collect comment text */ +void +check_comment(void) +{ + if (comment != NULL) { + if (first_rule) { + program_comment = comment; + } else + block_comment = comment; + comment = NULL; + } + first_rule = false; +} + +/* + * get_comment --- collect comment text. + * Flag = EOL_COMMENT for end-of-line comments. + * Flag = FULL_COMMENT for self-contained comments. + */ int -get_comment(void) +get_comment(int flag) { int c; int sl; @@ -5359,6 +5362,12 @@ get_comment(void) while ((c = nextc(false)) != '\n' && c != END_FILE) { tokadd(c); } + if (flag == EOL_COMMENT) { + /* comment at end of line. */ + if (c == '\n') + tokadd(c); + break; + } if (c == '\n') { tokadd(c); sourceline++; @@ -5373,6 +5382,7 @@ get_comment(void) break; else if (c != '#') { pushback(); + sourceline--; break; } else tokadd(c); @@ -5382,6 +5392,7 @@ get_comment(void) comment = bcalloc(Op_comment, 1, sl); comment->source_file = source; comment->memory = make_str_node(tokstart, tok - tokstart, 0); + comment->memory->comment_type = flag; return c; } @@ -5433,7 +5444,7 @@ allow_newline(void) if (c == '#') { if (do_pretty_print && ! do_profile) { /* collect comment byte code iff doing pretty print but not profiling. */ - c = get_comment(); + c = get_comment(EOL_COMMENT); } else { while ((c = nextc(false)) != '\n' && c != END_FILE) continue; @@ -5627,9 +5638,7 @@ retry: thisline = NULL; tok = tokstart; -#if MBS_SUPPORT if (gawk_mb_cur_max == 1 || nextc_is_1stbyte) -#endif switch (c) { case END_SRC: return 0; @@ -5647,7 +5656,10 @@ retry: * Collect comment byte code iff doing pretty print * but not profiling. */ - c = get_comment(); + if (lasttok == NEWLINE || lasttok == 0) + c = get_comment(FULL_COMMENT); + else + c = get_comment(EOL_COMMENT); if (c == END_FILE) return lasttok = NEWLINE_EOF; @@ -5684,7 +5696,7 @@ retry: _("use of `\\ #...' line continuation is not portable")); } if (do_pretty_print && ! do_profile) - c = get_comment(); + c = get_comment(EOL_COMMENT); else { while ((c = nextc(false)) != '\n') if (c == END_FILE) @@ -7539,7 +7551,11 @@ append_rule(INSTRUCTION *pattern, INSTRUCTION *action) (rp + 1)->lasti = action->lasti; (rp + 2)->first_line = pattern->source_line; (rp + 2)->last_line = lastline; - ip = list_prepend(action, rp); + if (block_comment != NULL) { + ip = list_prepend(list_prepend(action, block_comment), rp); + block_comment = NULL; + } else + ip = list_prepend(action, rp); } else { rp = bcalloc(Op_rule, 3, 0); @@ -88,6 +88,7 @@ static void check_funcs(void); static ssize_t read_one_line(int fd, void *buffer, size_t count); static int one_line_close(int fd); static void split_comment(void); +static void check_comment(void); static bool want_source = false; static bool want_regexp = false; /* lexical scanning kludge */ @@ -151,8 +152,10 @@ INSTRUCTION *main_beginfile; static INSTRUCTION *comment = NULL; static INSTRUCTION *program_comment = NULL; static INSTRUCTION *function_comment = NULL; +static INSTRUCTION *block_comment = NULL; static bool func_first = true; +static bool first_rule = true; static inline INSTRUCTION *list_create(INSTRUCTION *x); static inline INSTRUCTION *list_append(INSTRUCTION *l, INSTRUCTION *x); @@ -335,7 +338,11 @@ pattern ($1->nexti + 1)->condpair_left = $1->lasti; ($1->nexti + 1)->condpair_right = $4->lasti; } - $$ = list_append(list_merge($1, $4), tp); + if (comment != NULL) { + $$ = list_append(list_merge(list_prepend($1, comment), $4), tp); + comment = NULL; + } else + $$ = list_append(list_merge($1, $4), tp); rule = Rule; } | LEX_BEGIN @@ -349,6 +356,7 @@ pattern $1->in_rule = rule = BEGIN; $1->source_file = source; + check_comment(); $$ = $1; } | LEX_END @@ -362,6 +370,7 @@ pattern $1->in_rule = rule = END; $1->source_file = source; + check_comment(); $$ = $1; } | LEX_BEGINFILE @@ -369,6 +378,7 @@ pattern func_first = false; $1->in_rule = rule = BEGINFILE; $1->source_file = source; + check_comment(); $$ = $1; } | LEX_ENDFILE @@ -376,6 +386,7 @@ pattern func_first = false; $1->in_rule = rule = ENDFILE; $1->source_file = source; + check_comment(); $$ = $1; } ; @@ -1984,7 +1995,6 @@ static const struct token tokentab[] = { {"xor", Op_builtin, LEX_BUILTIN, GAWKX, do_xor, MPF(xor)}, }; -#if MBS_SUPPORT /* Variable containing the current shift state. */ static mbstate_t cur_mbstate; /* Ring buffer containing current characters. */ @@ -1996,10 +2006,6 @@ static int cur_ring_idx; /* This macro means that last nextc() return a singlebyte character or 1st byte of a multibyte character. */ #define nextc_is_1stbyte (cur_char_ring[cur_ring_idx] == 1) -#else /* MBS_SUPPORT */ -/* a dummy */ -#define nextc_is_1stbyte 1 -#endif /* MBS_SUPPORT */ /* getfname --- return name of a builtin function (for pretty printing) */ @@ -2288,11 +2294,9 @@ mk_program() cp = end_block; else cp = list_merge(begin_block, end_block); - /* - * We don't need to clear the comment variables - * since they're not used anymore after this - * function is called. - */ + if (program_comment != NULL) { + (void) list_prepend(cp, program_comment); + } if (comment != NULL) (void) list_append(cp, comment); (void) list_append(cp, ip_atexit); @@ -2340,6 +2344,10 @@ out: /* delete the Op_list, not needed */ tmp = cp->nexti; bcfree(cp); + /* these variables are not used again but zap them anyway. */ + comment = NULL; + function_comment = NULL; + program_comment = NULL; return tmp; #undef begin_block @@ -2901,8 +2909,6 @@ check_bad_char(int c) /* nextc --- get the next input character */ -#if MBS_SUPPORT - static int nextc(bool check_for_bad) { @@ -2973,43 +2979,40 @@ again: } } -#else /* MBS_SUPPORT */ - -int -nextc(bool check_for_bad) -{ - do { - if (lexeof) - return END_FILE; - if (lexptr && lexptr < lexend) { - if (check_for_bad) - check_bad_char(*lexptr); - return ((int) (unsigned char) *lexptr++); - } - } while (get_src_buf()); - return END_SRC; -} - -#endif /* MBS_SUPPORT */ - /* pushback --- push a character back on the input */ static inline void pushback(void) { -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) cur_ring_idx = (cur_ring_idx == 0)? RING_BUFFER_SIZE - 1 : cur_ring_idx - 1; -#endif (! lexeof && lexptr && lexptr > lexptr_begin ? lexptr-- : lexptr); } +/* check_comment --- check for block comment */ -/* get_comment --- collect comment text */ +void +check_comment(void) +{ + if (comment != NULL) { + if (first_rule) { + program_comment = comment; + } else + block_comment = comment; + comment = NULL; + } + first_rule = false; +} + +/* + * get_comment --- collect comment text. + * Flag = EOL_COMMENT for end-of-line comments. + * Flag = FULL_COMMENT for self-contained comments. + */ int -get_comment(void) +get_comment(int flag) { int c; int sl; @@ -3021,6 +3024,12 @@ get_comment(void) while ((c = nextc(false)) != '\n' && c != END_FILE) { tokadd(c); } + if (flag == EOL_COMMENT) { + /* comment at end of line. */ + if (c == '\n') + tokadd(c); + break; + } if (c == '\n') { tokadd(c); sourceline++; @@ -3035,6 +3044,7 @@ get_comment(void) break; else if (c != '#') { pushback(); + sourceline--; break; } else tokadd(c); @@ -3044,6 +3054,7 @@ get_comment(void) comment = bcalloc(Op_comment, 1, sl); comment->source_file = source; comment->memory = make_str_node(tokstart, tok - tokstart, 0); + comment->memory->comment_type = flag; return c; } @@ -3095,7 +3106,7 @@ allow_newline(void) if (c == '#') { if (do_pretty_print && ! do_profile) { /* collect comment byte code iff doing pretty print but not profiling. */ - c = get_comment(); + c = get_comment(EOL_COMMENT); } else { while ((c = nextc(false)) != '\n' && c != END_FILE) continue; @@ -3289,9 +3300,7 @@ retry: thisline = NULL; tok = tokstart; -#if MBS_SUPPORT if (gawk_mb_cur_max == 1 || nextc_is_1stbyte) -#endif switch (c) { case END_SRC: return 0; @@ -3309,7 +3318,10 @@ retry: * Collect comment byte code iff doing pretty print * but not profiling. */ - c = get_comment(); + if (lasttok == NEWLINE || lasttok == 0) + c = get_comment(FULL_COMMENT); + else + c = get_comment(EOL_COMMENT); if (c == END_FILE) return lasttok = NEWLINE_EOF; @@ -3346,7 +3358,7 @@ retry: _("use of `\\ #...' line continuation is not portable")); } if (do_pretty_print && ! do_profile) - c = get_comment(); + c = get_comment(EOL_COMMENT); else { while ((c = nextc(false)) != '\n') if (c == END_FILE) @@ -5201,7 +5213,11 @@ append_rule(INSTRUCTION *pattern, INSTRUCTION *action) (rp + 1)->lasti = action->lasti; (rp + 2)->first_line = pattern->source_line; (rp + 2)->last_line = lastline; - ip = list_prepend(action, rp); + if (block_comment != NULL) { + ip = list_prepend(list_prepend(action, block_comment), rp); + block_comment = NULL; + } else + ip = list_prepend(action, rp); } else { rp = bcalloc(Op_rule, 3, 0); diff --git a/awklib/Makefile.in b/awklib/Makefile.in index 5a4087e5..b4b887a1 100644 --- a/awklib/Makefile.in +++ b/awklib/Makefile.in @@ -248,6 +248,7 @@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ POSUB = @POSUB@ +SED = @SED@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ SOCKET_LIBS = @SOCKET_LIBS@ diff --git a/awklib/eg/lib/ftrans.awk b/awklib/eg/lib/ftrans.awk index 2fec27ef..6461efff 100644 --- a/awklib/eg/lib/ftrans.awk +++ b/awklib/eg/lib/ftrans.awk @@ -1,4 +1,4 @@ -# ftrans.awk --- handle data file transitions +# ftrans.awk --- handle datafile transitions # # user supplies beginfile() and endfile() functions # diff --git a/awklib/eg/lib/strtonum.awk b/awklib/eg/lib/strtonum.awk index cd56a449..783496e4 100644 --- a/awklib/eg/lib/strtonum.awk +++ b/awklib/eg/lib/strtonum.awk @@ -52,7 +52,7 @@ function mystrtonum(str, ret, n, i, k, c) # a[6] = "1.e3" # a[7] = "1.32" # a[8] = "1.32E2" -# +# # for (i = 1; i in a; i++) # print a[i], strtonum(a[i]), mystrtonum(a[i]) # } diff --git a/awklib/eg/prog/indirectcall.awk b/awklib/eg/prog/indirectcall.awk index 3ecb2887..165b022a 100644 --- a/awklib/eg/prog/indirectcall.awk +++ b/awklib/eg/prog/indirectcall.awk @@ -27,7 +27,7 @@ function do_sort(first, last, compare, data, i, retval) retval = data[1] for (i = 2; i in data; i++) retval = retval " " data[i] - + return retval } # sort --- sort the data in ascending order and return it as a string diff --git a/awklib/eg/prog/split.awk b/awklib/eg/prog/split.awk index 6a7198f6..b878fa50 100644 --- a/awklib/eg/prog/split.awk +++ b/awklib/eg/prog/split.awk @@ -22,7 +22,7 @@ BEGIN { } # test argv in case reading from stdin instead of file if (i in ARGV) - i++ # skip data file name + i++ # skip datafile name if (i in ARGV) { outfile = ARGV[i] ARGV[i] = "" @@ -247,7 +247,6 @@ do_fflush(int nargs) return make_number((AWKNUM) status); } -#if MBS_SUPPORT /* strncasecmpmbs --- like strncasecmp (multibyte string version) */ int @@ -327,14 +326,6 @@ index_multibyte_buffer(char* src, char* dest, int len) dest[idx] = mbclen; } } -#else -/* a dummy function */ -static void -index_multibyte_buffer(char* src ATTRIBUTE_UNUSED, char* dest ATTRIBUTE_UNUSED, int len ATTRIBUTE_UNUSED) -{ - cant_happen(); -} -#endif /* do_index --- find index of a string */ @@ -345,7 +336,6 @@ do_index(int nargs) const char *p1, *p2; size_t l1, l2; long ret; -#if MBS_SUPPORT bool do_single_byte = false; mbstate_t mbs1, mbs2; @@ -353,7 +343,6 @@ do_index(int nargs) memset(& mbs1, 0, sizeof(mbstate_t)); memset(& mbs2, 0, sizeof(mbstate_t)); } -#endif POP_TWO_SCALARS(s1, s2); @@ -383,7 +372,6 @@ do_index(int nargs) goto out; } -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { s1 = force_wstring(s1); s2 = force_wstring(s2); @@ -394,14 +382,12 @@ do_index(int nargs) do_single_byte = ((s1->wstlen == 0 && s1->stlen > 0) || (s2->wstlen == 0 && s2->stlen > 0)); } -#endif /* IGNORECASE will already be false if posix */ if (IGNORECASE) { while (l1 > 0) { if (l2 > l1) break; -#if MBS_SUPPORT if (! do_single_byte && gawk_mb_cur_max > 1) { const wchar_t *pos; @@ -412,21 +398,18 @@ do_index(int nargs) ret = pos - s1->wstptr + 1; /* 1-based */ goto out; } else { -#endif - /* - * Could use tolower(*p1) == tolower(*p2) here. - * See discussion in eval.c as to why not. - */ - if (casetable[(unsigned char)*p1] == casetable[(unsigned char)*p2] - && (l2 == 1 || strncasecmp(p1, p2, l2) == 0)) { - ret = 1 + s1->stlen - l1; - break; - } - l1--; - p1++; -#if MBS_SUPPORT + /* + * Could use tolower(*p1) == tolower(*p2) here. + * See discussion in eval.c as to why not. + */ + if (casetable[(unsigned char)*p1] == casetable[(unsigned char)*p2] + && (l2 == 1 || strncasecmp(p1, p2, l2) == 0)) { + ret = 1 + s1->stlen - l1; + break; + } + l1--; + p1++; } -#endif } } else { while (l1 > 0) { @@ -437,7 +420,6 @@ do_index(int nargs) ret = 1 + s1->stlen - l1; break; } -#if MBS_SUPPORT if (! do_single_byte && gawk_mb_cur_max > 1) { const wchar_t *pos; @@ -451,10 +433,6 @@ do_index(int nargs) l1--; p1++; } -#else - l1--; - p1++; -#endif } } out: @@ -544,7 +522,6 @@ do_length(int nargs) lintwarn(_("length: received non-string argument")); tmp = force_string(tmp); -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { tmp = force_wstring(tmp); len = tmp->wstlen; @@ -555,7 +532,6 @@ do_length(int nargs) if (len == 0 && tmp->stlen > 0) len = tmp->stlen; } else -#endif len = tmp->stlen; DEREF(tmp); @@ -1058,7 +1034,6 @@ check_pos: (void) force_number(arg); if ((arg->flags & NUMBER) != 0) { uval = get_number_uj(arg); -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { char buf[100]; wchar_t wc; @@ -1099,7 +1074,7 @@ out0: ; /* else, fall through */ -#endif + cpbuf[0] = uval; prec = 1; cp = cpbuf; @@ -1113,7 +1088,6 @@ out0: */ cp = arg->stptr; prec = 1; -#if MBS_SUPPORT /* * First character can be multiple bytes if * it's a multibyte character. Grr. @@ -1131,7 +1105,6 @@ out0: fw += count - 1; } } -#endif goto pr_tail; case 's': need_format = false; @@ -1805,13 +1778,11 @@ do_substr(int nargs) if (nargs == 2) { /* third arg. missing */ /* use remainder of string */ length = t1->stlen - indx; /* default to bytes */ -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { t1 = force_wstring(t1); if (t1->wstlen > 0) /* use length of wide char string if we have one */ length = t1->wstlen - indx; } -#endif d_length = length; /* set here in case used in diagnostics, below */ } @@ -1824,12 +1795,10 @@ do_substr(int nargs) } /* get total len of input string, for following checks */ -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { t1 = force_wstring(t1); src_len = t1->wstlen; } else -#endif src_len = t1->stlen; if (indx >= src_len) { @@ -1847,7 +1816,6 @@ do_substr(int nargs) length = src_len - indx; } -#if MBS_SUPPORT /* force_wstring() already called */ if (gawk_mb_cur_max == 1 || t1->wstlen == t1->stlen) /* single byte case */ @@ -1877,9 +1845,6 @@ do_substr(int nargs) *cp = '\0'; r = make_str_node(substr, cp - substr, ALREADY_MALLOCED); } -#else - r = make_string(t1->stptr + indx, length); -#endif DEREF(t1); return r; @@ -2211,7 +2176,6 @@ do_print_rec(int nargs, int redirtype) rp->output.gawk_fflush(rp->output.fp, rp->output.opaque); } -#if MBS_SUPPORT /* is_wupper --- function version of iswupper for passing function pointers */ @@ -2276,7 +2240,6 @@ wide_tolower(wchar_t *wstr, size_t wlen) { wide_change_case(wstr, wlen, is_wupper, to_wlower); } -#endif /* do_tolower --- lower case a string */ @@ -2299,14 +2262,11 @@ do_tolower(int nargs) cp < cp2; cp++) if (isupper(*cp)) *cp = tolower(*cp); - } -#if MBS_SUPPORT - else { + } else { force_wstring(t2); wide_tolower(t2->wstptr, t2->wstlen); wstr2str(t2); } -#endif DEREF(t1); return t2; @@ -2333,14 +2293,11 @@ do_toupper(int nargs) cp < cp2; cp++) if (islower(*cp)) *cp = toupper(*cp); - } -#if MBS_SUPPORT - else { + } else { force_wstring(t2); wide_toupper(t2->wstptr, t2->wstlen); wstr2str(t2); } -#endif DEREF(t1); return t2; @@ -2551,13 +2508,12 @@ do_match(int nargs) size_t *wc_indices = NULL; rlength = REEND(rp, t1->stptr) - RESTART(rp, t1->stptr); /* byte length */ -#if MBS_SUPPORT if (rlength > 0 && gawk_mb_cur_max > 1) { t1 = str2wstr(t1, & wc_indices); rlength = wc_indices[rstart + rlength - 1] - wc_indices[rstart] + 1; rstart = wc_indices[rstart]; } -#endif + rstart++; /* now it's 1-based indexing */ /* Build the array only if the caller wants the optional subpatterns */ @@ -2579,12 +2535,10 @@ do_match(int nargs) start = t1->stptr + s; subpat_start = s; subpat_len = len = SUBPATEND(rp, t1->stptr, ii) - s; -#if MBS_SUPPORT if (len > 0 && gawk_mb_cur_max > 1) { subpat_start = wc_indices[s]; subpat_len = wc_indices[s + len - 1] - subpat_start + 1; } -#endif it = make_string(start, len); it->flags |= MAYBE_NUM; /* user input */ @@ -2803,6 +2757,8 @@ do_sub(int nargs, unsigned int flags) if ((t1->flags & NUMCUR) != 0) goto set_how_many; + warning(_("gensub: third argument `%.*s' treated as 1"), + (int) t1->stlen, t1->stptr); how_many = 1; } } else { @@ -2815,8 +2771,8 @@ set_how_many: how_many = d; else how_many = LONG_MAX; - if (d == 0) - warning(_("gensub: third argument of 0 treated as 1")); + if (d <= 0) + warning(_("gensub: third argument %g treated as 1"), d); } DEREF(t1); @@ -3705,7 +3661,6 @@ do_div(int nargs) static size_t mbc_byte_count(const char *ptr, size_t numchars) { -#if MBS_SUPPORT mbstate_t cur_state; size_t sum = 0; int mb_len; @@ -3726,9 +3681,6 @@ mbc_byte_count(const char *ptr, size_t numchars) } return sum; -#else - return numchars; -#endif } /* mbc_char_count --- return number of m.b. chars in string, up to numbytes bytes */ @@ -3736,7 +3688,6 @@ mbc_byte_count(const char *ptr, size_t numchars) static size_t mbc_char_count(const char *ptr, size_t numbytes) { -#if MBS_SUPPORT mbstate_t cur_state; size_t sum = 0; int mb_len; @@ -3759,7 +3710,4 @@ mbc_char_count(const char *ptr, size_t numbytes) } return sum; -#else - return numbytes; -#endif } diff --git a/config.rpath b/config.rpath index ab6fd995..b625621f 100755 --- a/config.rpath +++ b/config.rpath @@ -367,11 +367,7 @@ else dgux*) hardcode_libdir_flag_spec='-L$libdir' ;; - freebsd2.2*) - hardcode_libdir_flag_spec='-R$libdir' - hardcode_direct=yes - ;; - freebsd2*) + freebsd2.[01]*) hardcode_direct=yes hardcode_minus_L=yes ;; @@ -548,13 +544,11 @@ case "$host_os" in dgux*) library_names_spec='$libname$shrext' ;; + freebsd[23].*) + library_names_spec='$libname$shrext$versuffix' + ;; freebsd* | dragonfly*) - case "$host_os" in - freebsd[123]*) - library_names_spec='$libname$shrext$versuffix' ;; - *) - library_names_spec='$libname$shrext' ;; - esac + library_names_spec='$libname$shrext' ;; gnu*) library_names_spec='$libname$shrext' @@ -657,6 +657,7 @@ GMSGFMT MSGFMT GETTEXT_MACRO_VERSION USE_NLS +SED pkgextensiondir acl_shlibext LN_S @@ -1420,7 +1421,7 @@ Optional Packages: --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) --with-whiny-user-strftime Force use of included version of strftime for deficient systems - --with-gnu-ld assume the C compiler uses GNU ld default=no + --with-gnu-ld assume the C compiler uses GNU ld [default=no] --with-libiconv-prefix[=DIR] search for libiconv in DIR/include and DIR/lib --without-libiconv-prefix don't search for libiconv in includedir and libdir --with-libintl-prefix[=DIR] search for libintl in DIR/include and DIR/lib @@ -5834,7 +5835,7 @@ $as_echo_n "checking for special development options... " >&6; } if test -f $srcdir/.developing then # add other debug flags as appropriate, save GAWKDEBUG for emergencies - CFLAGS="$CFLAGS -DARRAYDEBUG -DYYDEBUG" + CFLAGS="$CFLAGS -DARRAYDEBUG -DYYDEBUG -DLOCALEDEBUG" if grep dbug $srcdir/.developing then CFLAGS="$CFLAGS -DDBUG" @@ -6178,6 +6179,75 @@ ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $ ac_compiler_gnu=$ac_cv_c_compiler_gnu +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for a sed that does not truncate output" >&5 +$as_echo_n "checking for a sed that does not truncate output... " >&6; } +if ${ac_cv_path_SED+:} false; then : + $as_echo_n "(cached) " >&6 +else + ac_script=s/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb/ + for ac_i in 1 2 3 4 5 6 7; do + ac_script="$ac_script$as_nl$ac_script" + done + echo "$ac_script" 2>/dev/null | sed 99q >conftest.sed + { ac_script=; unset ac_script;} + if test -z "$SED"; then + ac_path_SED_found=false + # Loop through the user's path and test for each of PROGNAME-LIST + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_prog in sed gsed; do + for ac_exec_ext in '' $ac_executable_extensions; do + ac_path_SED="$as_dir/$ac_prog$ac_exec_ext" + as_fn_executable_p "$ac_path_SED" || continue +# Check for GNU ac_path_SED and select it if it is found. + # Check for GNU $ac_path_SED +case `"$ac_path_SED" --version 2>&1` in +*GNU*) + ac_cv_path_SED="$ac_path_SED" ac_path_SED_found=:;; +*) + ac_count=0 + $as_echo_n 0123456789 >"conftest.in" + while : + do + cat "conftest.in" "conftest.in" >"conftest.tmp" + mv "conftest.tmp" "conftest.in" + cp "conftest.in" "conftest.nl" + $as_echo '' >> "conftest.nl" + "$ac_path_SED" -f conftest.sed < "conftest.nl" >"conftest.out" 2>/dev/null || break + diff "conftest.out" "conftest.nl" >/dev/null 2>&1 || break + as_fn_arith $ac_count + 1 && ac_count=$as_val + if test $ac_count -gt ${ac_path_SED_max-0}; then + # Best one so far, save it but keep looking for a better one + ac_cv_path_SED="$ac_path_SED" + ac_path_SED_max=$ac_count + fi + # 10*(2^10) chars as input seems more than enough + test $ac_count -gt 10 && break + done + rm -f conftest.in conftest.tmp conftest.nl conftest.out;; +esac + + $ac_path_SED_found && break 3 + done + done + done +IFS=$as_save_IFS + if test -z "$ac_cv_path_SED"; then + as_fn_error $? "no acceptable sed could be found in \$PATH" "$LINENO" 5 + fi +else + ac_cv_path_SED=$SED +fi + +fi +{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $ac_cv_path_SED" >&5 +$as_echo "$ac_cv_path_SED" >&6; } + SED="$ac_cv_path_SED" + rm -f conftest.sed + { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether NLS is requested" >&5 $as_echo_n "checking whether NLS is requested... " >&6; } @@ -6194,7 +6264,7 @@ $as_echo "$USE_NLS" >&6; } - GETTEXT_MACRO_VERSION=0.18 + GETTEXT_MACRO_VERSION=0.19 @@ -6202,15 +6272,14 @@ $as_echo "$USE_NLS" >&6; } # Prepare PATH_SEPARATOR. # The user is always right. if test "${PATH_SEPARATOR+set}" != set; then - echo "#! /bin/sh" >conf$$.sh - echo "exit 0" >>conf$$.sh - chmod +x conf$$.sh - if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then - PATH_SEPARATOR=';' - else - PATH_SEPARATOR=: - fi - rm -f conf$$.sh + # Determine PATH_SEPARATOR by trying to find /bin/sh in a PATH which + # contains only /bin. Note that ksh looks also at the FPATH variable, + # so we have to set that as well for the test. + PATH_SEPARATOR=: + (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + && { (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + || PATH_SEPARATOR=';' + } fi # Find out how to test for executable files. Don't use a zero-byte file, @@ -6325,15 +6394,14 @@ fi # Prepare PATH_SEPARATOR. # The user is always right. if test "${PATH_SEPARATOR+set}" != set; then - echo "#! /bin/sh" >conf$$.sh - echo "exit 0" >>conf$$.sh - chmod +x conf$$.sh - if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then - PATH_SEPARATOR=';' - else - PATH_SEPARATOR=: - fi - rm -f conf$$.sh + # Determine PATH_SEPARATOR by trying to find /bin/sh in a PATH which + # contains only /bin. Note that ksh looks also at the FPATH variable, + # so we have to set that as well for the test. + PATH_SEPARATOR=: + (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + && { (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + || PATH_SEPARATOR=';' + } fi # Find out how to test for executable files. Don't use a zero-byte file, @@ -6403,15 +6471,14 @@ fi # Prepare PATH_SEPARATOR. # The user is always right. if test "${PATH_SEPARATOR+set}" != set; then - echo "#! /bin/sh" >conf$$.sh - echo "exit 0" >>conf$$.sh - chmod +x conf$$.sh - if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then - PATH_SEPARATOR=';' - else - PATH_SEPARATOR=: - fi - rm -f conf$$.sh + # Determine PATH_SEPARATOR by trying to find /bin/sh in a PATH which + # contains only /bin. Note that ksh looks also at the FPATH variable, + # so we have to set that as well for the test. + PATH_SEPARATOR=: + (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + && { (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + || PATH_SEPARATOR=';' + } fi # Find out how to test for executable files. Don't use a zero-byte file, @@ -6495,6 +6562,7 @@ fi prefix="$acl_save_prefix" + # Check whether --with-gnu-ld was given. if test "${with_gnu_ld+set}" = set; then : withval=$with_gnu_ld; test "$withval" = no || with_gnu_ld=yes @@ -6505,21 +6573,21 @@ fi # Prepare PATH_SEPARATOR. # The user is always right. if test "${PATH_SEPARATOR+set}" != set; then - echo "#! /bin/sh" >conf$$.sh - echo "exit 0" >>conf$$.sh - chmod +x conf$$.sh - if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then - PATH_SEPARATOR=';' - else - PATH_SEPARATOR=: - fi - rm -f conf$$.sh + # Determine PATH_SEPARATOR by trying to find /bin/sh in a PATH which + # contains only /bin. Note that ksh looks also at the FPATH variable, + # so we have to set that as well for the test. + PATH_SEPARATOR=: + (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + && { (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + || PATH_SEPARATOR=';' + } fi + ac_prog=ld if test "$GCC" = yes; then # Check if gcc -print-prog-name=ld gives a path. - { $as_echo "$as_me:${as_lineno-$LINENO}: checking for ld used by GCC" >&5 -$as_echo_n "checking for ld used by GCC... " >&6; } + { $as_echo "$as_me:${as_lineno-$LINENO}: checking for ld used by $CC" >&5 +$as_echo_n "checking for ld used by $CC... " >&6; } case $host in *-*-mingw*) # gcc leaves a trailing carriage return which upsets mingw @@ -6529,11 +6597,11 @@ $as_echo_n "checking for ld used by GCC... " >&6; } esac case $ac_prog in # Accept absolute paths. - [\\/]* | [A-Za-z]:[\\/]*) + [\\/]* | ?:[\\/]*) re_direlt='/[^/][^/]*/\.\./' - # Canonicalize the path of ld - ac_prog=`echo $ac_prog| sed 's%\\\\%/%g'` - while echo $ac_prog | grep "$re_direlt" > /dev/null 2>&1; do + # Canonicalize the pathname of ld + ac_prog=`echo "$ac_prog"| sed 's%\\\\%/%g'` + while echo "$ac_prog" | grep "$re_direlt" > /dev/null 2>&1; do ac_prog=`echo $ac_prog| sed "s%$re_direlt%/%"` done test -z "$LD" && LD="$ac_prog" @@ -6558,23 +6626,26 @@ if ${acl_cv_path_LD+:} false; then : $as_echo_n "(cached) " >&6 else if test -z "$LD"; then - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}${PATH_SEPARATOR-:}" + acl_save_ifs="$IFS"; IFS=$PATH_SEPARATOR for ac_dir in $PATH; do + IFS="$acl_save_ifs" test -z "$ac_dir" && ac_dir=. if test -f "$ac_dir/$ac_prog" || test -f "$ac_dir/$ac_prog$ac_exeext"; then acl_cv_path_LD="$ac_dir/$ac_prog" # Check to see if the program is GNU ld. I'd rather use --version, - # but apparently some GNU ld's only accept -v. + # but apparently some variants of GNU ld only accept -v. # Break only if it was the GNU/non-GNU ld that we prefer. - case `"$acl_cv_path_LD" -v 2>&1 < /dev/null` in + case `"$acl_cv_path_LD" -v 2>&1 </dev/null` in *GNU* | *'with BFD'*) - test "$with_gnu_ld" != no && break ;; + test "$with_gnu_ld" != no && break + ;; *) - test "$with_gnu_ld" != yes && break ;; + test "$with_gnu_ld" != yes && break + ;; esac fi done - IFS="$ac_save_ifs" + IFS="$acl_save_ifs" else acl_cv_path_LD="$LD" # Let the user override the test with a path. fi @@ -6594,12 +6665,14 @@ $as_echo_n "checking if the linker ($LD) is GNU ld... " >&6; } if ${acl_cv_prog_gnu_ld+:} false; then : $as_echo_n "(cached) " >&6 else - # I'd rather use --version here, but apparently some GNU ld's only accept -v. + # I'd rather use --version here, but apparently some GNU lds only accept -v. case `$LD -v 2>&1 </dev/null` in *GNU* | *'with BFD'*) - acl_cv_prog_gnu_ld=yes ;; + acl_cv_prog_gnu_ld=yes + ;; *) - acl_cv_prog_gnu_ld=no ;; + acl_cv_prog_gnu_ld=no + ;; esac fi { $as_echo "$as_me:${as_lineno-$LINENO}: result: $acl_cv_prog_gnu_ld" >&5 @@ -6782,7 +6855,7 @@ fi done if test -z "$already_handled"; then names_already_handled="$names_already_handled $name" - uppername=`echo "$name" | sed -e 'y|abcdefghijklmnopqrstuvwxyz./-|ABCDEFGHIJKLMNOPQRSTUVWXYZ___|'` + uppername=`echo "$name" | sed -e 'y|abcdefghijklmnopqrstuvwxyz./+-|ABCDEFGHIJKLMNOPQRSTUVWXYZ____|'` eval value=\"\$HAVE_LIB$uppername\" if test -n "$value"; then if test "$value" = yes; then @@ -7311,15 +7384,19 @@ if eval \${$gt_func_gnugettext_libc+:} false; then : else cat confdefs.h - <<_ACEOF >conftest.$ac_ext /* end confdefs.h. */ + #include <libintl.h> $gt_revision_test_code extern int _nl_msg_cat_cntr; extern int *_nl_domain_bindings; + int main () { + bindtextdomain ("", ""); return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_domain_bindings + ; return 0; } @@ -7377,14 +7454,16 @@ else am_cv_lib_iconv=no cat confdefs.h - <<_ACEOF >conftest.$ac_ext /* end confdefs.h. */ + #include <stdlib.h> #include <iconv.h> + int main () { iconv_t cd = iconv_open("",""); - iconv(cd,NULL,NULL,NULL,NULL); - iconv_close(cd); + iconv(cd,NULL,NULL,NULL,NULL); + iconv_close(cd); ; return 0; } @@ -7399,14 +7478,16 @@ rm -f core conftest.err conftest.$ac_objext \ LIBS="$LIBS $LIBICONV" cat confdefs.h - <<_ACEOF >conftest.$ac_ext /* end confdefs.h. */ + #include <stdlib.h> #include <iconv.h> + int main () { iconv_t cd = iconv_open("",""); - iconv(cd,NULL,NULL,NULL,NULL); - iconv_close(cd); + iconv(cd,NULL,NULL,NULL,NULL); + iconv_close(cd); ; return 0; } @@ -7430,15 +7511,17 @@ if ${am_cv_func_iconv_works+:} false; then : $as_echo_n "(cached) " >&6 else - am_save_LIBS="$LIBS" + am_save_LIBS="$LIBS" if test $am_cv_lib_iconv = yes; then LIBS="$LIBS $LIBICONV" fi if test "$cross_compiling" = yes; then : - case "$host_os" in + + case "$host_os" in aix* | hpux*) am_cv_func_iconv_works="guessing no" ;; *) am_cv_func_iconv_works="guessing yes" ;; esac + else cat confdefs.h - <<_ACEOF >conftest.$ac_ext /* end confdefs.h. */ @@ -7447,6 +7530,7 @@ else #include <string.h> int main () { + int result = 0; /* Test against AIX 5.1 bug: Failures are not distinguishable from successful returns. */ { @@ -7463,7 +7547,8 @@ int main () (char **) &inptr, &inbytesleft, &outptr, &outbytesleft); if (res == 0) - return 1; + result |= 1; + iconv_close (cd_utf8_to_88591); } } /* Test against Solaris 10 bug: Failures are not distinguishable from @@ -7482,7 +7567,27 @@ int main () (char **) &inptr, &inbytesleft, &outptr, &outbytesleft); if (res == 0) - return 1; + result |= 2; + iconv_close (cd_ascii_to_88591); + } + } + /* Test against AIX 6.1..7.1 bug: Buffer overrun. */ + { + iconv_t cd_88591_to_utf8 = iconv_open ("UTF-8", "ISO-8859-1"); + if (cd_88591_to_utf8 != (iconv_t)(-1)) + { + static const char input[] = "\304"; + static char buf[2] = { (char)0xDE, (char)0xAD }; + const char *inptr = input; + size_t inbytesleft = 1; + char *outptr = buf; + size_t outbytesleft = 1; + size_t res = iconv (cd_88591_to_utf8, + (char **) &inptr, &inbytesleft, + &outptr, &outbytesleft); + if (res != (size_t)(-1) || outptr - buf > 1 || buf[1] != (char)0xAD) + result |= 4; + iconv_close (cd_88591_to_utf8); } } #if 0 /* This bug could be worked around by the caller. */ @@ -7501,7 +7606,8 @@ int main () (char **) &inptr, &inbytesleft, &outptr, &outbytesleft); if ((int)res > 0) - return 1; + result |= 8; + iconv_close (cd_88591_to_utf8); } } #endif @@ -7515,8 +7621,8 @@ int main () && iconv_open ("UTF-8", "IBM-eucJP") == (iconv_t)(-1) /* Try HP-UX names. */ && iconv_open ("utf8", "eucJP") == (iconv_t)(-1)) - return 1; - return 0; + result |= 16; + return result; } _ACEOF if ac_fn_c_try_run "$LINENO"; then : @@ -7633,7 +7739,7 @@ fi done if test -z "$already_handled"; then names_already_handled="$names_already_handled $name" - uppername=`echo "$name" | sed -e 'y|abcdefghijklmnopqrstuvwxyz./-|ABCDEFGHIJKLMNOPQRSTUVWXYZ___|'` + uppername=`echo "$name" | sed -e 'y|abcdefghijklmnopqrstuvwxyz./+-|ABCDEFGHIJKLMNOPQRSTUVWXYZ____|'` eval value=\"\$HAVE_LIB$uppername\" if test -n "$value"; then if test "$value" = yes; then @@ -8031,6 +8137,7 @@ else LIBS="$LIBS $LIBINTL" cat confdefs.h - <<_ACEOF >conftest.$ac_ext /* end confdefs.h. */ + #include <libintl.h> $gt_revision_test_code extern int _nl_msg_cat_cntr; @@ -8039,11 +8146,14 @@ extern "C" #endif const char *_nl_expand_alias (const char *); + int main () { + bindtextdomain ("", ""); return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_expand_alias ("") + ; return 0; } @@ -8059,6 +8169,7 @@ rm -f core conftest.err conftest.$ac_objext \ LIBS="$LIBS $LIBICONV" cat confdefs.h - <<_ACEOF >conftest.$ac_ext /* end confdefs.h. */ + #include <libintl.h> $gt_revision_test_code extern int _nl_msg_cat_cntr; @@ -8067,19 +8178,22 @@ extern "C" #endif const char *_nl_expand_alias (const char *); + int main () { + bindtextdomain ("", ""); return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_expand_alias ("") + ; return 0; } _ACEOF if ac_fn_c_try_link "$LINENO"; then : LIBINTL="$LIBINTL $LIBICONV" - LTLIBINTL="$LTLIBINTL $LTLIBICONV" - eval "$gt_func_gnugettext_libintl=yes" + LTLIBINTL="$LTLIBINTL $LTLIBICONV" + eval "$gt_func_gnugettext_libintl=yes" fi rm -f core conftest.err conftest.$ac_objext \ @@ -9691,7 +9805,7 @@ fi done if test -z "$already_handled"; then names_already_handled="$names_already_handled $name" - uppername=`echo "$name" | sed -e 'y|abcdefghijklmnopqrstuvwxyz./-|ABCDEFGHIJKLMNOPQRSTUVWXYZ___|'` + uppername=`echo "$name" | sed -e 'y|abcdefghijklmnopqrstuvwxyz./+-|ABCDEFGHIJKLMNOPQRSTUVWXYZ____|'` eval value=\"\$HAVE_LIB$uppername\" if test -n "$value"; then if test "$value" = yes; then @@ -12614,7 +12728,7 @@ $as_echo X"$file" | case "$ac_file" in */Makefile.in) # Adjust a relative srcdir. ac_dir=`echo "$ac_file"|sed 's%/[^/][^/]*$%%'` - ac_dir_suffix="/`echo "$ac_dir"|sed 's%^\./%%'`" + ac_dir_suffix=/`echo "$ac_dir"|sed 's%^\./%%'` ac_dots=`echo "$ac_dir_suffix"|sed 's%/[^/]*%../%g'` # In autoconf-2.13 it is called $ac_given_srcdir. # In autoconf-2.50 it is called $srcdir. @@ -12630,7 +12744,8 @@ $as_echo X"$file" | if test -f "$ac_given_srcdir/$ac_dir/POTFILES.in"; then rm -f "$ac_dir/POTFILES" test -n "$as_me" && echo "$as_me: creating $ac_dir/POTFILES" || echo "creating $ac_dir/POTFILES" - cat "$ac_given_srcdir/$ac_dir/POTFILES.in" | sed -e "/^#/d" -e "/^[ ]*\$/d" -e "s,.*, $top_srcdir/& \\\\," | sed -e "\$s/\(.*\) \\\\/\1/" > "$ac_dir/POTFILES" + gt_tab=`printf '\t'` + cat "$ac_given_srcdir/$ac_dir/POTFILES.in" | sed -e "/^#/d" -e "/^[ ${gt_tab}]*\$/d" -e "s,.*, $top_srcdir/& \\\\," | sed -e "\$s/\(.*\) \\\\/\1/" > "$ac_dir/POTFILES" POMAKEFILEDEPS="POTFILES.in" # ALL_LINGUAS, POFILES, UPDATEPOFILES, DUMMYPOFILES, GMOFILES depend # on $ac_dir but don't depend on user-specified configuration @@ -12641,12 +12756,12 @@ $as_echo X"$file" | test -n "$as_me" && echo "$as_me: setting ALL_LINGUAS in configure.in is obsolete" || echo "setting ALL_LINGUAS in configure.in is obsolete" fi ALL_LINGUAS_=`sed -e "/^#/d" -e "s/#.*//" "$ac_given_srcdir/$ac_dir/LINGUAS"` - # Hide the ALL_LINGUAS assigment from automake < 1.5. + # Hide the ALL_LINGUAS assignment from automake < 1.5. eval 'ALL_LINGUAS''=$ALL_LINGUAS_' POMAKEFILEDEPS="$POMAKEFILEDEPS LINGUAS" else # The set of available languages was given in configure.in. - # Hide the ALL_LINGUAS assigment from automake < 1.5. + # Hide the ALL_LINGUAS assignment from automake < 1.5. eval 'ALL_LINGUAS''=$OBSOLETE_ALL_LINGUAS' fi # Compute POFILES diff --git a/configure.ac b/configure.ac index 70074139..7e5f69c3 100644 --- a/configure.ac +++ b/configure.ac @@ -40,7 +40,7 @@ then fi AC_PREREQ(2.69) -AM_INIT_AUTOMAKE([1.13 dist-xz dist-lzip]) +AM_INIT_AUTOMAKE([1.14 dist-xz dist-lzip]) AC_CONFIG_MACRO_DIR([m4]) @@ -87,7 +87,7 @@ AC_MSG_CHECKING([for special development options]) if test -f $srcdir/.developing then # add other debug flags as appropriate, save GAWKDEBUG for emergencies - CFLAGS="$CFLAGS -DARRAYDEBUG -DYYDEBUG" + CFLAGS="$CFLAGS -DARRAYDEBUG -DYYDEBUG -DLOCALEDEBUG" if grep dbug $srcdir/.developing then CFLAGS="$CFLAGS -DDBUG" @@ -131,7 +131,7 @@ AC_LANG([C]) dnl initialize GNU gettext AM_GNU_GETTEXT([external]) -AM_GNU_GETTEXT_VERSION([0.18.1]) +AM_GNU_GETTEXT_VERSION([0.19.3]) AM_LANGINFO_CODESET gt_LC_MESSAGES @@ -58,15 +58,15 @@ #include "gettext.h" #define _(str) gettext (str) -#include "mbsupport.h" /* Define MBS_SUPPORT to 1 or 0, as appropriate. */ -#if MBS_SUPPORT -/* We can handle multibyte strings. */ -# include <wchar.h> -# include <wctype.h> -#endif +#include <wchar.h> +#include <wctype.h> #include "xalloc.h" +#if defined(__DJGPP__) +#include "mbsupport.h" +#endif + #include "dfa.h" #ifdef GAWK @@ -391,12 +391,10 @@ struct dfa */ int *multibyte_prop; -#if MBS_SUPPORT /* A table indexed by byte values that contains the corresponding wide character (if any) for that byte. WEOF means the byte is not a valid single-byte character. */ wint_t mbrtowc_cache[NOTCHAR]; -#endif /* Array of the bracket expression in the DFA. */ struct mb_char_classes *mbcsets; @@ -481,7 +479,6 @@ static void regexp (void); static void dfambcache (struct dfa *d) { -#if MBS_SUPPORT int i; for (i = CHAR_MIN; i <= CHAR_MAX; ++i) { @@ -491,10 +488,8 @@ dfambcache (struct dfa *d) wchar_t wc; d->mbrtowc_cache[uc] = mbrtowc (&wc, &c, 1, &s) <= 1 ? wc : WEOF; } -#endif } -#if MBS_SUPPORT /* Store into *PWC the result of converting the leading bytes of the multibyte buffer S of length N bytes, using the mbrtowc_cache in *D and updating the conversion state in *D. On conversion error, @@ -533,9 +528,6 @@ mbs_to_wchar (wint_t *pwc, char const *s, size_t n, struct dfa *d) *pwc = wc; return 1; } -#else -#define mbs_to_wchar(pwc, s, n, d) (WEOF) -#endif #ifdef DEBUG @@ -730,7 +722,7 @@ static charclass newline; #ifdef __GLIBC__ # define is_valid_unibyte_character(c) 1 #else -# define is_valid_unibyte_character(c) (! (MBS_SUPPORT && btowc (c) == WEOF)) +# define is_valid_unibyte_character(c) (btowc (c) != WEOF) #endif /* C is a "word-constituent" byte. */ @@ -791,17 +783,12 @@ dfasyntax (reg_syntax_t bits, int fold, unsigned char eol) static bool setbit_wc (wint_t wc, charclass c) { -#if MBS_SUPPORT int b = wctob (wc); if (b == EOF) return false; setbit (b, c); return true; -#else - abort (); - /*NOTREACHED*/ return false; -#endif } /* Set a bit for B and its case variants in the charclass C. @@ -895,7 +882,6 @@ static wint_t wctok; /* Wide character representation of the current MB_CUR_MAX > 1. */ -#if MBS_SUPPORT /* Fetch the next lexical input character. Set C (of type int) to the next input byte, except set C to EOF if the input is a multibyte character of length greater than 1. Set WC (of type wint_t) to the @@ -924,23 +910,6 @@ static wint_t wctok; /* Wide character representation of the current } \ } while (0) -#else -/* Note that characters become unsigned here. */ -# define FETCH_WC(c, unused, eoferr) \ - do { \ - if (! lexleft) \ - { \ - if ((eoferr) != 0) \ - dfaerror (eoferr); \ - else \ - return lasttok = END; \ - } \ - (c) = to_uchar (*lexptr++); \ - --lexleft; \ - } while (0) - -#endif /* MBS_SUPPORT */ - #ifndef MIN # define MIN(a,b) ((a) < (b) ? (a) : (b)) #endif @@ -1752,7 +1721,6 @@ addtok (token t) } } -#if MBS_SUPPORT /* We treat a multibyte character as a single atom, so that DFA can treat a multibyte character as a single expression. @@ -1784,17 +1752,10 @@ addtok_wc (wint_t wc) addtok (CAT); } } -#else -static void -addtok_wc (wint_t wc) -{ -} -#endif static void add_utf8_anychar (void) { -#if MBS_SUPPORT static const charclass utf8_classes[5] = { /* 80-bf: non-leading bytes. */ {0, 0, 0, 0, CHARCLASS_WORD_MASK, CHARCLASS_WORD_MASK, 0, 0}, @@ -1849,7 +1810,6 @@ add_utf8_anychar (void) addtok (CAT); addtok (OR); } -#endif } /* The grammar understood by the parser is as follows. @@ -1890,7 +1850,7 @@ add_utf8_anychar (void) static void atom (void) { - if (MBS_SUPPORT && tok == WCHAR) + if (tok == WCHAR) { if (wctok == WEOF) addtok (BACKREF); @@ -1912,7 +1872,7 @@ atom (void) tok = lex (); } - else if (MBS_SUPPORT && tok == ANYCHAR && using_utf8 ()) + else if (tok == ANYCHAR && using_utf8 ()) { /* For UTF-8 expand the period to a series of CSETs that define a valid UTF-8 character. This avoids using the slow multibyte path. I'm @@ -1926,9 +1886,7 @@ atom (void) } else if ((tok >= 0 && tok < NOTCHAR) || tok >= CSET || tok == BACKREF || tok == BEGLINE || tok == ENDLINE || tok == BEGWORD -#if MBS_SUPPORT || tok == ANYCHAR || tok == MBCSET -#endif /* MBS_SUPPORT */ || tok == ENDWORD || tok == LIMWORD || tok == NOTLIMWORD) { addtok (tok); @@ -2261,10 +2219,8 @@ epsclosure (position_set *s, struct dfa const *d, char *visited) for (i = 0; i < s->nelem; ++i) if (d->tokens[s->elems[i].index] >= NOTCHAR && d->tokens[s->elems[i].index] != BACKREF -#if MBS_SUPPORT && d->tokens[s->elems[i].index] != ANYCHAR && d->tokens[s->elems[i].index] != MBCSET -#endif && d->tokens[s->elems[i].index] < CSET) { if (!initialized) @@ -2583,9 +2539,7 @@ dfaanalyze (struct dfa *d, int searchflag) it with its epsilon closure. */ for (i = 0; i < d->tindex; ++i) if (d->tokens[i] < NOTCHAR || d->tokens[i] == BACKREF -#if MBS_SUPPORT || d->tokens[i] == ANYCHAR || d->tokens[i] == MBCSET -#endif || d->tokens[i] >= CSET) { #ifdef DEBUG @@ -2695,9 +2649,8 @@ dfastate (state_num s, struct dfa *d, state_num trans[]) copyset (d->charclasses[d->tokens[pos.index] - CSET], matches); else { - if (MBS_SUPPORT - && (d->tokens[pos.index] == MBCSET - || d->tokens[pos.index] == ANYCHAR)) + if (d->tokens[pos.index] == MBCSET + || d->tokens[pos.index] == ANYCHAR) { /* MB_CUR_MAX > 1 */ if (d->tokens[pos.index] == MBCSET) @@ -3531,13 +3484,23 @@ dfaexec_main (struct dfa *d, char const *begin, char *end, } } - if ((char *) p > end) + if (s < 0) { - p = NULL; - goto done; + if ((char *) p > end || p[-1] != eol || d->newlines[s1] < 0) + { + p = NULL; + goto done; + } + + /* The previous character was a newline, count it, and skip + checking of multibyte character boundary until here. */ + nlcount++; + mbp = p; + + s = allow_nl ? d->newlines[s1] : 0; } - if (s >= 0 && d->fails[s]) + if (d->fails[s]) { if (d->success[s] & sbit[*p]) { @@ -3551,32 +3514,13 @@ dfaexec_main (struct dfa *d, char const *begin, char *end, State_transition(); else s = d->fails[s][*p++]; - continue; } - - /* If the previous character was a newline, count it, and skip - checking of multibyte character boundary until here. */ - if (p[-1] == eol) - { - nlcount++; - mbp = p; - } - - if (s >= 0) + else { if (!d->trans[s]) build_state (s, d); trans = d->trans; - continue; } - - if (p[-1] == eol && allow_nl) - { - s = d->newlines[s1]; - continue; - } - - s = 0; } done: @@ -3672,7 +3616,7 @@ dfaoptimize (struct dfa *d) size_t i; bool have_backref = false; - if (!MBS_SUPPORT || !using_utf8 ()) + if (!using_utf8 ()) return; for (i = 0; i < d->tindex; ++i) @@ -3732,8 +3676,11 @@ dfassbuild (struct dfa *d) sup->musts = NULL; sup->charclasses = xnmalloc (sup->calloc, sizeof *sup->charclasses); - memcpy (sup->charclasses, d->charclasses, - d->cindex * sizeof *sup->charclasses); + if (d->cindex) + { + memcpy (sup->charclasses, d->charclasses, + d->cindex * sizeof *sup->charclasses); + } sup->tokens = xnmalloc (d->tindex, 2 * sizeof *sup->tokens); sup->talloc = d->tindex * 2; diff --git a/doc/ChangeLog b/doc/ChangeLog index 6dfd1b17..cf320744 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,41 @@ +2014-12-12 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Minor fix. + Thanks to Teri Price <tjp212@lehigh.edu>. + +2014-12-10 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More minor fixes. + +2014-12-09 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More minor fixes. + +2014-12-07 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Minor fixes. + +2014-12-06 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: A minor fix. + +2014-12-05 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Various minor fixes and updates. + +2014-11-23 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Update that TZ env. var can influnce mktime + in running program. Thanks to Hermann Peifer. + +2014-11-19 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Update that RFC 4180 documents CSV data. + +2014-11-17 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Copyedits applied. + 2014-11-02 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Comment out that I need an owner for awk.info. diff --git a/doc/Makefile.in b/doc/Makefile.in index 09701a06..a17000bc 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -276,6 +276,7 @@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ POSUB = @POSUB@ +SED = @SED@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ SOCKET_LIBS = @SOCKET_LIBS@ diff --git a/doc/gawk.info b/doc/gawk.info index 5863ea0f..8e5e6b29 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -691,24 +691,24 @@ circumstances--and our favorite programming language, AWK. The circumstances started a couple of years earlier. I was working at a new job and noticed an unplugged Unix computer sitting in the corner. No one knew how to use it, and neither did I. However, a couple of days -later it was running, and I was `root' and the one-and-only user. That -day, I began the transition from statistician to Unix programmer. +later, it was running, and I was `root' and the one-and-only user. +That day, I began the transition from statistician to Unix programmer. On one of many trips to the library or bookstore in search of books -on Unix, I found the gray AWK book, a.k.a. Aho, Kernighan and -Weinberger, `The AWK Programming Language', Addison-Wesley, 1988. -AWK's simple programming paradigm--find a pattern in the input and then -perform an action--often reduced complex or tedious data manipulations -to a few lines of code. I was excited to try my hand at programming in -AWK. +on Unix, I found the gray AWK book, a.k.a. Alfred V. Aho, Brian W. +Kernighan, and Peter J. Weinberger's `The AWK Programming Language' +(Addison-Wesley, 1988). `awk''s simple programming paradigm--find a +pattern in the input and then perform an action--often reduced complex +or tedious data manipulations to a few lines of code. I was excited to +try my hand at programming in AWK. Alas, the `awk' on my computer was a limited version of the -language described in the AWK book. I discovered that my computer had -"old `awk'" and the AWK book described "new `awk'." I learned that -this was typical; the old version refused to step aside or relinquish -its name. If a system had a new `awk', it was invariably called -`nawk', and few systems had it. The best way to get a new `awk' was to -`ftp' the source code for `gawk' from `prep.ai.mit.edu'. `gawk' was a +language described in the gray book. I discovered that my computer had +"old `awk'" and the book described "new `awk'." I learned that this +was typical; the old version refused to step aside or relinquish its +name. If a system had a new `awk', it was invariably called `nawk', +and few systems had it. The best way to get a new `awk' was to `ftp' +the source code for `gawk' from `prep.ai.mit.edu'. `gawk' was a version of new `awk' written by David Trueman and Arnold, and available under the GNU General Public License. @@ -719,14 +719,15 @@ almost any system; my wife uses `gawk' on her VMS box.) My Unix system started out unplugged from the wall; it certainly was not plugged into a network. So, oblivious to the existence of `gawk' and the Unix community in general, and desiring a new `awk', I wrote my -own, called `mawk'. Before I was finished I knew about `gawk', but it +own, called `mawk'. Before I was finished, I knew about `gawk', but it was too late to stop, so I eventually posted to a `comp.sources' newsgroup. A few days after my posting, I got a friendly email from Arnold introducing himself. He suggested we share design and algorithms and attached a draft of the POSIX standard so that I could update `mawk' to -support language extensions added after publication of the AWK book. +support language extensions added after publication of `The AWK +Programming Language'. Frankly, if our roles had been reversed, I would not have been so open and we probably would have never met. I'm glad we did meet. He @@ -740,9 +741,9 @@ a definitive reference to the AWK language as defined by the 1987 Bell Laboratories release and codified in the 1992 POSIX Utilities standard. On the other hand, the novice AWK programmer can study a wealth of -practical programs that emphasize the power of AWK's basic idioms: data -driven control-flow, pattern matching with regular expressions, and -associative arrays. Those looking for something new can try out +practical programs that emphasize the power of AWK's basic idioms: +data-driven control flow, pattern matching with regular expressions, +and associative arrays. Those looking for something new can try out `gawk''s interface to network protocols via special `/inet' files. The programs in this book make clear that an AWK program is @@ -765,7 +766,7 @@ want to learn how, then read this book. Michael Brennan Author of `mawk' - March, 2001 + March 2001 File: gawk.info, Node: Foreword4, Next: Preface, Prev: Foreword3, Up: Top @@ -799,7 +800,7 @@ help you learn the ins and outs. Michael Brennan Author of `mawk' - October, 2014 + October 2014 File: gawk.info, Node: Preface, Next: Getting Started, Prev: Foreword4, Up: Top @@ -815,12 +816,12 @@ rest of the file alone. Such jobs are often easy with `awk'. The makes it easy to handle simple data-reformatting jobs. The GNU implementation of `awk' is called `gawk'; if you invoke it -with the proper options or environment variables it is fully compatible -with the POSIX(1) specification of the `awk' language and with the Unix -version of `awk' maintained by Brian Kernighan. This means that all -properly written `awk' programs should work with `gawk'. So most of -the time, we don't distinguish between `gawk' and other `awk' -implementations. +with the proper options or environment variables, it is fully +compatible with the POSIX(1) specification of the `awk' language and +with the Unix version of `awk' maintained by Brian Kernighan. This +means that all properly written `awk' programs should work with `gawk'. +So most of the time, we don't distinguish between `gawk' and other +`awk' implementations. Using `awk' you can: @@ -893,7 +894,7 @@ File: gawk.info, Node: History, Next: Names, Up: Preface History of `awk' and `gawk' =========================== - Recipe For A Programming Language + Recipe for a Programming Language 1 part `egrep' 1 part `snobol' 2 parts `ed' 3 parts C @@ -905,7 +906,7 @@ release. Document very well and release. The name `awk' comes from the initials of its designers: Alfred V. -Aho, Peter J. Weinberger and Brian W. Kernighan. The original version +Aho, Peter J. Weinberger, and Brian W. Kernighan. The original version of `awk' was written in 1977 at AT&T Bell Laboratories. In 1985, a new version made the programming language more powerful, introducing user-defined functions, multiple input streams, and computed regular @@ -925,7 +926,7 @@ Circa 1994, I became the primary maintainer. Current development focuses on bug fixes, performance improvements, standards compliance and, occasionally, new features. - In May of 1997, Ju"rgen Kahrs felt the need for network access from + In May 1997, Ju"rgen Kahrs felt the need for network access from `awk', and with a little help from me, set about adding features to do this for `gawk'. At that time, he also wrote the bulk of `TCP/IP Internetworking with `gawk'' (a separate document, available as part of @@ -947,7 +948,7 @@ A Rose by Any Other Name The `awk' language has evolved over the years. Full details are provided in *note Language History::. The language described in this -Info file is often referred to as "new `awk'". By analogy, the +Info file is often referred to as "new `awk'." By analogy, the original version of `awk' is referred to as "old `awk'." Today, on most systems, when you run the `awk' utility, you get some @@ -1002,110 +1003,120 @@ heading "sidebar." the more advanced sections show only the part of the `awk' program that illustrates the concept being described. - While this Info file is aimed principally at people who have not been -exposed to `awk', there is a lot of information here that even the `awk' -expert should find useful. In particular, the description of POSIX -`awk' and the example programs in *note Library Functions::, and in -*note Sample Programs::, should be of interest. + Although this Info file is aimed principally at people who have not +been exposed to `awk', there is a lot of information here that even the +`awk' expert should find useful. In particular, the description of +POSIX `awk' and the example programs in *note Library Functions::, and +in *note Sample Programs::, should be of interest. This Info file is split into several parts, as follows: - Part I describes the `awk' language and `gawk' program in detail. -It starts with the basics, and continues through all of the features of -`awk'. It contains the following chapters: + * Part I describes the `awk' language and `gawk' program in detail. + It starts with the basics, and continues through all of the + features of `awk'. It contains the following chapters: - *note Getting Started::, provides the essentials you need to know to -begin using `awk'. + - *note Getting Started::, provides the essentials you need to + know to begin using `awk'. - *note Invoking Gawk::, describes how to run `gawk', the meaning of -its command-line options, and how it finds `awk' program source files. + - *note Invoking Gawk::, describes how to run `gawk', the + meaning of its command-line options, and how it finds `awk' + program source files. - *note Regexp::, introduces regular expressions in general, and in -particular the flavors supported by POSIX `awk' and `gawk'. + - *note Regexp::, introduces regular expressions in general, + and in particular the flavors supported by POSIX `awk' and + `gawk'. - *note Reading Files::, describes how `awk' reads your data. It -introduces the concepts of records and fields, as well as the `getline' -command. I/O redirection is first described here. Network I/O is also -briefly introduced here. + - *note Reading Files::, describes how `awk' reads your data. + It introduces the concepts of records and fields, as well as + the `getline' command. I/O redirection is first described + here. Network I/O is also briefly introduced here. - *note Printing::, describes how `awk' programs can produce output -with `print' and `printf'. + - *note Printing::, describes how `awk' programs can produce + output with `print' and `printf'. - *note Expressions::, describes expressions, which are the basic -building blocks for getting most things done in a program. + - *note Expressions::, describes expressions, which are the + basic building blocks for getting most things done in a + program. - *note Patterns and Actions::, describes how to write patterns for -matching records, actions for doing something when a record is matched, -and the predefined variables `awk' and `gawk' use. + - *note Patterns and Actions::, describes how to write patterns + for matching records, actions for doing something when a + record is matched, and the predefined variables `awk' and + `gawk' use. - *note Arrays::, covers `awk''s one-and-only data structure: -associative arrays. Deleting array elements and whole arrays is also -described, as well as sorting arrays in `gawk'. It also describes how -`gawk' provides arrays of arrays. + - *note Arrays::, covers `awk''s one-and-only data structure: + associative arrays. Deleting array elements and whole arrays + is also described, as well as sorting arrays in `gawk'. It + also describes how `gawk' provides arrays of arrays. - *note Functions::, describes the built-in functions `awk' and `gawk' -provide, as well as how to define your own functions. It also -discusses how `gawk' lets you call functions indirectly. + - *note Functions::, describes the built-in functions `awk' and + `gawk' provide, as well as how to define your own functions. + It also discusses how `gawk' lets you call functions + indirectly. - Part II shows how to use `awk' and `gawk' for problem solving. -There is lots of code here for you to read and learn from. It contains -the following chapters: + * Part II shows how to use `awk' and `gawk' for problem solving. + There is lots of code here for you to read and learn from. It + contains the following chapters: - *note Library Functions::, which provides a number of functions -meant to be used from main `awk' programs. + - *note Library Functions::, which provides a number of + functions meant to be used from main `awk' programs. - *note Sample Programs::, which provides many sample `awk' programs. + - *note Sample Programs::, which provides many sample `awk' + programs. - Reading these two chapters allows you to see `awk' solving real -problems. + Reading these two chapters allows you to see `awk' solving real + problems. - Part III focuses on features specific to `gawk'. It contains the -following chapters: + * Part III focuses on features specific to `gawk'. It contains the + following chapters: - *note Advanced Features::, describes a number of advanced features. -Of particular note are the abilities to control the order of array -traversal, have two-way communications with another process, perform -TCP/IP networking, and profile your `awk' programs. + - *note Advanced Features::, describes a number of advanced + features. Of particular note are the abilities to control + the order of array traversal, have two-way communications + with another process, perform TCP/IP networking, and profile + your `awk' programs. - *note Internationalization::, describes special features for -translating program messages into different languages at runtime. + - *note Internationalization::, describes special features for + translating program messages into different languages at + runtime. - *note Debugger::, describes the `gawk' debugger. + - *note Debugger::, describes the `gawk' debugger. - *note Arbitrary Precision Arithmetic::, describes advanced -arithmetic facilities. + - *note Arbitrary Precision Arithmetic::, describes advanced + arithmetic facilities. - *note Dynamic Extensions::, describes how to add new variables and -functions to `gawk' by writing extensions in C or C++. + - *note Dynamic Extensions::, describes how to add new + variables and functions to `gawk' by writing extensions in C + or C++. - Part IV provides the appendices, the Glossary, and two licenses that -cover the `gawk' source code and this Info file, respectively. It -contains the following appendices: + * Part IV provides the appendices, the Glossary, and two licenses + that cover the `gawk' source code and this Info file, respectively. + It contains the following appendices: - *note Language History::, describes how the `awk' language has -evolved since its first release to present. It also describes how -`gawk' has acquired features over time. + - *note Language History::, describes how the `awk' language + has evolved since its first release to present. It also + describes how `gawk' has acquired features over time. - *note Installation::, describes how to get `gawk', how to compile it -on POSIX-compatible systems, and how to compile and use it on different -non-POSIX systems. It also describes how to report bugs in `gawk' and -where to get other freely available `awk' implementations. + - *note Installation::, describes how to get `gawk', how to + compile it on POSIX-compatible systems, and how to compile + and use it on different non-POSIX systems. It also describes + how to report bugs in `gawk' and where to get other freely + available `awk' implementations. - *note Notes::, describes how to disable `gawk''s extensions, as well -as how to contribute new code to `gawk', and some possible future -directions for `gawk' development. + - *note Notes::, describes how to disable `gawk''s extensions, + as well as how to contribute new code to `gawk', and some + possible future directions for `gawk' development. - *note Basic Concepts::, provides some very cursory background -material for those who are completely unfamiliar with computer -programming. + - *note Basic Concepts::, provides some very cursory background + material for those who are completely unfamiliar with + computer programming. - The *note Glossary::, defines most, if not all, the significant -terms used throughout the Info file. If you find terms that you aren't -familiar with, try looking them up here. + The *note Glossary::, defines most, if not all of, the + significant terms used throughout the Info file. If you find + terms that you aren't familiar with, try looking them up here. - *note Copying::, and *note GNU Free Documentation License::, present -the licenses that cover the `gawk' source code and this Info file, -respectively. + - *note Copying::, and *note GNU Free Documentation License::, + present the licenses that cover the `gawk' source code and + this Info file, respectively. ---------- Footnotes ---------- @@ -1150,7 +1161,7 @@ Versions::, for information on his and other versions.) Dark Corners ------------ - Dark corners are basically fractal -- no matter how much you + Dark corners are basically fractal--no matter how much you illuminate, there's always a smaller but darker one. -- Brian Kernighan @@ -1186,7 +1197,7 @@ always available to the end user. A copy of the GPL is included for your reference (*note Copying::). The GPL applies to the C language source code for `gawk'. To find out more about the FSF and the GNU Project online, see the GNU Project's home page (http://www.gnu.org). -This Info file may also be read from their web site +This Info file may also be read from GNU's website (http://www.gnu.org/software/gawk/manual/). A shell, an editor (Emacs), highly portable optimizing C, C++, and @@ -1203,9 +1214,9 @@ from the Internet. The Info file itself has gone through multiple previous editions. Paul Rubin wrote the very first draft of `The GAWK Manual'; it was -around 40 pages in size. Diane Close and Richard Stallman improved it, -yielding a version that was around 90 pages long and barely described -the original, "old" version of `awk'. +around 40 pages long. Diane Close and Richard Stallman improved it, +yielding a version that was around 90 pages and barely described the +original, "old" version of `awk'. I started working with that version in the fall of 1988. As work on it progressed, the FSF published several preliminary versions (numbered @@ -1252,12 +1263,12 @@ contributed code: the archive did not grow and the domain went unused for several years. Late in 2008, a volunteer took on the task of setting up an -`awk'-related web site--`http://awk.info'--and did a very nice job. +`awk'-related website--`http://awk.info'--and did a very nice job. If you have written an interesting `awk' program, or have written a `gawk' extension that you would like to share with the rest of the world, please see `http://awk.info/?contribute' for how to contribute -it to the web site. +it to the website. File: gawk.info, Node: Acknowledgments, Prev: How To Contribute, Up: Preface @@ -1331,13 +1342,13 @@ continues to be a pleasure working with this team of fine people. Notable code and documentation contributions were made by a number of people. *Note Contributors::, for the full list. - Thanks to Michael Brennan for the Foreword. + Thanks to Michael Brennan for the Forewords. Thanks to Patrice Dumas for the new `makeinfo' program. Thanks to Karl Berry who continues to work to keep the Texinfo markup language sane. - Robert P.J. Day, Michael Brennan and Brian Kernighan kindly acted as + Robert P.J. Day, Michael Brennan, and Brian Kernighan kindly acted as reviewers for the 2015 edition of this Info file. Their feedback helped improve the final work. @@ -1348,8 +1359,8 @@ have done nearly as good a job on either `gawk' or its documentation without his help. Brian is in a class by himself as a programmer and technical author. -I have to thank him (yet again) for his ongoing friendship and the role -model he has been for me for close to 30 years! Having him as a +I have to thank him (yet again) for his ongoing friendship and for +being a role model to me for close to 30 years! Having him as a reviewer is an exciting privilege. It has also been extremely humbling... @@ -1370,22 +1381,22 @@ File: gawk.info, Node: Getting Started, Next: Invoking Gawk, Prev: Preface, The basic function of `awk' is to search files for lines (or other units of text) that contain certain patterns. When a line matches one of the patterns, `awk' performs specified actions on that line. `awk' -keeps processing input lines in this way until it reaches the end of -the input files. +continues to process input lines in this way until it reaches the end +of the input files. Programs in `awk' are different from programs in most other -languages, because `awk' programs are "data-driven"; that is, you -describe the data you want to work with and then what to do when you -find it. Most other languages are "procedural"; you have to describe, -in great detail, every step the program is to take. When working with +languages, because `awk' programs are "data driven" (i.e., you describe +the data you want to work with and then what to do when you find it). +Most other languages are "procedural"; you have to describe, in great +detail, every step the program should take. When working with procedural languages, it is usually much harder to clearly describe the data your program will process. For this reason, `awk' programs are often refreshingly easy to read and write. When you run `awk', you specify an `awk' "program" that tells `awk' -what to do. The program consists of a series of "rules". (It may also +what to do. The program consists of a series of "rules" (it may also contain "function definitions", an advanced feature that we will ignore -for now. *Note User-defined::.) Each rule specifies one pattern to +for now; *note User-defined::). Each rule specifies one pattern to search for and one action to perform upon finding the pattern. Syntactically, a rule consists of a pattern followed by an action. @@ -1474,7 +1485,8 @@ programs from shell scripts, because it avoids the need for a separate file for the `awk' program. A self-contained shell script is more reliable because there are no other files to misplace. - *note Very Simple::, presents several short, self-contained programs. + Later in this chapter, *note Very Simple::, presents several short, +self-contained programs. File: gawk.info, Node: Read Terminal, Next: Long, Prev: One-shot, Up: Running gawk @@ -1516,7 +1528,7 @@ ugly shell quoting tricks. This next simple `awk' program emulates the `cat' utility; it copies whatever you type on the keyboard to its standard output (why this -works is explained shortly). +works is explained shortly): $ awk '{ print }' Now is the time for all good men @@ -1608,7 +1620,7 @@ the instructions in your program. (This is different from a "compiled" language such as C, where your program is first compiled into machine code that is executed directly by your system's processor.) The `awk' utility is thus termed an "interpreter". Many modern languages are -interperted. +interpreted. The line beginning with `#!' lists the full file name of an interpreter to run and a single optional initial command-line argument @@ -1636,8 +1648,8 @@ the name of your script (`advice'). (d.c.) Don't rely on the value of ---------- Footnotes ---------- - (1) The `#!' mechanism works on GNU/Linux systems, BSD-based systems -and commercial Unix systems. + (1) The `#!' mechanism works on GNU/Linux systems, BSD-based +systems, and commercial Unix systems. File: gawk.info, Node: Comments, Next: Quoting, Prev: Executable Scripts, Up: Running gawk @@ -1651,13 +1663,13 @@ Comments can explain what the program does and how it works. Nearly all programming languages have provisions for comments, as programs are typically hard to understand without them. - In the `awk' language, a comment starts with the sharp sign + In the `awk' language, a comment starts with the number sign character (`#') and continues to the end of the line. The `#' does not have to be the first character on the line. The `awk' language ignores -the rest of a line following a sharp sign. For example, we could have +the rest of a line following a number sign. For example, we could have put the following into `advice': - # This program prints a nice friendly message. It helps + # This program prints a nice, friendly message. It helps # keep novice users from being afraid of the computer. BEGIN { print "Don't Panic!" } @@ -1666,15 +1678,15 @@ programs, but this usually isn't very useful; the purpose of a comment is to help you or another person understand the program when reading it at a later time. - CAUTION: As mentioned in *note One-shot::, you can enclose small - to medium programs in single quotes, in order to keep your shell - scripts self-contained. When doing so, _don't_ put an apostrophe - (i.e., a single quote) into a comment (or anywhere else in your - program). The shell interprets the quote as the closing quote for - the entire program. As a result, usually the shell prints a - message about mismatched quotes, and if `awk' actually runs, it - will probably print strange messages about syntax errors. For - example, look at the following: + CAUTION: As mentioned in *note One-shot::, you can enclose short + to medium-sized programs in single quotes, in order to keep your + shell scripts self-contained. When doing so, _don't_ put an + apostrophe (i.e., a single quote) into a comment (or anywhere else + in your program). The shell interprets the quote as the closing + quote for the entire program. As a result, usually the shell + prints a message about mismatched quotes, and if `awk' actually + runs, it will probably print strange messages about syntax errors. + For example, look at the following: $ awk 'BEGIN { print "hello" } # let's be cute' > @@ -1690,8 +1702,8 @@ at a later time. error--> source line number 1 Putting a backslash before the single quote in `let's' wouldn't - help, since backslashes are not special inside single quotes. The - next node describes the shell's quoting rules. + help, because backslashes are not special inside single quotes. + The next node describes the shell's quoting rules. File: gawk.info, Node: Quoting, Prev: Comments, Up: Running gawk @@ -1703,7 +1715,7 @@ File: gawk.info, Node: Quoting, Prev: Comments, Up: Running gawk * DOS Quoting:: Quoting in Windows Batch Files. - For short to medium length `awk' programs, it is most convenient to + For short to medium-length `awk' programs, it is most convenient to enter the program on the `awk' command line. This is best done by enclosing the entire program in single quotes. This is true whether you are entering the program interactively at the shell prompt, or @@ -1723,15 +1735,15 @@ string. The null string is character data that has no value. In other words, it is empty. It is written in `awk' programs like this: `""'. In the shell, it can be written using single or double quotes: `""' or -`'''. While the null string has no characters in it, it does exist. -Consider this command: +`'''. Although the null string has no characters in it, it does exist. +For example, consider this command: $ echo "" Here, the `echo' utility receives a single argument, even though that argument has no characters in it. In the rest of this Info file, we use the terms "null string" and "empty string" interchangeably. Now, on to -the quoting rules. +the quoting rules: * Quoted items can be concatenated with nonquoted items as well as with other quoted items. The shell turns everything into one @@ -1752,7 +1764,7 @@ the quoting rules. on the quoted text. Different shells may do additional kinds of processing on double-quoted text. - Since certain characters within double-quoted text are processed + Because certain characters within double-quoted text are processed by the shell, they must be "escaped" within the text. Of note are the characters `$', ``', `\', and `"', all of which must be preceded by a backslash within double-quoted text if they are to @@ -1791,7 +1803,7 @@ shell quoting tricks, like this: -| Here is a single quote <'> This program consists of three concatenated quoted strings. The first -and the third are single-quoted, the second is double-quoted. +and the third are single quoted, the second is double quoted. This can be "simplified" to: @@ -1866,7 +1878,7 @@ about monthly shipments. In both files, each line is considered to be one "record". In `mail-list', each record contains the name of a person, his/her -phone number, his/her email-address, and a code for their relationship +phone number, his/her email address, and a code for his/her relationship with the author of the list. The columns are aligned using spaces. An `A' in the last column means that the person is an acquaintance. An `F' in the last column means that the person is a friend. An `R' means @@ -1962,13 +1974,13 @@ that does nothing (i.e., no lines are printed). collection of useful, short programs to get you started. Some of these programs contain constructs that haven't been covered yet. (The description of the program will give you a good idea of what is going -on, but please read the rest of the Info file to become an `awk' -expert!) Most of the examples use a data file named `data'. This is -just a placeholder; if you use these programs yourself, substitute your -own file names for `data'. For future reference, note that there is -often more than one way to do things in `awk'. At some point, you may -want to look back at these examples and see if you can come up with -different ways to do the same things shown here: +on, but you'll need to read the rest of the Info file to become an +`awk' expert!) Most of the examples use a data file named `data'. +This is just a placeholder; if you use these programs yourself, +substitute your own file names for `data'. For future reference, note +that there is often more than one way to do things in `awk'. At some +point, you may want to look back at these examples and see if you can +come up with different ways to do the same things shown here: * Print every line that is longer than 80 characters: @@ -1990,7 +2002,7 @@ different ways to do the same things shown here: expand data | awk '{ if (x < length($0)) x = length($0) } END { print "maximum line length is " x }' - This example differs slightly from the previous one: The input is + This example differs slightly from the previous one: the input is processed by the `expand' utility to change TABs into spaces, so the widths compared are actually the right-margin columns, as opposed to the number of input characters on each line. @@ -2184,10 +2196,10 @@ or a string. the C shell._ It works for `awk' programs in files and for one-shot programs, _provided_ you are using a POSIX-compliant shell, such as the Unix Bourne shell or Bash. But the C shell - behaves differently! There, you must use two backslashes in a - row, followed by a newline. Note also that when using the C - shell, _every_ newline in your `awk' program must be escaped with - a backslash. To illustrate: + behaves differently! There you must use two backslashes in a row, + followed by a newline. Note also that when using the C shell, + _every_ newline in your `awk' program must be escaped with a + backslash. To illustrate: % awk 'BEGIN { \ ? print \\ @@ -2292,8 +2304,8 @@ edit-compile-test-debug cycle of software development. Complex programs have been written in `awk', including a complete retargetable assembler for eight-bit microprocessors (*note Glossary::, for more information), and a microcode assembler for a special-purpose -Prolog computer. While the original `awk''s capabilities were strained -by tasks of such complexity, modern versions are more capable. +Prolog computer. The original `awk''s capabilities were strained by +tasks of such complexity, but modern versions are more capable. If you find yourself writing `awk' scripts of more than, say, a few hundred lines, you might consider using a different programming @@ -2341,10 +2353,10 @@ File: gawk.info, Node: Invoking Gawk, Next: Regexp, Prev: Getting Started, U This major node covers how to run `awk', both POSIX-standard and `gawk'-specific command-line options, and what `awk' and `gawk' do with -non-option arguments. It then proceeds to cover how `gawk' searches -for source files, reading standard input along with other files, -`gawk''s environment variables, `gawk''s exit status, using include -files, and obsolete and undocumented options and/or features. +nonoption arguments. It then proceeds to cover how `gawk' searches for +source files, reading standard input along with other files, `gawk''s +environment variables, `gawk''s exit status, using include files, and +obsolete and undocumented options and/or features. Many of the options and features described here are discussed in more detail later in the Info file; feel free to skip over things in @@ -2378,8 +2390,8 @@ enclosed in [...] in these templates are optional: `awk' [OPTIONS] `-f' PROGFILE [`--'] FILE ... `awk' [OPTIONS] [`--'] `'PROGRAM'' FILE ... - Besides traditional one-letter POSIX-style options, `gawk' also -supports GNU long options. + In addition to traditional one-letter POSIX-style options, `gawk' +also supports GNU long options. It is possible to invoke `awk' with an empty program: @@ -2415,7 +2427,7 @@ The following list describes options mandated by the POSIX standard: `-f SOURCE-FILE' `--file SOURCE-FILE' Read `awk' program source from SOURCE-FILE instead of in the first - non-option argument. This option may be given multiple times; the + nonoption argument. This option may be given multiple times; the `awk' program consists of the concatenation of the contents of each specified SOURCE-FILE. @@ -2527,8 +2539,8 @@ The following list describes options mandated by the POSIX standard: applications that pass arguments through the URL; using this option prevents a malicious (or other) user from passing in options, assignments, or `awk' source code (via `-e') to the CGI - application. This option should be used with `#!' scripts (*note - Executable Scripts::), like so: + application.(1) This option should be used with `#!' scripts + (*note Executable Scripts::), like so: #! /usr/local/bin/gawk -E @@ -2594,7 +2606,7 @@ The following list describes options mandated by the POSIX standard: `-M' `--bignum' - Force arbitrary precision arithmetic on numbers. This option has + Force arbitrary-precision arithmetic on numbers. This option has no effect if `gawk' is not compiled to use the GNU MPFR and MP libraries (*note Arbitrary Precision Arithmetic::). @@ -2604,9 +2616,8 @@ The following list describes options mandated by the POSIX standard: input data (*note Nondecimal Data::). CAUTION: This option can severely break old programs. Use - with care. - - This option may disappear in a future version of `gawk'. + with care. Also note that this option may disappear in a + future version of `gawk'. `-N' `--use-lc-numeric' @@ -2627,7 +2638,8 @@ The following list describes options mandated by the POSIX standard: `-O' `--optimize' Enable some optimizations on the internal representation of the - program. At the moment this includes just simple constant folding. + program. At the moment, this includes just simple constant + folding. `-p'[FILE] `--profile'[`='FILE] @@ -2670,8 +2682,8 @@ The following list describes options mandated by the POSIX standard: `--re-interval' Allow interval expressions (*note Regexp Operators::) in regexps. This is now `gawk''s default behavior. Nevertheless, this option - remains both for backward compatibility, and for use in - combination with `--traditional'. + remains (both for backward compatibility and for use in + combination with `--traditional'). `-S' `--sandbox' @@ -2707,7 +2719,7 @@ it is, `awk' reads its program source from all of the named files, as if they had been concatenated together into one big file. This is useful for creating libraries of `awk' functions. These functions can be written once and then retrieved from a standard place, instead of -having to be included into each individual program. The `-i' option is +having to be included in each individual program. The `-i' option is similar in this regard. (As mentioned in *note Definition Syntax::, function names must be unique.) @@ -2715,7 +2727,7 @@ function names must be unique.) the program is entered at the keyboard, by specifying `-f /dev/tty'. After typing your program, type `Ctrl-d' (the end-of-file character) to terminate it. (You may also use `-f -' to read program source from the -standard input but then you will not be able to also use the standard +standard input, but then you will not be able to also use the standard input as a source of data.) Because it is clumsy using the standard `awk' mechanisms to mix @@ -2726,7 +2738,7 @@ source code (*note AWKPATH Variable::). As with `-f', the `-e' and `-i' options may also be used multiple times on the command line. If no `-f' or `-e' option is specified, then `gawk' uses the first -non-option command-line argument as the text of the program source code. +nonoption command-line argument as the text of the program source code. If the environment variable `POSIXLY_CORRECT' exists, then `gawk' behaves in strict POSIX mode, exactly as if you had supplied `--posix'. @@ -2743,7 +2755,7 @@ you would add these lines to the `.profile' file in your home directory: POSIXLY_CORRECT=true export POSIXLY_CORRECT - For a C shell-compatible shell,(1) you would add this line to the + For a C shell-compatible shell,(2) you would add this line to the `.login' file in your home directory: setenv POSIXLY_CORRECT true @@ -2754,7 +2766,12 @@ environments. ---------- Footnotes ---------- - (1) Not recommended. + (1) For more detail, please see Section 4.4 of RFC 3875 +(http://www.ietf.org/rfc/rfc3875). Also see the explanatory note sent +to the `gawk' bug mailing list +(http://lists.gnu.org/archive/html/bug-gawk/2014-11/msg00022.html). + + (2) Not recommended. File: gawk.info, Node: Other Arguments, Next: Naming Standard Input, Prev: Options, Up: Invoking Gawk @@ -2775,8 +2792,8 @@ not a file name: program in the `ARGV' array (*note Built-in Variables::). Command-line options and the program text (if present) are omitted from `ARGV'. All other arguments, including variable assignments, are included. As -each element of `ARGV' is processed, `gawk' sets the variable `ARGIND' -to the index in `ARGV' of the current element. +each element of `ARGV' is processed, `gawk' sets `ARGIND' to the index +in `ARGV' of the current element. Changing `ARGC' and `ARGV' in your `awk' program lets you control how `awk' processes the input files; this is described in more detail @@ -2923,11 +2940,11 @@ to manipulate the `AWKPATH' variable. `ENVIRON["AWKPATH"]'. This provides access to the actual search path value from within an `awk' program. - While you can change `ENVIRON["AWKPATH"]' within your `awk' program, -this has no effect on the running program's behavior. This makes -sense: the `AWKPATH' environment variable is used to find the program -source files. Once your program is running, all the files have been -found, and `gawk' no longer needs to use `AWKPATH'. + Although you can change `ENVIRON["AWKPATH"]' within your `awk' +program, this has no effect on the running program's behavior. This +makes sense: the `AWKPATH' environment variable is used to find the +program source files. Once your program is running, all the files have +been found, and `gawk' no longer needs to use `AWKPATH'. ---------- Footnotes ---------- @@ -2973,7 +2990,7 @@ File: gawk.info, Node: Other Environment Variables, Prev: AWKLIBPATH Variable, A number of other environment variables affect `gawk''s behavior, but they are more specialized. Those in the following list are meant to be -used by regular users. +used by regular users: `GAWK_MSEC_SLEEP' Specifies the interval between connection retries, in @@ -2990,7 +3007,7 @@ used by regular users. Networking::. `POSIXLY_CORRECT' - Causes `gawk' to switch to POSIX compatibility mode, disabling all + Causes `gawk' to switch to POSIX-compatibility mode, disabling all traditional and GNU extensions. *Note Options::. The environment variables in the following list are meant for use by @@ -3021,8 +3038,8 @@ change. The variables are: If this variable exists, `gawk' includes the file name and line number within the `gawk' source code from which warning and/or fatal messages are generated. Its purpose is to help isolate the - source of a message, since there are multiple places which produce - the same warning or error message. + source of a message, as there are multiple places which produce the + same warning or error message. `GAWK_NO_DFA' If this variable exists, `gawk' does not use the DFA regexp matcher @@ -3063,13 +3080,13 @@ with the value of the C constant `EXIT_SUCCESS'. This is usually zero. If an error occurs, `gawk' exits with the value of the C constant `EXIT_FAILURE'. This is usually one. - If `gawk' exits because of a fatal error, the exit status is 2. On -non-POSIX systems, this value may be mapped to `EXIT_FAILURE'. + If `gawk' exits because of a fatal error, the exit status is two. +On non-POSIX systems, this value may be mapped to `EXIT_FAILURE'. File: gawk.info, Node: Include Files, Next: Loading Shared Libraries, Prev: Exit Status, Up: Invoking Gawk -2.7 Including Other Files Into Your Program +2.7 Including Other Files into Your Program =========================================== This minor node describes a feature that is specific to `gawk'. @@ -3104,9 +3121,9 @@ and here is `test2': -| This is script test1. -| This is script test2. - `gawk' runs the `test2' script which includes `test1' using the -`@include' keyword. So, to include external `awk' source files you just -use `@include' followed by the name of the file to be included, + `gawk' runs the `test2' script, which includes `test1' using the +`@include' keyword. So, to include external `awk' source files, you +just use `@include' followed by the name of the file to be included, enclosed in double quotes. NOTE: Keep in mind that this is a language construct and the file @@ -3132,22 +3149,22 @@ Running `gawk' with the `test3' script produces the following results: @include "../io_funcs" -or: +and: @include "/usr/awklib/network" -are valid. The `AWKPATH' environment variable can be of great value -when using `@include'. The same rules for the use of the `AWKPATH' -variable in command-line file searches (*note AWKPATH Variable::) apply -to `@include' also. +are both valid. The `AWKPATH' environment variable can be of great +value when using `@include'. The same rules for the use of the +`AWKPATH' variable in command-line file searches (*note AWKPATH +Variable::) apply to `@include' also. This is very helpful in constructing `gawk' function libraries. If -you have a large script with useful, general purpose `awk' functions, +you have a large script with useful, general-purpose `awk' functions, you can break it down into library files and put those files in a special directory. You can then include those "libraries," using either the full pathnames of the files, or by setting the `AWKPATH' environment variable accordingly and then using `@include' with just -the file part of the full pathname. Of course you can have more than +the file part of the full pathname. Of course, you can have more than one directory to keep library files; the more complex the working environment is, the more directories you may need to organize the files to be included. @@ -3166,7 +3183,7 @@ and this also applies to files named with `@include'. File: gawk.info, Node: Loading Shared Libraries, Next: Obsolete, Prev: Include Files, Up: Invoking Gawk -2.8 Loading Dynamic Extensions Into Your Program +2.8 Loading Dynamic Extensions into Your Program ================================================ This minor node describes a feature that is specific to `gawk'. @@ -3181,7 +3198,7 @@ The `AWKLIBPATH' variable is used to search for the extension. Using If the extension is not initially found in `AWKLIBPATH', another search is conducted after appending the platform's default shared library suffix to the file name. For example, on GNU/Linux systems, -the suffix `.so' is used. +the suffix `.so' is used: $ gawk '@load "ordchr"; BEGIN {print chr(65)}' -| A @@ -3238,12 +3255,12 @@ File: gawk.info, Node: Invoking Summary, Prev: Undocumented, Up: Invoking Gaw `-F' and `-v'. `gawk' supplies these and many others, as well as corresponding GNU-style long options. - * Non-option command-line arguments are usually treated as file - names, unless they have the form `VAR=VALUE', in which case they - are taken as variable assignments to be performed at that point in + * Nonoption command-line arguments are usually treated as file names, + unless they have the form `VAR=VALUE', in which case they are + taken as variable assignments to be performed at that point in processing the input. - * All non-option command-line arguments, excluding the program text, + * All nonoption command-line arguments, excluding the program text, are placed in the `ARGV' array. Adjusting `ARGC' and `ARGV' affects how `awk' processes input. @@ -3282,7 +3299,7 @@ strings. Because regular expressions are such a fundamental part of that matches every input record whose text belongs to that set. The simplest regular expression is a sequence of letters, numbers, or both. Such a regexp matches any string that contains that sequence. Thus, -the regexp `foo' matches any string containing `foo'. Therefore, the +the regexp `foo' matches any string containing `foo'. Thus, the pattern `/foo/' matches any input record containing the three adjacent characters `foo' _anywhere_ in the record. Other kinds of regexps let you specify more complicated classes of strings. @@ -3323,13 +3340,13 @@ expressions allow you to specify the string to match against; it need not be the entire current input record. The two operators `~' and `!~' perform regular expression comparisons. Expressions using these operators can be used as patterns, or in `if', `while', `for', and `do' -statements. (*Note Statements::.) For example: +statements. (*Note Statements::.) For example, the following is true +if the expression EXP (taken as a string) matches REGEXP: EXP ~ /REGEXP/ -is true if the expression EXP (taken as a string) matches REGEXP. The -following example matches, or selects, all input records with the -uppercase letter `J' somewhere in the first field: +This example matches, or selects, all input records with the uppercase +letter `J' somewhere in the first field: $ awk '$1 ~ /J/' inventory-shipped -| Jan 13 25 15 115 @@ -3383,9 +3400,9 @@ string or regexp. Thus, the string whose contents are the two characters `"' and `\' must be written `"\"\\"'. Other escape sequences represent unprintable characters such as TAB -or newline. While there is nothing to stop you from entering most +or newline. There is nothing to stop you from entering most unprintable characters directly in a string constant or regexp constant, -they may look ugly. +but they may look ugly. The following list presents all the escape sequences used in `awk' and what they represent. Unless noted otherwise, all these escape @@ -3440,7 +3457,7 @@ sequences apply to both string constants and regexp constants: A literal slash (necessary for regexp constants only). This sequence is used when you want to write a regexp constant that contains a slash (such as `/.*:\/home\/[[:alnum:]]+:.*/'; the - `[[:alnum:]]' notation is discussed shortly, in *note Bracket + `[[:alnum:]]' notation is discussed in *note Bracket Expressions::). Because the regexp is delimited by slashes, you need to escape any slash that is part of the pattern, in order to tell `awk' to keep processing the rest of the regexp. @@ -3466,19 +3483,6 @@ characters `a+b'. For complete portability, do not use a backslash before any character not shown in the previous list and that is not an operator. - To summarize: - - * The escape sequences in the list above are always processed first, - for both string constants and regexp constants. This happens very - early, as soon as `awk' reads your program. - - * `gawk' processes both regexp constants and dynamic regexps (*note - Computed Regexps::), for the special operators listed in *note GNU - Regexp Operators::. - - * A backslash before any other character means to treat that - character literally. - Backslash Before Regular Characters If you place a backslash in a string constant before something that @@ -3497,6 +3501,19 @@ Leave the backslash alone Some other `awk' implementations do this. In such implementations, typing `"a\qc"' is the same as typing `"a\\qc"'. + To summarize: + + * The escape sequences in the preceding list are always processed + first, for both string constants and regexp constants. This + happens very early, as soon as `awk' reads your program. + + * `gawk' processes both regexp constants and dynamic regexps (*note + Computed Regexps::), for the special operators listed in *note GNU + Regexp Operators::. + + * A backslash before any other character means to treat that + character literally. + Escape Sequences for Metacharacters Suppose you use an octal or hexadecimal escape to represent a regexp @@ -3529,15 +3546,15 @@ in processing regexps. sequences and that are not listed in the following stand for themselves: `\' - This is used to suppress the special meaning of a character when - matching. For example, `\$' matches the character `$'. + This suppresses the special meaning of a character when matching. + For example, `\$' matches the character `$'. `^' - This matches the beginning of a string. For example, `^@chapter' - matches `@chapter' at the beginning of a string and can be used to - identify chapter beginnings in Texinfo source files. The `^' is - known as an "anchor", because it anchors the pattern to match only - at the beginning of the string. + This matches the beginning of a string. `^@chapter' matches + `@chapter' at the beginning of a string, for example, and can be + used to identify chapter beginnings in Texinfo source files. The + `^' is known as an "anchor", because it anchors the pattern to + match only at the beginning of the string. It is important to realize that `^' does not match the beginning of a line (the point right after a `\n' newline character) embedded @@ -3610,7 +3627,7 @@ sequences and that are not listed in the following stand for themselves: First, the `*' applies only to the single preceding regular expression component (e.g., in `ph*', it applies just to the `h'). To cause `*' to apply to a larger sub-expression, use parentheses: - `(ph)*' matches `ph', `phph', `phphph' and so on. + `(ph)*' matches `ph', `phph', `phphph', and so on. Second, `*' finds as many repetitions as possible. If the text to be matched is `phhhhhhhhhhhhhhooey', `ph*' matches all of the `h's. @@ -3694,7 +3711,7 @@ File: gawk.info, Node: Bracket Expressions, Next: Leftmost Longest, Prev: Reg 3.4 Using Bracket Expressions ============================= -As mentioned earlier, a bracket expression matches any character amongst +As mentioned earlier, a bracket expression matches any character among those listed between the opening and closing square brackets. Within a bracket expression, a "range expression" consists of two @@ -3734,24 +3751,24 @@ character classes defined by the POSIX standard. Class Meaning -------------------------------------------------------------------------- -`[:alnum:]' Alphanumeric characters. -`[:alpha:]' Alphabetic characters. -`[:blank:]' Space and TAB characters. -`[:cntrl:]' Control characters. -`[:digit:]' Numeric characters. -`[:graph:]' Characters that are both printable and visible. (A space is - printable but not visible, whereas an `a' is both.) -`[:lower:]' Lowercase alphabetic characters. +`[:alnum:]' Alphanumeric characters +`[:alpha:]' Alphabetic characters +`[:blank:]' Space and TAB characters +`[:cntrl:]' Control characters +`[:digit:]' Numeric characters +`[:graph:]' Characters that are both printable and visible (a space is + printable but not visible, whereas an `a' is both) +`[:lower:]' Lowercase alphabetic characters `[:print:]' Printable characters (characters that are not control - characters). + characters) `[:punct:]' Punctuation characters (characters that are not letters, - digits, control characters, or space characters). + digits control characters, or space characters) `[:space:]' Space characters (such as space, TAB, and formfeed, to name - a few). -`[:upper:]' Uppercase alphabetic characters. -`[:xdigit:]'Characters that are hexadecimal digits. + a few) +`[:upper:]' Uppercase alphabetic characters +`[:xdigit:]'Characters that are hexadecimal digits -Table 3.1: POSIX Character Classes +Table 3.1: POSIX character classes For example, before the POSIX standard, you had to write `/[A-Za-z0-9]/' to match alphanumeric characters. If your character @@ -3759,7 +3776,7 @@ set had other alphabetic characters in it, this would not match them. With the POSIX character classes, you can write `/[[:alnum:]]/' to match the alphabetic and numeric characters in your character set. - Some utilities that match regular expressions provide a non-standard + Some utilities that match regular expressions provide a nonstandard `[:ascii:]' character class; `awk' does not. However, you can simulate such a construct using `[\x00-\x7F]'. This matches all values numerically between zero and 127, which is the defined range of the @@ -3952,9 +3969,9 @@ letters, digits, or underscores (`_'): not match `dirty rat'. `\B' is essentially the opposite of `\y'. There are two other operators that work on buffers. In Emacs, a -"buffer" is, naturally, an Emacs buffer. For other programs, `gawk''s -regexp library routines consider the entire string to match as the -buffer. The operators are: +"buffer" is, naturally, an Emacs buffer. Other GNU programs, including +`gawk', consider the entire string to match as the buffer. The +operators are: `\`' Matches the empty string at the beginning of a buffer (string). @@ -3982,15 +3999,14 @@ No options Operators::. `--posix' - Only POSIX regexps are supported; the GNU operators are not special - (e.g., `\w' matches a literal `w'). Interval expressions are - allowed. + Match only POSIX regexps; the GNU operators are not special (e.g., + `\w' matches a literal `w'). Interval expressions are allowed. `--traditional' - Traditional Unix `awk' regexps are matched. The GNU operators are - not special, and interval expressions are not available. The - POSIX character classes (`[[:alnum:]]', etc.) are supported, as - BWK `awk' supports them. Characters described by octal and + Match traditional Unix `awk' regexps. The GNU operators are not + special, and interval expressions are not available. Because BWK + `awk' supports them, the POSIX character classes (`[[:alnum:]]', + etc.) are available. Characters described by octal and hexadecimal escape sequences are treated literally, even if they represent regexp metacharacters. @@ -4030,10 +4046,9 @@ works in any POSIX-compliant `awk'. `IGNORECASE' is not zero, _all_ regexp and string operations ignore case. - Changing the value of `IGNORECASE' dynamically controls the -case-sensitivity of the program as it runs. Case is significant by -default because `IGNORECASE' (like most variables) is initialized to -zero: + Changing the value of `IGNORECASE' dynamically controls the case +sensitivity of the program as it runs. Case is significant by default +because `IGNORECASE' (like most variables) is initialized to zero: x = "aB" if (x ~ /ab/) ... # this test will fail @@ -4041,17 +4056,17 @@ zero: IGNORECASE = 1 if (x ~ /ab/) ... # now it will succeed - In general, you cannot use `IGNORECASE' to make certain rules -case-insensitive and other rules case-sensitive, because there is no + In general, you cannot use `IGNORECASE' to make certain rules case +insensitive and other rules case sensitive, as there is no straightforward way to set `IGNORECASE' just for the pattern of a particular rule.(1) To do this, use either bracket expressions or `tolower()'. However, one thing you can do with `IGNORECASE' only is -dynamically turn case-sensitivity on or off for all the rules at once. +dynamically turn case sensitivity on or off for all the rules at once. `IGNORECASE' can be set on the command line or in a `BEGIN' rule (*note Other Arguments::; also *note Using BEGIN/END::). Setting -`IGNORECASE' from the command line is a way to make a program -case-insensitive without having to edit it. +`IGNORECASE' from the command line is a way to make a program case +insensitive without having to edit it. In multibyte locales, the equivalences between upper- and lowercase characters are tested based on the wide-character values of the @@ -4088,11 +4103,11 @@ File: gawk.info, Node: Regexp Summary, Prev: Case-sensitivity, Up: Regexp conditional expressions, or as part of matching expressions using the `~' and `!~' operators. - * Escape sequences let you represent non-printable characters and + * Escape sequences let you represent nonprintable characters and also let you represent regexp metacharacters as literal characters to be matched. - * Regexp operators provide grouping, alternation and repetition. + * Regexp operators provide grouping, alternation, and repetition. * Bracket expressions give you a shorthand for specifying sets of characters that can match at a particular point in a regexp. @@ -4104,8 +4119,8 @@ File: gawk.info, Node: Regexp Summary, Prev: Case-sensitivity, Up: Regexp extent of the match, such as for text substitution and when the record separator is a regexp. - * Matching expressions may use dynamic regexps, that is, string - values treated as regular expressions. + * Matching expressions may use dynamic regexps (i.e., string values + treated as regular expressions). * `gawk''s `IGNORECASE' variable lets you control the case sensitivity of regexp matching. In other `awk' versions, use @@ -4164,7 +4179,7 @@ File: gawk.info, Node: Records, Next: Fields, Up: Reading Files `awk' divides the input for your program into records and fields. It keeps track of the number of records that have been read so far from the current input file. This value is stored in a predefined variable -called `FNR' which is reset to zero every time a new file is started. +called `FNR', which is reset to zero every time a new file is started. Another predefined variable, `NR', records the total number of input records read so far from all data files. It starts at zero, but is never automatically reset to zero. @@ -4177,7 +4192,7 @@ never automatically reset to zero. File: gawk.info, Node: awk split records, Next: gawk split records, Up: Records -4.1.1 Record Splitting With Standard `awk' +4.1.1 Record Splitting with Standard `awk' ------------------------------------------ Records are separated by a character called the "record separator". By @@ -4189,7 +4204,7 @@ predefined variable `RS'. Like any other variable, the value of `RS' can be changed in the `awk' program with the assignment operator, `=' (*note Assignment Ops::). The new record-separator character should be enclosed in -quotation marks, which indicate a string constant. Often the right +quotation marks, which indicate a string constant. Often, the right time to do this is at the beginning of execution, before any input is processed, so that the very first record is read with the proper separator. To do this, use the special `BEGIN' pattern (*note @@ -4199,7 +4214,7 @@ BEGIN/END::). For example: { print $0 }' mail-list changes the value of `RS' to `u', before reading any input. This is a -string whose first character is the letter "u;" as a result, records +string whose first character is the letter "u"; as a result, records are separated by the letter "u." Then the input file is read, and the second rule in the `awk' program (the action with no pattern) prints each record. Because each `print' statement adds a newline at the end @@ -4305,7 +4320,7 @@ variable `RT' to the text in the input that matched `RS'. File: gawk.info, Node: gawk split records, Prev: awk split records, Up: Records -4.1.2 Record Splitting With `gawk' +4.1.2 Record Splitting with `gawk' ---------------------------------- When using `gawk', the value of `RS' is not limited to a one-character @@ -4345,7 +4360,7 @@ leading and trailing whitespace. The final value of `RT' is a newline. `RT'. If you set `RS' to a regular expression that allows optional -trailing text, such as `RS = "abc(XYZ)?"' it is possible, due to +trailing text, such as `RS = "abc(XYZ)?"', it is possible, due to implementation constraints, that `gawk' may match the leading part of the regular expression, but not the trailing part, particularly if the input text that could match the trailing part is fairly long. `gawk' @@ -4358,7 +4373,7 @@ that this will never happen. `RS = "^[[:upper:]]"' can only match at the beginning of a file. This is because `gawk' views the input file as one long string that happens to contain newline characters. It is thus best to - avoid anchor characters in the value of `RS'. + avoid anchor metacharacters in the value of `RS'. The use of `RS' as a regular expression and the `RT' variable are `gawk' extensions; they are not available in compatibility mode (*note @@ -4413,8 +4428,8 @@ When `awk' reads an input record, the record is automatically "parsed" or separated by the `awk' utility into chunks called "fields". By default, fields are separated by "whitespace", like words in a line. Whitespace in `awk' means any string of one or more spaces, TABs, or -newlines;(1) other characters, such as formfeed, vertical tab, etc., -that are considered whitespace by other languages, are _not_ considered +newlines;(1) other characters that are considered whitespace by other +languages (such as formfeed, vertical tab, etc.) are _not_ considered whitespace by `awk'. The purpose of fields is to make it more convenient for you to refer @@ -4425,9 +4440,9 @@ simple `awk' programs so powerful. You use a dollar-sign (`$') to refer to a field in an `awk' program, followed by the number of the field you want. Thus, `$1' refers to the first field, `$2' to the second, and so on. (Unlike the Unix shells, -the field numbers are not limited to single digits. `$127' is the one -hundred twenty-seventh field in the record.) For example, suppose the -following is a line of input: +the field numbers are not limited to single digits. `$127' is the +127th field in the record.) For example, suppose the following is a +line of input: This seems like a pretty nice example. @@ -4486,11 +4501,11 @@ example: awk '{ print $NR }' Recall that `NR' is the number of records read so far: one in the first -record, two in the second, etc. So this example prints the first field -of the first record, the second field of the second record, and so on. -For the twentieth record, field number 20 is printed; most likely, the -record has fewer than 20 fields, so this prints a blank line. Here is -another example of using expressions as field numbers: +record, two in the second, and so on. So this example prints the first +field of the first record, the second field of the second record, and so +on. For the twentieth record, field number 20 is printed; most likely, +the record has fewer than 20 fields, so this prints a blank line. Here +is another example of using expressions as field numbers: awk '{ print $(2*2) }' mail-list @@ -4520,7 +4535,7 @@ field number. ---------- Footnotes ---------- (1) A "binary operator", such as `*' for multiplication, is one that -takes two operands. The distinction is required, since `awk' also has +takes two operands. The distinction is required, because `awk' also has unary (one-operand) and ternary (three-operand) operators. @@ -4566,8 +4581,8 @@ subtracted from the second field of each line: -| Mar 5 24 34 228 ... - It is also possible to also assign contents to fields that are out -of range. For example: + It is also possible to assign contents to fields that are out of +range. For example: $ awk '{ $6 = ($5 + $4 + $3 + $2) > print $6 }' inventory-shipped @@ -4668,7 +4683,7 @@ separate the fields. record simply by setting `FS' and `OFS', and then expecting a plain `print' or `print $0' to print the modified record. - But this does not work, since nothing was done to change the record + But this does not work, because nothing was done to change the record itself. Instead, you must force the record to be rebuilt, typically with a statement such as `$1 = $1', as described earlier. @@ -4708,7 +4723,7 @@ is used by the POSIX-compliant shells (such as the Unix Bourne shell, `sh', or Bash). The value of `FS' can be changed in the `awk' program with the -assignment operator, `=' (*note Assignment Ops::). Often the right +assignment operator, `=' (*note Assignment Ops::). Often, the right time to do this is at the beginning of execution before any input has been processed, so that the very first record is read with the proper separator. To do this, use the special `BEGIN' pattern (*note @@ -4820,7 +4835,7 @@ was ignored when finding `$1', it is not part of the new `$0'. Finally, the last `print' statement prints the new `$0'. There is an additional subtlety to be aware of when using regular -expressions for field splitting. It is not well-specified in the POSIX +expressions for field splitting. It is not well specified in the POSIX standard, or anywhere else, what `^' means when splitting fields. Does the `^' match only at the beginning of the entire record? Or is each field separator a new string? It turns out that different `awk' @@ -4945,21 +4960,50 @@ the entries for users whose full name is not indicated: File: gawk.info, Node: Full Line Fields, Next: Field Splitting Summary, Prev: Command Line Field Separator, Up: Field Separators -4.5.5 Making The Full Line Be A Single Field +4.5.5 Making the Full Line Be a Single Field -------------------------------------------- Occasionally, it's useful to treat the whole input line as a single field. This can be done easily and portably simply by setting `FS' to -`"\n"' (a newline).(1) +`"\n"' (a newline):(1) awk -F'\n' 'PROGRAM' FILES ... When you do this, `$1' is the same as `$0'. + Changing `FS' Does Not Affect the Fields + + According to the POSIX standard, `awk' is supposed to behave as if +each record is split into fields at the time it is read. In +particular, this means that if you change the value of `FS' after a +record is read, the value of the fields (i.e., how they were split) +should reflect the old value of `FS', not the new one. + + However, many older implementations of `awk' do not work this way. +Instead, they defer splitting the fields until a field is actually +referenced. The fields are split using the _current_ value of `FS'! +(d.c.) This behavior can be difficult to diagnose. The following +example illustrates the difference between the two methods. (The +`sed'(2) command prints just the first line of `/etc/passwd'.) + + sed 1q /etc/passwd | awk '{ FS = ":" ; print $1 }' + +which usually prints: + + root + +on an incorrect implementation of `awk', while `gawk' prints the full +first line of the file, something like: + + root:x:0:0:Root:/: + ---------- Footnotes ---------- (1) Thanks to Andrew Schorr for this tip. + (2) The `sed' utility is a "stream editor." Its behavior is also +defined by the POSIX standard. + File: gawk.info, Node: Field Splitting Summary, Prev: Full Line Fields, Up: Field Separators @@ -4998,32 +5042,6 @@ value of `FS' (`==' means "is equal to"): (This is a common extension; it is not specified by the POSIX standard.) - Changing `FS' Does Not Affect the Fields - - According to the POSIX standard, `awk' is supposed to behave as if -each record is split into fields at the time it is read. In -particular, this means that if you change the value of `FS' after a -record is read, the value of the fields (i.e., how they were split) -should reflect the old value of `FS', not the new one. - - However, many older implementations of `awk' do not work this way. -Instead, they defer splitting the fields until a field is actually -referenced. The fields are split using the _current_ value of `FS'! -(d.c.) This behavior can be difficult to diagnose. The following -example illustrates the difference between the two methods. (The -`sed'(1) command prints just the first line of `/etc/passwd'.) - - sed 1q /etc/passwd | awk '{ FS = ":" ; print $1 }' - -which usually prints: - - root - -on an incorrect implementation of `awk', while `gawk' prints the full -first line of the file, something like: - - root:nSijPlPhZZwgE:0:0:Root:/: - `FS' and `IGNORECASE' The `IGNORECASE' variable (*note User-modified::) affects field @@ -5038,23 +5056,17 @@ Thus, in the following code: The output is `aCa'. If you really want to split fields on an alphabetic character while ignoring case, use a regexp that will do it -for you. E.g., `FS = "[c]"'. In this case, `IGNORECASE' will take +for you (e.g., `FS = "[c]"'). In this case, `IGNORECASE' will take effect. - ---------- Footnotes ---------- - - (1) The `sed' utility is a "stream editor." Its behavior is also -defined by the POSIX standard. - File: gawk.info, Node: Constant Size, Next: Splitting By Content, Prev: Field Separators, Up: Reading Files 4.6 Reading Fixed-Width Data ============================ - NOTE: This minor node discusses an advanced feature of `gawk'. If - you are a novice `awk' user, you might want to skip it on the - first reading. +This minor node discusses an advanced feature of `gawk'. If you are a +novice `awk' user, you might want to skip it on the first reading. `gawk' provides a facility for dealing with fixed-width fields with no distinctive field separator. For example, data of this nature @@ -5090,13 +5102,10 @@ use of `FIELDWIDTHS': brent ttyp0 26Jun91 4:46 26:46 4:41 bash dave ttyq4 26Jun9115days 46 46 wnewmail - The following program takes the above input, converts the idle time -to number of seconds, and prints out the first two fields and the + The following program takes this input, converts the idle time to +number of seconds, and prints out the first two fields and the calculated idle time: - NOTE: This program uses a number of `awk' features that haven't - been introduced yet. - BEGIN { FIELDWIDTHS = "9 6 10 6 7 7 35" } NR > 2 { idle = $4 @@ -5113,6 +5122,9 @@ calculated idle time: print $1, $2, idle } + NOTE: The preceding program uses a number of `awk' features that + haven't been introduced yet. + Running the program on the data produces the following results: hzuo ttyV0 0 @@ -5156,12 +5168,11 @@ of such a function). File: gawk.info, Node: Splitting By Content, Next: Multiple Line, Prev: Constant Size, Up: Reading Files -4.7 Defining Fields By Content +4.7 Defining Fields by Content ============================== - NOTE: This minor node discusses an advanced feature of `gawk'. If - you are a novice `awk' user, you might want to skip it on the - first reading. +This minor node discusses an advanced feature of `gawk'. If you are a +novice `awk' user, you might want to skip it on the first reading. Normally, when using `FS', `gawk' defines the fields as the parts of the record that occur in between each field separator. In other words, @@ -5169,14 +5180,13 @@ the record that occur in between each field separator. In other words, However, there are times when you really want to define the fields by what they are, and not by what they are not. - The most notorious such case is so-called "comma separated value" + The most notorious such case is so-called "comma-separated values" (CSV) data. Many spreadsheet programs, for example, can export their data into text files, where each record is terminated with a newline, and fields are separated by commas. If only commas separated the data, there wouldn't be an issue. The problem comes when one of the fields -contains an _embedded_ comma. While there is no formal standard -specification for CSV data(1), in such cases, most programs embed the -field in double quotes. So we might have data like this: +contains an _embedded_ comma. In such cases, most programs embed the +field in double quotes.(1) So we might have data like this: Robbins,Arnold,"1234 A Pretty Street, NE",MyTown,MyState,12345-6789,USA @@ -5184,7 +5194,7 @@ field in double quotes. So we might have data like this: value of `FPAT' should be a string that provides a regular expression. This regular expression describes the contents of each field. - In the case of CSV data as presented above, each field is either + In the case of CSV data as presented here, each field is either "anything that is not a comma," or "a double quote, anything that is not a double quote, and a closing double quote." If written as a regular expression constant (*note Regexp::), we would have @@ -5238,8 +5248,8 @@ being used. NOTE: Some programs export CSV data that contains embedded newlines between the double quotes. `gawk' provides no way to - deal with this. Since there is no formal specification for CSV - data, there isn't much more to be done; the `FPAT' mechanism + deal with this. Even though a formal specification for CSV data + exists, there isn't much more to be done; the `FPAT' mechanism provides an elegant solution for the majority of cases, and the `gawk' developers are satisfied with that. @@ -5259,7 +5269,9 @@ based on which of the three variables--`FS', `FIELDWIDTHS', and ---------- Footnotes ---------- - (1) At least, we don't know of one. + (1) The CSV format lacked a formal standard definition for many +years. RFC 4180 (http://www.ietf.org/rfc/rfc4180.txt) standardizes the +most common practices. File: gawk.info, Node: Multiple Line, Next: Getline, Prev: Splitting By Content, Up: Reading Files @@ -5365,7 +5377,7 @@ A simple program to process this file is as follows: -| ... - *Note Labels Program::, for a more realistic program that deals with + *Note Labels Program::, for a more realistic program dealing with address lists. The following list summarizes how records are split, based on the value of `RS'. (`==' means "is equal to.") @@ -5430,7 +5442,7 @@ describing the error that occurred. represents a shell command. NOTE: When `--sandbox' is specified (*note Options::), reading - lines from files, pipes and coprocesses is disabled. + lines from files, pipes, and coprocesses is disabled. * Menu: @@ -5547,7 +5559,7 @@ and produces these results: free The `getline' command used in this way sets only the variables `NR', -`FNR' and `RT' (and of course, VAR). The record is not split into +`FNR', and `RT' (and of course, VAR). The record is not split into fields, so the values of the fields (including `$0') and the value of `NF' do not change. @@ -5591,8 +5603,8 @@ File: gawk.info, Node: Getline/Variable/File, Next: Getline/Pipe, Prev: Getli ------------------------------------------------- Use `getline VAR < FILE' to read input from the file FILE, and put it -in the variable VAR. As above, FILE is a string-valued expression that -specifies the file from which to read. +in the variable VAR. As earlier, FILE is a string-valued expression +that specifies the file from which to read. In this version of `getline', none of the predefined variables are changed and the record is not split into fields. The only variable @@ -5803,7 +5815,7 @@ in mind: * Using `FILENAME' with `getline' (`getline < FILENAME') is likely to be a source for confusion. `awk' opens a separate input stream from the current input file. However, by not using a variable, - `$0' and `NR' are still updated. If you're doing this, it's + `$0' and `NF' are still updated. If you're doing this, it's probably by accident, and you should reconsider what it is you're trying to accomplish. @@ -5858,19 +5870,19 @@ COMMAND `|& getline' Sets `$0', `NF', and `RT' `gawk' COMMAND `|& getline' Sets VAR and `RT' `gawk' VAR -Table 4.1: `getline' Variants and What They Set +Table 4.1: `getline' variants and what they set File: gawk.info, Node: Read Timeout, Next: Command-line directories, Prev: Getline, Up: Reading Files -4.10 Reading Input With A Timeout +4.10 Reading Input with a Timeout ================================= This minor node describes a feature that is specific to `gawk'. You may specify a timeout in milliseconds for reading input from the keyboard, a pipe, or two-way communication, including TCP/IP sockets. -This can be done on a per input, command or connection basis, by +This can be done on a per input, command, or connection basis, by setting a special element in the `PROCINFO' array (*note Auto-set::): PROCINFO["input_name", "READ_TIMEOUT"] = TIMEOUT IN MILLISECONDS @@ -5922,20 +5934,20 @@ input to arrive: PROCINFO[Service, "READ_TIMEOUT"] = 1000 while ((Service |& getline) > 0) { print $0 - PROCINFO[S, "READ_TIMEOUT"] -= 100 + PROCINFO[Service, "READ_TIMEOUT"] -= 100 } NOTE: You should not assume that the read operation will block exactly after the tenth record has been printed. It is possible that `gawk' will read and buffer more than one record's worth of data the first time. Because of this, changing the value of - timeout like in the above example is not very useful. + timeout like in the preceding example is not very useful. - If the `PROCINFO' element is not present and the environment -variable `GAWK_READ_TIMEOUT' exists, `gawk' uses its value to -initialize the timeout value. The exclusive use of the environment -variable to specify timeout has the disadvantage of not being able to -control it on a per command or connection basis. + If the `PROCINFO' element is not present and the `GAWK_READ_TIMEOUT' +environment variable exists, `gawk' uses its value to initialize the +timeout value. The exclusive use of the environment variable to +specify timeout has the disadvantage of not being able to control it on +a per command or connection basis. `gawk' considers a timeout event to be an error even though the attempt to read from the underlying device may succeed in a later @@ -5957,7 +5969,7 @@ writing. File: gawk.info, Node: Command-line directories, Next: Input Summary, Prev: Read Timeout, Up: Reading Files -4.11 Directories On The Command Line +4.11 Directories on the Command Line ==================================== According to the POSIX standard, files named on the `awk' command line @@ -5968,7 +5980,7 @@ of `awk' treat a directory on the command line as a fatal error. line, but otherwise ignores it. This makes it easier to use shell wildcards with your `awk' program: - $ gawk -f whizprog.awk * Directories could kill this progam + $ gawk -f whizprog.awk * Directories could kill this program If either of the `--posix' or `--traditional' options is given, then `gawk' reverts to treating a directory on the command line as a fatal @@ -5987,6 +5999,7 @@ File: gawk.info, Node: Input Summary, Next: Input Exercises, Prev: Command-li possibilities are as follows: Value of `RS' Records are split on `awk' / `gawk' + ... ---------------------------------------------------------------------- Any single That character `awk' character @@ -6002,8 +6015,8 @@ File: gawk.info, Node: Input Summary, Next: Input Exercises, Prev: Command-li * `gawk' sets `RT' to the text matched by `RS'. * After splitting the input into records, `awk' further splits the - record into individual fields, named `$1', `$2' and so on. `$0' is - the whole record, and `NF' indicates how many fields there are. + record into individual fields, named `$1', `$2', and so on. `$0' + is the whole record, and `NF' indicates how many fields there are. The default way to split fields is between whitespace characters. * Fields may be referenced using a variable, as in `$NF'. Fields @@ -6014,7 +6027,7 @@ File: gawk.info, Node: Input Summary, Next: Input Exercises, Prev: Command-li does the same thing. Decrementing `NF' throws away fields and rebuilds the record. - * Field splitting is more complicated than record splitting. + * Field splitting is more complicated than record splitting: Field separator value Fields are split ... `awk' / `gawk' @@ -6231,14 +6244,15 @@ separated by commas. In the output, the items are normally separated by single spaces. However, this doesn't need to be the case; a single space is simply the default. Any string of characters may be used as the "output field separator" by setting the predefined variable `OFS'. -The initial value of this variable is the string `" "'--that is, a -single space. +The initial value of this variable is the string `" "' (i.e., a single +space). The output from an entire `print' statement is called an "output record". Each `print' statement outputs one output record, and then outputs a string called the "output record separator" (or `ORS'). The -initial value of `ORS' is the string `"\n"'; i.e., a newline character. -Thus, each `print' statement normally makes a separate line. +initial value of `ORS' is the string `"\n"' (i.e., a newline +character). Thus, each `print' statement normally makes a separate +line. In order to change how output fields and records are separated, assign new values to the variables `OFS' and `ORS'. The usual place to @@ -6337,10 +6351,10 @@ A simple `printf' statement looks like this: printf FORMAT, ITEM1, ITEM2, ... -As print `print', the entire list of arguments may optionally be -enclosed in parentheses. Here too, the parentheses are necessary if any -of the item expressions use the `>' relational operator; otherwise, it -can be confused with an output redirection (*note Redirection::). +As for `print', the entire list of arguments may optionally be enclosed +in parentheses. Here too, the parentheses are necessary if any of the +item expressions use the `>' relational operator; otherwise, it can be +confused with an output redirection (*note Redirection::). The difference between `printf' and `print' is the FORMAT argument. This is an expression whose value is taken as a string; it specifies @@ -6366,7 +6380,7 @@ statements. For example: > }' -| Don't Panic! -Here, neither the `+' nor the `OUCH' appear in the output message. +Here, neither the `+' nor the `OUCH!' appear in the output message. File: gawk.info, Node: Control Letters, Next: Format Modifiers, Prev: Basic Printf, Up: Printf @@ -6423,9 +6437,9 @@ width. Here is a list of the format-control letters: of which follow the decimal point. (The `4.3' represents two modifiers, discussed in the next node.) - On systems supporting IEEE 754 floating point format, values + On systems supporting IEEE 754 floating-point format, values representing negative infinity are formatted as `-inf' or - `-infinity', and positive infinity as `inf' and `infinity'. The + `-infinity', and positive infinity as `inf' or `infinity'. The special "not a number" value formats as `-nan' or `nan' (*note Math Definitions::). @@ -6449,7 +6463,7 @@ width. Here is a list of the format-control letters: `%u' Print an unsigned decimal integer. (This format is of marginal - use, because all numbers in `awk' are floating-point; it is + use, because all numbers in `awk' are floating point; it is provided primarily for compatibility with C.) `%x', `%X' @@ -6499,7 +6513,7 @@ which they may appear: messages at runtime. *Note Printf Ordering::, which describes how and why to use positional specifiers. For now, we ignore them. -`-' +`- (Minus)' The minus sign, used before the width modifier (see later on in this list), says to left-justify the argument within its specified width. Normally, the argument is printed right-justified in the @@ -6520,7 +6534,7 @@ which they may appear: space modifier. `#' - Use an "alternate form" for certain control letters. For `%o', + Use an "alternative form" for certain control letters. For `%o', supply a leading zero. For `%x' and `%X', supply a leading `0x' or `0X' for a nonzero result. For `%e', `%E', `%f', and `%F', the result always contains a decimal point. For `%g' and `%G', @@ -6534,7 +6548,7 @@ which they may appear: `'' A single quote or apostrophe character is a POSIX extension to ISO - C. It indicates that the integer part of a floating point value, + C. It indicates that the integer part of a floating-point value, or the entire part of an integer decimal value, should have a thousands-separator character in it. This only works in locales that support such characters. For example: @@ -6599,10 +6613,10 @@ which they may appear: prints `foob'. - The C library `printf''s dynamic WIDTH and PREC capability (for -example, `"%*.*s"') is supported. Instead of supplying explicit WIDTH -and/or PREC values in the format string, they are passed in the -argument list. For example: + The C library `printf''s dynamic WIDTH and PREC capability (e.g., +`"%*.*s"') is supported. Instead of supplying explicit WIDTH and/or +PREC values in the format string, they are passed in the argument list. +For example: w = 5 p = 3 @@ -6680,8 +6694,9 @@ beginning of the `awk' program: print "---- ------" } { printf "%-10s %s\n", $1, $2 }' mail-list - The above example mixes `print' and `printf' statements in the same -program. Using just `printf' statements can produce the same results: + The preceding example mixes `print' and `printf' statements in the +same program. Using just `printf' statements can produce the same +results: awk 'BEGIN { printf "%-10s %s\n", "Name", "Number" printf "%-10s %s\n", "----", "------" } @@ -6822,7 +6837,7 @@ a file, and then to use `>>' for subsequent output: This is indeed how redirections must be used from the shell. But in `awk', it isn't necessary. In this kind of case, a program should use -`>' for all the `print' statements, since the output file is only +`>' for all the `print' statements, because the output file is only opened once. (It happens that if you mix `>' and `>>' that output is produced in the expected order. However, mixing the operators for the same file is definitely poor style, and is confusing to readers of your @@ -6894,7 +6909,7 @@ that happens, writing to the screen is not correct. In fact, if `awk' is run from a background job, it may not have a terminal at all. Then opening `/dev/tty' fails. - `gawk', BWK `awk' and `mawk' provide special file names for + `gawk', BWK `awk', and `mawk' provide special file names for accessing the three standard streams. If the file name matches one of these special names when `gawk' (or one of the others) redirects input or output, then it directly uses the descriptor that the file name @@ -6919,10 +6934,10 @@ becomes: redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results. - `gawk' does not treat these file names as special when in POSIX -compatibility mode. However, since BWK `awk' supports them, `gawk' does -support them even when invoked with the `--traditional' option (*note -Options::). + `gawk' does not treat these file names as special when in +POSIX-compatibility mode. However, because BWK `awk' supports them, +`gawk' does support them even when invoked with the `--traditional' +option (*note Options::). ---------- Footnotes ---------- @@ -6934,7 +6949,7 @@ File: gawk.info, Node: Special Files, Next: Close Files And Pipes, Prev: Spec 5.8 Special File Names in `gawk' ================================ -Besides access to standard input, stanard output, and standard error, +Besides access to standard input, standard output, and standard error, `gawk' provides access to any open file descriptor. Additionally, there are special file names reserved for TCP/IP networking. @@ -6981,7 +6996,7 @@ form: `/NET-TYPE/PROTOCOL/LOCAL-PORT/REMOTE-HOST/REMOTE-PORT' - The NET-TYPE is one of `inet', `inet4' or `inet6'. The PROTOCOL is + The NET-TYPE is one of `inet', `inet4', or `inet6'. The PROTOCOL is one of `tcp' or `udp', and the other fields represent the other essential pieces of information for making a networking connection. These file names are used with the `|&' operator for communicating with @@ -7123,9 +7138,10 @@ terminated;(1) more importantly, the file descriptor for the pipe is not closed and released until `close()' is called or `awk' exits. `close()' silently does nothing if given an argument that does not -represent a file, pipe or coprocess that was opened with a redirection. -In such a case, it returns a negative value, indicating an error. In -addition, `gawk' sets `ERRNO' to a string indicating the error. +represent a file, pipe, or coprocess that was opened with a +redirection. In such a case, it returns a negative value, indicating +an error. In addition, `gawk' sets `ERRNO' to a string indicating the +error. Note also that `close(FILENAME)' has no "magic" effects on the implicit loop that reads through the files named on the command line. @@ -7146,8 +7162,8 @@ describes it in more detail and gives an example. Using `close()''s Return Value In many older versions of Unix `awk', the `close()' function is -actually a statement. It is a syntax error to try and use the return -value from `close()': (d.c.) +actually a statement. (d.c.) It is a syntax error to try and use the +return value from `close()': command = "..." command | getline info @@ -7200,9 +7216,9 @@ File: gawk.info, Node: Output Summary, Next: Output Exercises, Prev: Close Fi pipes, and coprocesses. * `gawk' provides special file names for access to standard input, - output and error, and for network communications. + output, and error, and for network communications. - * Use `close()' to close open file, pipe and coprocess redirections. + * Use `close()' to close open file, pipe, and coprocess redirections. For coprocesses, it is possible to close only one direction of the communications. @@ -7262,8 +7278,8 @@ operators. File: gawk.info, Node: Values, Next: All Operators, Up: Expressions -6.1 Constants, Variables and Conversions -======================================== +6.1 Constants, Variables, and Conversions +========================================= Expressions are built up from values and the operations performed upon them. This minor node describes the elementary objects which provide @@ -7289,7 +7305,7 @@ regular expression. Each is used in the appropriate context when you need a data value that isn't going to change. Numeric constants can have different -forms, but are stored identically internally. +forms, but are internally stored in an identical manner. * Menu: @@ -7313,7 +7329,7 @@ the same value: 1050e-1 A string constant consists of a sequence of characters enclosed in -double-quotation marks. For example: +double quotation marks. For example: "parrot" @@ -7326,7 +7342,7 @@ codes. ---------- Footnotes ---------- (1) The internal representation of all numbers, including integers, -uses double precision floating-point numbers. On most modern systems, +uses double-precision floating-point numbers. On most modern systems, these are in IEEE 754 standard format. *Note Arbitrary Precision Arithmetic::, for much more information. @@ -7336,17 +7352,17 @@ File: gawk.info, Node: Nondecimal-numbers, Next: Regexp Constants, Prev: Scal 6.1.1.2 Octal and Hexadecimal Numbers ..................................... -In `awk', all numbers are in decimal; i.e., base 10. Many other +In `awk', all numbers are in decimal (i.e., base 10). Many other programming languages allow you to specify numbers in other bases, often octal (base 8) and hexadecimal (base 16). In octal, the numbers go 0, -1, 2, 3, 4, 5, 6, 7, 10, 11, 12, etc. Just as `11', in decimal, is 1 -times 10 plus 1, so `11', in octal, is 1 times 8, plus 1. This equals 9 -in decimal. In hexadecimal, there are 16 digits. Since the everyday -decimal number system only has ten digits (`0'-`9'), the letters `a' -through `f' are used to represent the rest. (Case in the letters is -usually irrelevant; hexadecimal `a' and `A' have the same value.) -Thus, `11', in hexadecimal, is 1 times 16 plus 1, which equals 17 in -decimal. +1, 2, 3, 4, 5, 6, 7, 10, 11, 12, and so on. Just as `11', in decimal, +is 1 times 10 plus 1, so `11', in octal, is 1 times 8, plus 1. This +equals 9 in decimal. In hexadecimal, there are 16 digits. Because the +everyday decimal number system only has ten digits (`0'-`9'), the +letters `a' through `f' are used to represent the rest. (Case in the +letters is usually irrelevant; hexadecimal `a' and `A' have the same +value.) Thus, `11', in hexadecimal, is 1 times 16 plus 1, which equals +17 in decimal. Just by looking at plain `11', you can't tell what base it's in. So, in C, C++, and other languages derived from C, there is a special @@ -7384,7 +7400,7 @@ manipulation functions; see *note Bitwise Functions::, for more information. Unlike some early C implementations, `8' and `9' are not valid in -octal constants; e.g., `gawk' treats `018' as decimal 18: +octal constants. For example, `gawk' treats `018' as decimal 18: $ gawk 'BEGIN { print "021 is", 021 ; print 018 }' -| 021 is 17 @@ -7427,8 +7443,8 @@ When used on the righthand side of the `~' or `!~' operators, a regexp constant merely stands for the regexp that is to be matched. However, regexp constants (such as `/foo/') may be used like simple expressions. When a regexp constant appears by itself, it has the same meaning as if -it appeared in a pattern, i.e., `($0 ~ /foo/)' (d.c.) *Note Expression -Patterns::. This means that the following two code segments: +it appeared in a pattern (i.e., `($0 ~ /foo/)'). (d.c.) *Note +Expression Patterns::. This means that the following two code segments: if ($0 ~ /barfly/ || $0 ~ /camelot/) print "found" @@ -7492,8 +7508,8 @@ the user-defined function `mysub()', which in turn passes it on to either `sub()' or `gsub()'. However, what really happens is that the `pat' parameter is either one or zero, depending upon whether or not `$0' matches `/hi/'. `gawk' issues a warning when it sees a regexp -constant used as a parameter to a user-defined function, since passing -a truth value in this way is probably not what was intended. +constant used as a parameter to a user-defined function, because +passing a truth value in this way is probably not what was intended. File: gawk.info, Node: Variables, Next: Conversion, Prev: Using Constant Regexps, Up: Values @@ -7533,7 +7549,7 @@ variable's current value. Variables are given new values with "assignment operators", "increment operators", and "decrement operators". *Note Assignment Ops::. In addition, the `sub()' and `gsub()' functions can change a variable's value, and the `match()', -`split()' and `patsplit()' functions can change the contents of their +`split()', and `patsplit()' functions can change the contents of their array parameters. *Note String Functions::. A few variables have special built-in meanings, such as `FS' (the @@ -7605,7 +7621,7 @@ File: gawk.info, Node: Conversion, Prev: Variables, Up: Values 6.1.4 Conversion of Strings and Numbers --------------------------------------- -Number to string and string to number conversion are generally +Number-to-string and string-to-number conversion are generally straightforward. There can be subtleties to be aware of; this minor node discusses this important facet of `awk'. @@ -7618,7 +7634,7 @@ node discusses this important facet of `awk'. File: gawk.info, Node: Strings And Numbers, Next: Locale influences conversions, Up: Conversion -6.1.4.1 How `awk' Converts Between Strings And Numbers +6.1.4.1 How `awk' Converts Between Strings and Numbers ...................................................... Strings are converted to numbers and numbers are converted to strings, @@ -7641,7 +7657,7 @@ string, concatenate that number with the empty string, `""'. To force a string to be converted to a number, add zero to that string. A string is converted to a number by interpreting any numeric prefix of the string as numerals: `"2.5"' converts to 2.5, `"1e3"' converts to -1000, and `"25fix"' has a numeric value of 25. Strings that can't be +1,000, and `"25fix"' has a numeric value of 25. Strings that can't be interpreted as valid numbers convert to zero. The exact manner in which numbers are converted into strings is @@ -7670,7 +7686,7 @@ value of `CONVFMT' may be. Given the following code fragment: `b' has the value `"12"', not `"12.00"'. (d.c.) - Pre-POSIX `awk' Used `OFMT' For String Conversion + Pre-POSIX `awk' Used `OFMT' for String Conversion Prior to the POSIX standard, `awk' used the value of `OFMT' for converting numbers to strings. `OFMT' specifies the output format to @@ -7707,7 +7723,7 @@ separator, if they have one. decimal point when reading the `awk' program source code, and for command-line variable assignments (*note Other Arguments::). However, when interpreting input data, for `print' and `printf' output, and for -number to string conversion, the local decimal point character is used. +number-to-string conversion, the local decimal point character is used. (d.c.) In all cases, numbers in source code and in input data cannot have a thousands separator. Here are some examples indicating the difference in behavior, on a GNU/Linux system: @@ -7729,7 +7745,7 @@ full number including the fractional part, 4.321. Some earlier versions of `gawk' fully complied with this aspect of the standard. However, many users in non-English locales complained -about this behavior, since their data used a period as the decimal +about this behavior, because their data used a period as the decimal point, so the default behavior was restored to use a period as the decimal point character. You can use the `--use-lc-numeric' option (*note Options::) to force `gawk' to use the locale's decimal point @@ -7748,9 +7764,9 @@ Feature Default `--posix' or `--use-lc-numeric' Input Use period Use locale `strtonum()'Use period Use locale -Table 6.1: Locale Decimal Point versus A Period +Table 6.1: Locale decimal point versus a period - Finally, modern day formal standards and IEEE standard floating point + Finally, modern day formal standards and IEEE standard floating-point representation can have an unusual but important effect on the way `gawk' converts some special string values to numbers. The details are presented in *note POSIX Floating Point Problems::. @@ -7758,7 +7774,7 @@ presented in *note POSIX Floating Point Problems::. File: gawk.info, Node: All Operators, Next: Truth Values and Conditions, Prev: Values, Up: Expressions -6.2 Operators: Doing Something With Values +6.2 Operators: Doing Something with Values ========================================== This minor node introduces the "operators" which make use of the values @@ -7820,9 +7836,9 @@ order from the highest precedence to the lowest: Division; because all numbers in `awk' are floating-point numbers, the result is _not_ rounded to an integer--`3 / 4' has the value 0.75. (It is a common mistake, especially for C - programmers, to forget that _all_ numbers in `awk' are - floating-point, and that division of integer-looking constants - produces a real number, not an integer.) + programmers, to forget that _all_ numbers in `awk' are floating + point, and that division of integer-looking constants produces a + real number, not an integer.) `X % Y' Remainder; further discussion is provided in the text, just after @@ -7884,7 +7900,7 @@ runs together. For example: ... Because string concatenation does not have an explicit operator, it -is often necessary to insure that it happens at the right time by using +is often necessary to ensure that it happens at the right time by using parentheses to enclose the items to concatenate. For example, you might expect that the following code fragment concatenates `file' and `name': @@ -8059,7 +8075,7 @@ righthand expression. For example: The indices of `bar' are practically guaranteed to be different, because `rand()' returns different values each time it is called. (Arrays and the `rand()' function haven't been covered yet. *Note Arrays::, and -see *note Numeric Functions::, for more information). This example +*note Numeric Functions::, for more information). This example illustrates an important fact about assignment operators: the lefthand expression is only evaluated _once_. @@ -8077,16 +8093,16 @@ converted to a number. Operator Effect -------------------------------------------------------------------------- -LVALUE `+=' INCREMENT Add INCREMENT to the value of LVALUE. -LVALUE `-=' DECREMENT Subtract DECREMENT from the value of LVALUE. -LVALUE `*=' Multiply the value of LVALUE by COEFFICIENT. +LVALUE `+=' INCREMENT Add INCREMENT to the value of LVALUE +LVALUE `-=' DECREMENT Subtract DECREMENT from the value of LVALUE +LVALUE `*=' Multiply the value of LVALUE by COEFFICIENT COEFFICIENT -LVALUE `/=' DIVISOR Divide the value of LVALUE by DIVISOR. -LVALUE `%=' MODULUS Set LVALUE to its remainder by MODULUS. +LVALUE `/=' DIVISOR Divide the value of LVALUE by DIVISOR +LVALUE `%=' MODULUS Set LVALUE to its remainder by MODULUS LVALUE `^=' POWER -LVALUE `**=' POWER Raise LVALUE to the power POWER. (c.e.) +LVALUE `**=' POWER Raise LVALUE to the power POWER (c.e.) -Table 6.2: Arithmetic Assignment Operators +Table 6.2: Arithmetic assignment operators NOTE: Only the `^=' operator is specified by POSIX. For maximum portability, do not use the `**=' operator. @@ -8135,7 +8151,7 @@ effect of incrementing it. The post-increment `foo++' is nearly the same as writing `(foo += 1) - 1'. It is not perfectly equivalent because all numbers in `awk' are -floating-point--in floating-point, `foo + 1 - 1' does not necessarily +floating point--in floating point, `foo + 1 - 1' does not necessarily equal `foo'. But the difference is minute as long as you stick to numbers that are fairly small (less than 10e12). @@ -8199,8 +8215,8 @@ File: gawk.info, Node: Truth Values and Conditions, Next: Function Calls, Pre 6.3 Truth Values and Conditions =============================== -In certain contexts, expression values also serve as "truth values;" -i.e., they determine what should happen next as the program runs. This +In certain contexts, expression values also serve as "truth values"; +(i.e., they determine what should happen next as the program runs). This minor node describes how `awk' defines "true" and "false" and how values are compared. @@ -8251,8 +8267,8 @@ File: gawk.info, Node: Typing and Comparison, Next: Boolean Ops, Prev: Truth 6.3.2 Variable Typing and Comparison Expressions ------------------------------------------------ - The Guide is definitive. Reality is frequently inaccurate. -- The - Hitchhiker's Guide to the Galaxy + The Guide is definitive. Reality is frequently inaccurate. -- + Douglas Adams, `The Hitchhiker's Guide to the Galaxy' Unlike other programming languages, `awk' variables do not have a fixed type. Instead, they can be either a number or a string, depending @@ -8268,7 +8284,7 @@ are typed, and how `awk' compares variables. File: gawk.info, Node: Variable Typing, Next: Comparison Operators, Up: Typing and Comparison -6.3.2.1 String Type Versus Numeric Type +6.3.2.1 String Type versus Numeric Type ....................................... The POSIX standard introduced the concept of a "numeric string", which @@ -8285,7 +8301,7 @@ determine how they are compared. Variable typing follows these rules: * Fields, `getline' input, `FILENAME', `ARGV' elements, `ENVIRON' elements, and the elements of an array created by `match()', - `split()' and `patsplit()' that are numeric strings have the + `split()', and `patsplit()' that are numeric strings have the STRNUM attribute. Otherwise, they have the STRING attribute. Uninitialized variables also have the STRNUM attribute. @@ -8366,19 +8382,19 @@ them. Expression Result -------------------------------------------------------------------------- -X `<' Y True if X is less than Y. -X `<=' Y True if X is less than or equal to Y. -X `>' Y True if X is greater than Y. -X `>=' Y True if X is greater than or equal to Y. -X `==' Y True if X is equal to Y. -X `!=' Y True if X is not equal to Y. -X `~' Y True if the string X matches the regexp denoted by Y. +X `<' Y True if X is less than Y +X `<=' Y True if X is less than or equal to Y +X `>' Y True if X is greater than Y +X `>=' Y True if X is greater than or equal to Y +X `==' Y True if X is equal to Y +X `!=' Y True if X is not equal to Y +X `~' Y True if the string X matches the regexp denoted by Y X `!~' Y True if the string X does not match the regexp - denoted by Y. + denoted by Y SUBSCRIPT `in' True if the array ARRAY has an element with the -ARRAY subscript SUBSCRIPT. +ARRAY subscript SUBSCRIPT -Table 6.3: Relational Operators +Table 6.3: Relational operators Comparison expressions have the value one if true and zero if false. When comparing operands of mixed types, numeric operands are converted @@ -8408,24 +8424,24 @@ comparisons `awk' performs, as well as what the result of each comparison is: `1.5 <= 2.0' - numeric comparison (true) + Numeric comparison (true) `"abc" >= "xyz"' - string comparison (false) + String comparison (false) `1.5 != " +2"' - string comparison (true) + String comparison (true) `"1e2" < "3"' - string comparison (true) + String comparison (true) `a = 2; b = "2"' `a == b' - string comparison (true) + String comparison (true) `a = 2; b = " +2"' `a == b' - string comparison (false) + String comparison (false) In this example: @@ -8457,8 +8473,8 @@ case, the value of the expression as a string is used as a dynamic regexp (*note Regexp Usage::; also *note Computed Regexps::). A constant regular expression in slashes by itself is also an -expression. The regexp `/REGEXP/' is an abbreviation for the following -comparison expression: +expression. `/REGEXP/' is an abbreviation for the following comparison +expression: $0 ~ /REGEXP/ @@ -8469,7 +8485,7 @@ Constant Regexps::, where this is discussed in more detail. File: gawk.info, Node: POSIX String Comparison, Prev: Comparison Operators, Up: Typing and Comparison -6.3.2.3 String Comparison With POSIX Rules +6.3.2.3 String Comparison with POSIX Rules .......................................... The POSIX standard says that string comparison is performed based on @@ -8656,7 +8672,7 @@ these. *Note Built-in::, for a list of built-in functions and their descriptions. In addition, you can define functions for use in your program. *Note User-defined::, for instructions on how to do this. Finally, `gawk' lets you write functions in C or C++ that may be called -from your program: see *note Dynamic Extensions::. +from your program (*note Dynamic Extensions::). The way to use a function is with a "function call" expression, which consists of the function name followed immediately by a list of @@ -8671,7 +8687,7 @@ examples show function calls with and without arguments: rand() no arguments CAUTION: Do not put any space between the function name and the - open-parenthesis! A user-defined function name looks just like + opening parenthesis! A user-defined function name looks just like the name of a variable--a space would make the expression look like concatenation of a variable with an expression inside parentheses. With built-in functions, space before the @@ -8796,7 +8812,7 @@ precedence: `+ -' Addition, subtraction. -String Concatenation +String concatenation There is no special symbol for concatenation. The operands are simply written side by side (*note Concatenation::). @@ -8811,9 +8827,9 @@ String Concatenation redirection does not produce an expression that could be the operand of another operator. As a result, it does not make sense to use a redirection operator near another operator of lower - precedence without parentheses. Such combinations (for example, - `print foo > a ? b : c'), result in syntax errors. The correct - way to write this statement is `print foo > (a ? b : c)'. + precedence without parentheses. Such combinations (e.g., `print + foo > a ? b : c'), result in syntax errors. The correct way to + write this statement is `print foo > (a ? b : c)'. `~ !~' Matching, nonmatching. @@ -8839,7 +8855,7 @@ String Concatenation File: gawk.info, Node: Locales, Next: Expressions Summary, Prev: Precedence, Up: Expressions -6.6 Where You Are Makes A Difference +6.6 Where You Are Makes a Difference ==================================== Modern systems support the notion of "locales": a way to tell the @@ -8859,7 +8875,7 @@ terminator. Locales can affect how dates and times are formatted (*note Time Functions::). For example, a common way to abbreviate the date -September 4, 2015 in the United States is "9/4/15." In many countries +September 4, 2015, in the United States is "9/4/15." In many countries in Europe, however, it is abbreviated "4.9.15." Thus, the `%x' specification in a `"US"' locale might produce `9/4/15', while in a `"EUROPE"' locale, it might produce `4.9.15'. @@ -8879,12 +8895,12 @@ File: gawk.info, Node: Expressions Summary, Prev: Locales, Up: Expressions =========== * Expressions are the basic elements of computation in programs. - They are built from constants, variables, function calls and + They are built from constants, variables, function calls, and combinations of the various kinds of values with operators. * `awk' supplies three kinds of constants: numeric, string, and regexp. `gawk' lets you specify numeric constants in octal and - hexadecimal (bases 8 and 16) in addition to decimal (base 10). In + hexadecimal (bases 8 and 16) as well as decimal (base 10). In certain contexts, a standalone regexp constant such as `/foo/' has the same meaning as `$0 ~ /foo/'. @@ -8919,8 +8935,7 @@ File: gawk.info, Node: Expressions Summary, Prev: Locales, Up: Expressions * Function calls return a value which may be used as part of a larger expression. Expressions used to pass parameter values are fully evaluated before the function is called. `awk' provides built-in - and user-defined functions; this is described later on in this - Info file. + and user-defined functions; this is described in *note Functions::. * Operator precedence specifies the order in which operations are performed, unless explicitly overridden by parentheses. `awk''s @@ -9049,10 +9064,9 @@ accepts any record with a first field that contains `li': -| 555-5553 -| 555-6699 - A regexp constant as a pattern is also a special case of an -expression pattern. The expression `/li/' has the value one if `li' -appears in the current input record. Thus, as a pattern, `/li/' matches -any record containing `li'. + pattern. The expression `/li/' has the value one if `li' appears in +the current input record. Thus, as a pattern, `/li/' matches any record +containing `li'. Boolean expressions are also commonly used as patterns. Whether the pattern matches an input record depends on whether its subexpressions @@ -9089,7 +9103,7 @@ _not_ contain the string `li': constant regular expressions, comparisons, or any other `awk' expressions. Range patterns are not expressions, so they cannot appear inside Boolean patterns. Likewise, the special patterns `BEGIN', `END', -`BEGINFILE' and `ENDFILE', which never match any input record, are not +`BEGINFILE', and `ENDFILE', which never match any input record, are not expressions and cannot appear inside Boolean patterns. The precedence of the different operators which can appear in @@ -9175,8 +9189,7 @@ All the patterns described so far are for matching input records. The and cleanup actions for `awk' programs. `BEGIN' and `END' rules must have actions; there is no default action for these rules because there is no current record when they run. `BEGIN' and `END' rules are often -referred to as "`BEGIN' and `END' blocks" by long-time `awk' -programmers. +referred to as "`BEGIN' and `END' blocks" by longtime `awk' programmers. * Menu: @@ -9203,7 +9216,7 @@ input is read. For example: This program finds the number of records in the input file `mail-list' that contain the string `li'. The `BEGIN' rule prints a title for the report. There is no need to use the `BEGIN' rule to -initialize the counter `n' to zero, since `awk' does this automatically +initialize the counter `n' to zero, as `awk' does this automatically (*note Variables::). The second rule increments the variable `n' every time a record containing the pattern `li' is read. The `END' rule prints the value of `n' at the end of the run. @@ -9271,20 +9284,20 @@ many older versions of Unix `awk' do not. The third point follows from the first two. The meaning of `print' inside a `BEGIN' or `END' rule is the same as always: `print $0'. If -`$0' is the null string, then this prints an empty record. Many long -time `awk' programmers use an unadorned `print' in `BEGIN' and `END' -rules, to mean `print ""', relying on `$0' being null. Although one -might generally get away with this in `BEGIN' rules, it is a very bad -idea in `END' rules, at least in `gawk'. It is also poor style, since -if an empty line is needed in the output, the program should print one -explicitly. +`$0' is the null string, then this prints an empty record. Many +longtime `awk' programmers use an unadorned `print' in `BEGIN' and +`END' rules, to mean `print ""', relying on `$0' being null. Although +one might generally get away with this in `BEGIN' rules, it is a very +bad idea in `END' rules, at least in `gawk'. It is also poor style, +because if an empty line is needed in the output, the program should +print one explicitly. Finally, the `next' and `nextfile' statements are not allowed in a `BEGIN' rule, because the implicit read-a-record-and-match-against-the-rules loop has not started yet. -Similarly, those statements are not valid in an `END' rule, since all -the input has been read. (*Note Next Statement::, and see *note -Nextfile Statement::.) +Similarly, those statements are not valid in an `END' rule, because all +the input has been read. (*Note Next Statement::, and *note Nextfile +Statement::,.) File: gawk.info, Node: BEGINFILE/ENDFILE, Next: Empty, Prev: BEGIN/END, Up: Pattern Overview @@ -9383,9 +9396,9 @@ following program: END { print nmatches, "found" }' /path/to/data The `awk' program consists of two pieces of quoted text that are -concatenated together to form the program. The first part is -double-quoted, which allows substitution of the `pattern' shell -variable inside the quotes. The second part is single-quoted. +concatenated together to form the program. The first part is double +quoted, which allows substitution of the `pattern' shell variable +inside the quotes. The second part is single quoted. Variable substitution via quoting works, but can be potentially messy. It requires a good understanding of the shell's quoting rules @@ -9407,10 +9420,10 @@ Now, the `awk' program is just one single-quoted string. The assignment `-v pat="$pattern"' still requires double quotes, in case there is whitespace in the value of `$pattern'. The `awk' variable `pat' could be named `pattern' too, but that would be more confusing. -Using a variable also provides more flexibility, since the variable can -be used anywhere inside the program--for printing, as an array -subscript, or for any other use--without requiring the quoting tricks -at every point in the program. +Using a variable also provides more flexibility, as the variable can be +used anywhere inside the program--for printing, as an array subscript, +or for any other use--without requiring the quoting tricks at every +point in the program. File: gawk.info, Node: Action Overview, Next: Statements, Prev: Using Shell Variables, Up: Patterns and Actions @@ -9462,7 +9475,7 @@ Compound statements Input statements Use the `getline' command (*note Getline::). Also supplied in - `awk' are the `next' statement (*note Next Statement::), and the + `awk' are the `next' statement (*note Next Statement::) and the `nextfile' statement (*note Nextfile Statement::). Output statements @@ -9530,7 +9543,7 @@ following: else print "x is odd" - In this example, if the expression `x % 2 == 0' is true (that is, if + In this example, if the expression `x % 2 == 0' is true (i.e., if the value of `x' is evenly divisible by two), then the first `print' statement is executed; otherwise, the second `print' statement is executed. If the `else' keyword appears on the same line as THEN-BODY @@ -9589,7 +9602,7 @@ increments the value of `i' and the loop repeats. The loop terminates when `i' reaches four. A newline is not required between the condition and the body; -however using one makes the program clearer unless the body is a +however, using one makes the program clearer unless the body is a compound statement or else is very simple. The newline after the open-brace that begins the compound statement is not required either, but the program is harder to read without it. @@ -9627,8 +9640,8 @@ false to begin with. The following is an example of a `do' statement: } This program prints each input record 10 times. However, it isn't a -very realistic example, since in this case an ordinary `while' would do -just as well. This situation reflects actual experience; only +very realistic example, because in this case an ordinary `while' would +do just as well. This situation reflects actual experience; only occasionally is there a real use for a `do' statement. @@ -9707,7 +9720,7 @@ natural to think of. Counting the number of iterations is very common in loops. It can be easier to think of this counting as part of looping rather than as something to do inside the loop. - There is an alternate version of the `for' loop, for iterating over + There is an alternative version of the `for' loop, for iterating over all the indices of an array: for (i in array) @@ -9774,12 +9787,12 @@ the end of the `switch' statement itself. For example: } } - Note that if none of the statements specified above halt execution -of a matched `case' statement, execution falls through to the next -`case' until execution halts. In the above example, the `case' for -`"?"' falls through to the `default' case, which is to call a function -named `usage()'. (The `getopt()' function being called here is -described in *note Getopt Function::.) + Note that if none of the statements specified here halt execution of +a matched `case' statement, execution falls through to the next `case' +until execution halts. In this example, the `case' for `"?"' falls +through to the `default' case, which is to call a function named +`usage()'. (The `getopt()' function being called here is described in +*note Getopt Function::.) File: gawk.info, Node: Break Statement, Next: Continue Statement, Prev: Switch Statement, Up: Statements @@ -9880,7 +9893,7 @@ the previous example with the following `while' loop: print "" } -This program loops forever once `x' reaches 5, since the increment +This program loops forever once `x' reaches 5, because the increment (`x++') is never reached. The `continue' statement has no special meaning with respect to the @@ -9926,7 +9939,7 @@ beginning, in the following manner: Because of the `next' statement, the program's subsequent rules won't see the bad record. The error message is redirected to the standard -error output stream, as error messages should be. For more detail see +error output stream, as error messages should be. For more detail, see *note Special Files::. If the `next' statement causes the end of the input to be reached, @@ -9979,14 +9992,14 @@ over a file that would otherwise cause `gawk' to exit with a fatal error. In this case, `ENDFILE' rules are not executed. *Note BEGINFILE/ENDFILE::. - While one might think that `close(FILENAME)' would accomplish the + Although it might seem that `close(FILENAME)' would accomplish the same as `nextfile', this isn't true. `close()' is reserved for closing files, pipes, and coprocesses that are opened with redirections. It is not related to the main processing that `awk' does with the files listed in `ARGV'. NOTE: For many years, `nextfile' was a common extension. In - September, 2012, it was accepted for inclusion into the POSIX + September 2012, it was accepted for inclusion into the POSIX standard. See the Austin Group website (http://austingroupbugs.net/view.php?id=607). @@ -10083,7 +10096,7 @@ of activity. File: gawk.info, Node: User-modified, Next: Auto-set, Up: Built-in Variables -7.5.1 Built-in Variables That Control `awk' +7.5.1 Built-In Variables That Control `awk' ------------------------------------------- The following is an alphabetical list of variables that you can change @@ -10204,11 +10217,11 @@ description of each variable.) character. (*Note Output Separators::.) `PREC #' - The working precision of arbitrary precision floating-point + The working precision of arbitrary-precision floating-point numbers, 53 bits by default (*note Setting precision::). `ROUNDMODE #' - The rounding mode to use for arbitrary precision arithmetic on + The rounding mode to use for arbitrary-precision arithmetic on numbers, by default `"N"' (`roundTiesToEven' in the IEEE 754 standard; *note Setting the rounding mode::). @@ -10235,7 +10248,7 @@ description of each variable.) Used for internationalization of programs at the `awk' level. It sets the default text domain for specially marked string constants in the source text, as well as for the `dcgettext()', - `dcngettext()' and `bindtextdomain()' functions (*note + `dcngettext()', and `bindtextdomain()' functions (*note Internationalization::). The default value of `TEXTDOMAIN' is `"messages"'. @@ -10246,7 +10259,7 @@ description of each variable.) File: gawk.info, Node: Auto-set, Next: ARGC and ARGV, Prev: User-modified, Up: Built-in Variables -7.5.2 Built-in Variables That Convey Information +7.5.2 Built-In Variables That Convey Information ------------------------------------------------ The following is an alphabetical list of variables that `awk' sets @@ -10256,7 +10269,7 @@ your program. The variables that are specific to `gawk' are marked with a pound sign (`#'). These variables are `gawk' extensions. In other `awk' implementations or if `gawk' is in compatibility mode (*note -Options::), they are not special. +Options::), they are not special: `ARGC', `ARGV' The command-line arguments available to `awk' programs are stored @@ -10320,6 +10333,12 @@ Options::), they are not special. `ENVIRON["PATH"]"', which is the search path for finding executable programs. + This can also affect the running `gawk' program, since some of the + built-in functions may pay attention to certain environment + variables. The most notable instance of this is `mktime()' (*note + Time Functions::), which pays attention the value of the `TZ' + environment variable on many systems. + Some operating systems may not have environment variables. On such systems, the `ENVIRON' array is empty (except for `ENVIRON["AWKPATH"]' and `ENVIRON["AWKLIBPATH"]'; *note AWKPATH @@ -10346,9 +10365,10 @@ Options::), they are not special. on the command line, `awk' reads from the standard input and `FILENAME' is set to `"-"'. `FILENAME' changes each time a new file is read (*note Reading Files::). Inside a `BEGIN' rule, the - value of `FILENAME' is `""', since there are no input files being - processed yet.(1) (d.c.) Note, though, that using `getline' (*note - Getline::) inside a `BEGIN' rule can give `FILENAME' a value. + value of `FILENAME' is `""', because there are no input files + being processed yet.(1) (d.c.) Note, though, that using `getline' + (*note Getline::) inside a `BEGIN' rule can give `FILENAME' a + value. `FNR' The current record number in the current file. `awk' increments @@ -10368,7 +10388,7 @@ Options::), they are not special. `FUNCTAB #' An array whose indices and corresponding values are the names of - all the built-in, user-defined and extension functions in the + all the built-in, user-defined, and extension functions in the program. NOTE: Attempting to use the `delete' statement with the @@ -10444,8 +10464,8 @@ Options::), they are not special. `PROCINFO["sorted_in"]' If this element exists in `PROCINFO', its value controls the order in which array indices will be processed by `for (INDX - in ARRAY)' loops. Since this is an advanced feature, we - defer the full description until later; see *note Scanning an + in ARRAY)' loops. This is an advanced feature, so we defer + the full description until later; see *note Scanning an Array::. `PROCINFO["strftime"]' @@ -10461,7 +10481,7 @@ Options::), they are not special. The following additional elements in the array are available to provide information about the MPFR and GMP libraries if your - version of `gawk' supports arbitrary precision arithmetic (*note + version of `gawk' supports arbitrary-precision arithmetic (*note Arbitrary Precision Arithmetic::): `PROCINFO["mpfr_version"]' @@ -10653,7 +10673,7 @@ string. Another option is to use the `delete' statement to remove elements from `ARGV' (*note Delete::). All of these actions are typically done in the `BEGIN' rule, before -actual processing of the input begins. *Note Split Program::, and see +actual processing of the input begins. *Note Split Program::, and *note Tee Program::, for examples of each way of removing elements from `ARGV'. @@ -10664,7 +10684,7 @@ manner: awk -f myprog.awk -- -v -q file1 file2 ... The following fragment processes `ARGV' in order to examine, and -then remove, the above command-line options: +then remove, the previously mentioned command-line options: BEGIN { for (i = 1; i < ARGC; i++) { @@ -10696,10 +10716,10 @@ are passed on to the `awk' program. (*Note Getopt Function::, for an `awk' library function that parses command-line options.) When designing your program, you should choose options that don't -conflict with `gawk''s, since it will process any options that it +conflict with `gawk''s, because it will process any options that it accepts before passing the rest of the command line on to your program. -Using `#!' with the `-E' option may help (*note Executable Scripts::, -and *note Options::). +Using `#!' with the `-E' option may help (*Note Executable Scripts::, +and *note Options::,). File: gawk.info, Node: Pattern Action Summary, Prev: Built-in Variables, Up: Patterns and Actions @@ -10851,14 +10871,14 @@ example, conceptually, if the element values are 8, `"foo"', `""', and | 8 | "foo" | "" | 30 | @r{Value} +---------+---------+--------+---------+ 0 1 2 3 @r{Index} -Figure 8.1: A Contiguous Array +Figure 8.1: A contiguous array Only the values are stored; the indices are implicit from the order of the values. Here, 8 is the value at index zero, because 8 appears in the position with zero elements before it. Arrays in `awk' are different--they are "associative". This means -that each array is a collection of pairs: an index and its corresponding +that each array is a collection of pairs--an index and its corresponding array element value: Index 3 Value 30 @@ -10898,7 +10918,7 @@ numeric form--thus illustrating that a single array can have both numbers and strings as indices. (In fact, array subscripts are always strings. There are some subtleties to how numbers work when used as array subscripts; this is discussed in more detail in *note Numeric -Array Subscripts::.) Here, the number `1' isn't double-quoted, since +Array Subscripts::.) Here, the number `1' isn't double quoted, because `awk' automatically converts it to a string. The value of `IGNORECASE' has no effect upon array subscripting. @@ -10961,8 +10981,8 @@ index, use the following expression: This expression tests whether the particular index INDX exists, without the side effect of creating that element if it is not present. The expression has the value one (true) if `ARRAY[INDX]' exists and zero -(false) if it does not exist. (We use INDX here, since `index' is the -name of a built-in function.) For example, this statement tests +(false) if it does not exist. (We use INDX here, because `index' is +the name of a built-in function.) For example, this statement tests whether the array `frequencies' contains the index `2': if (2 in frequencies) @@ -11138,7 +11158,7 @@ all `awk' versions do so. Consider this program, named `loopcheck.awk': File: gawk.info, Node: Controlling Scanning, Prev: Scanning an Array, Up: Array Basics -8.1.6 Using Predefined Array Scanning Orders With `gawk' +8.1.6 Using Predefined Array Scanning Orders with `gawk' -------------------------------------------------------- This node describes a feature that is specific to `gawk'. @@ -11159,7 +11179,7 @@ internal implementation of arrays and will vary from one version of * Set `PROCINFO["sorted_in"]' to the name of a user-defined function to use for comparison of array elements. This advanced feature is - described later, in *note Array Sorting::. + described later in *note Array Sorting::. The following special values for `PROCINFO["sorted_in"]' are available: @@ -11248,7 +11268,7 @@ subarrays are treated as being equal to each other. Their order relative to each other is determined by their index strings. Here are some additional things to bear in mind about sorted array -traversal. +traversal: * The value of `PROCINFO["sorted_in"]' is global. That is, it affects all array traversal `for' loops. If you need to change it within @@ -11264,12 +11284,12 @@ traversal. if (save_sorted) PROCINFO["sorted_in"] = save_sorted - * As mentioned, the default array traversal order is represented by - `"@unsorted"'. You can also get the default behavior by assigning - the null string to `PROCINFO["sorted_in"]' or by just deleting the - `"sorted_in"' element from the `PROCINFO' array with the `delete' - statement. (The `delete' statement hasn't been described yet; - *note Delete::.) + * As already mentioned, the default array traversal order is + represented by `"@unsorted"'. You can also get the default + behavior by assigning the null string to `PROCINFO["sorted_in"]' + or by just deleting the `"sorted_in"' element from the `PROCINFO' + array with the `delete' statement. (The `delete' statement hasn't + been described yet; *note Delete::.) In addition, `gawk' provides built-in functions for sorting arrays; see *note Array Sorting Functions::. @@ -11310,8 +11330,8 @@ string value `"12.153"' (using the default conversion value of assigned the value one. The program then changes the value of `CONVFMT'. The test `(xyz in data)' generates a new string value from `xyz'--this time `"12.15"'--because the value of `CONVFMT' only allows -two significant digits. This test fails, since `"12.15"' is different -from `"12.153"'. +two significant digits. This test fails, because `"12.15"' is +different from `"12.153"'. According to the rules for conversions (*note Conversion::), integer values always convert to strings as integers, no matter what the value @@ -11330,7 +11350,7 @@ the same element! As with many things in `awk', the majority of the time things work as you would expect them to. But it is useful to have a precise -knowledge of the actual rules since they can sometimes have a subtle +knowledge of the actual rules, as they can sometimes have a subtle effect on your programs. @@ -11433,7 +11453,7 @@ at a time. and `mawk', as well as by a number of other implementations. NOTE: For many years, using `delete' without a subscript was a - common extension. In September, 2012, it was accepted for + common extension. In September 2012, it was accepted for inclusion into the POSIX standard. See the Austin Group website (http://austingroupbugs.net/view.php?id=544). @@ -11470,7 +11490,7 @@ File: gawk.info, Node: Multidimensional, Next: Arrays of Arrays, Prev: Delete * Multiscanning:: Scanning multidimensional arrays. - A multidimensional array is an array in which an element is + A "multidimensional array" is an array in which an element is identified by a sequence of indices instead of a single index. For example, a two-dimensional array requires two indices. The usual way (in many languages, including `awk') to refer to an element of a @@ -11505,7 +11525,7 @@ stored as `foo["a@b@c"]'. To test whether a particular index sequence exists in a multidimensional array, use the same operator (`in') that is used for -single dimensional arrays. Write the whole sequence of indices in +single-dimensional arrays. Write the whole sequence of indices in parentheses, separated by commas, as the left operand: if ((SUBSCRIPT1, SUBSCRIPT2, ...) in ARRAY) @@ -11606,8 +11626,8 @@ two-element subarray at index `1' of the main array `a': can contain another subarray as a value, which in turn can hold other arrays as well. In this way, you can create arrays of three or more dimensions. The indices can be any `awk' expression, including scalars -separated by commas (that is, a regular `awk' simulated -multidimensional subscript). So the following is valid in `gawk': +separated by commas (i.e., a regular `awk' simulated multidimensional +subscript). So the following is valid in `gawk': a[1][3][1, "name"] = "barney" @@ -11620,7 +11640,7 @@ itself an array and not a scalar: a[4] = "An element in a jagged array" - The terms "dimension", "row" and "column" are meaningless when + The terms "dimension", "row", and "column" are meaningless when applied to such an array, but we will use "dimension" henceforth to imply the maximum number of indices needed to refer to an existing element. The type of any element that has already been assigned cannot @@ -11696,7 +11716,7 @@ the following code prints the elements of our main array `a': } *Note Walking Arrays::, for a user-defined function that "walks" an -arbitrarily-dimensioned array of arrays. +arbitrarily dimensioned array of arrays. Recall that a reference to an uninitialized array element yields a value of `""', the null string. This has one important implication when @@ -11737,11 +11757,11 @@ File: gawk.info, Node: Arrays Summary, Prev: Arrays of Arrays, Up: Arrays `gawk' lets you control the order by assigning special predefined values to `PROCINFO["sorted_in"]'. - * Use `delete ARRAY[INDX]' to delete an individual element. You may - also use `delete ARRAY' to delete all of the elements in the - array. This latter feature has been a common extension for many - years and is now standard, but may not be supported by all - commercial versions of `awk'. + * Use `delete ARRAY[INDX]' to delete an individual element. To + delete all of the elements in an array, use `delete ARRAY'. This + latter feature has been a common extension for many years and is + now standard, but may not be supported by all commercial versions + of `awk'. * Standard `awk' simulates multidimensional arrays by separating subscript values with a comma. The values are concatenated into a @@ -11769,7 +11789,8 @@ File: gawk.info, Node: Functions, Next: Library Functions, Prev: Arrays, Up: This major node describes `awk''s built-in functions, which fall into three categories: numeric, string, and I/O. `gawk' provides additional groups of functions to work with values that represent time, do bit -manipulation, sort arrays, and internationalize and localize programs. +manipulation, sort arrays, provide type information, and +internationalize and localize programs. Besides the built-in functions, `awk' has provisions for writing new functions that the rest of a program can use. The second half of this @@ -11785,7 +11806,7 @@ major node describes these "user-defined" functions. File: gawk.info, Node: Built-in, Next: User-defined, Up: Functions -9.1 Built-in Functions +9.1 Built-In Functions ====================== "Built-in" functions are always available for your `awk' program to @@ -11810,7 +11831,7 @@ for your convenience. File: gawk.info, Node: Calling Built-in, Next: Numeric Functions, Up: Built-in -9.1.1 Calling Built-in Functions +9.1.1 Calling Built-In Functions -------------------------------- To call one of `awk''s built-in functions, write the name of the @@ -11818,7 +11839,7 @@ function followed by arguments in parentheses. For example, `atan2(y + z, 1)' is a call to the function `atan2()' and has two arguments. Whitespace is ignored between the built-in function name and the -open parenthesis, but nonetheless it is good practice to avoid using +opening parenthesis, but nonetheless it is good practice to avoid using whitespace there. User-defined functions do not permit whitespace in this way, and it is easier to avoid mistakes by following a simple convention that always works--no whitespace after a function name. @@ -11844,7 +11865,7 @@ undefined. Thus, avoid writing programs that assume that parameters are evaluated from left to right or from right to left. For example: i = 5 - j = atan2(i++, i *= 2) + j = atan2(++i, i *= 2) If the order of evaluation is left to right, then `i' first becomes 6, and then 12, and `atan2()' is called with the two arguments 6 and @@ -11890,10 +11911,8 @@ brackets ([ ]): `int(X)' Return the nearest integer to X, located between X and zero and - truncated toward zero. - - For example, `int(3)' is 3, `int(3.9)' is 3, `int(-3.9)' is -3, - and `int(-3)' is -3 as well. + truncated toward zero. For example, `int(3)' is 3, `int(3.9)' is + 3, `int(-3.9)' is -3, and `int(-3)' is -3 as well. `log(X)' Return the natural logarithm of X, if X is positive; otherwise, @@ -11984,7 +12003,7 @@ numbers. (2) `mawk' uses a different seed each time. (3) Computer-generated random numbers really are not truly random. -They are technically known as "pseudorandom." This means that while +They are technically known as "pseudorandom." This means that although the numbers in a sequence appear to be random, you can in fact generate the same sequence of random numbers over and over again. @@ -12015,7 +12034,8 @@ with character indices, and not byte indices. In the following list, optional parameters are enclosed in square brackets ([ ]). Several functions perform string substitution; the full discussion is provided in the description of the `sub()' function, -which comes towards the end since the list is presented alphabetically. +which comes toward the end, because the list is presented +alphabetically. Those functions that are specific to `gawk' are marked with a pound sign (`#'). They are not available in compatibility mode (*note @@ -12033,10 +12053,10 @@ Options::): together. NOTE: The following description ignores the third argument, - HOW, since it requires understanding features that we have - not discussed yet. Thus, the discussion here is a deliberate - simplification. (We do provide all the details later on: - *Note Array Sorting Functions::, for the full story.) + HOW, as it requires understanding features that we have not + discussed yet. Thus, the discussion here is a deliberate + simplification. (We do provide all the details later on; see + *note Array Sorting Functions::, for the full story.) Both functions return the number of elements in the array SOURCE. For `asort()', `gawk' sorts the values of SOURCE and replaces the @@ -12275,7 +12295,7 @@ Options::): -| 9 7 There may not be subscripts for the start and index for every - parenthesized subexpression, since they may not all have matched + parenthesized subexpression, because they may not all have matched text; thus they should be tested for with the `in' operator (*note Reference to Elements::). @@ -12314,8 +12334,8 @@ Options::): `SEPS[I]' being the separator string between `ARRAY[I]' and `ARRAY[I+1]'. If FIELDSEP is a single space then any leading whitespace goes into `SEPS[0]' and any trailing whitespace goes - into `SEPS[N]' where N is the return value of `split()' (that is, - the number of elements in ARRAY). + into `SEPS[N]' where N is the return value of `split()' (i.e., the + number of elements in ARRAY). The `split()' function splits strings into pieces in a manner similar to the way input lines are split into fields. For example: @@ -12339,7 +12359,7 @@ Options::): As with input field-splitting, when the value of FIELDSEP is `" "', leading and trailing whitespace is ignored in values assigned to the elements of ARRAY but not in SEPS, and the elements - are separated by runs of whitespace. Also as with input + are separated by runs of whitespace. Also, as with input field-splitting, if FIELDSEP is the null string, each individual character in the string is split into its own array element. (c.e.) @@ -12548,7 +12568,7 @@ is number zero. File: gawk.info, Node: Gory Details, Up: String Functions -9.1.3.1 More About `\' and `&' with `sub()', `gsub()', and `gensub()' +9.1.3.1 More about `\' and `&' with `sub()', `gsub()', and `gensub()' ..................................................................... CAUTION: This subsubsection has been reported to cause headaches. @@ -12591,7 +12611,7 @@ is illustrated in *note table-sub-escapes::. `\\\\\\&' `\\\&' A literal `\\&' `\\q' `\q' A literal `\q' -Table 9.1: Historical Escape Sequence Processing for `sub()' and +Table 9.1: Historical escape sequence processing for `sub()' and `gsub()' This table shows both the lexical-level processing, where an odd number @@ -12621,7 +12641,7 @@ This is shown in *note table-sub-proposed::. `\\q' `\q' A literal `\q' `\\\\' `\\' `\\' -Table 9.2: GNU `awk' Rules For `sub()' And Backslash +Table 9.2: GNU `awk' rules for `sub()' and backslash In a nutshell, at the runtime level, there are now three special sequences of characters (`\\\&', `\\&' and `\&') whereas historically @@ -12648,20 +12668,19 @@ rules are presented in *note table-posix-sub::. `\\q' `\q' A literal `\q' `\\\\' `\\' `\' -Table 9.3: POSIX Rules For `sub()' And `gsub()' +Table 9.3: POSIX rules for `sub()' and `gsub()' The only case where the difference is noticeable is the last one: `\\\\' is seen as `\\' and produces `\' instead of `\\'. Starting with version 3.1.4, `gawk' followed the POSIX rules when `--posix' is specified (*note Options::). Otherwise, it continued to -follow the proposed rules, since that had been its behavior for many -years. +follow the proposed rules, as that had been its behavior for many years. When version 4.0.0 was released, the `gawk' maintainer made the POSIX rules the default, breaking well over a decade's worth of -backwards compatibility.(1) Needless to say, this was a bad idea, and -as of version 4.0.1, `gawk' resumed its historical behavior, and only +backward compatibility.(1) Needless to say, this was a bad idea, and as +of version 4.0.1, `gawk' resumed its historical behavior, and only follows the POSIX rules when `--posix' is given. The rules for `gensub()' are considerably simpler. At the runtime @@ -12680,7 +12699,7 @@ the `\' does not, as shown in *note table-gensub-escapes::. `\\\\\\&' `\\\&' A literal `\&' `\\q' `\q' A literal `q' -Table 9.4: Escape Sequence Processing For `gensub()' +Table 9.4: Escape sequence processing for `gensub()' Because of the complexity of the lexical and runtime level processing and the special cases for `sub()' and `gsub()', we recommend the use of @@ -12724,23 +12743,23 @@ parameters are enclosed in square brackets ([ ]): either a file opened for writing or a shell command for redirecting output to a pipe or coprocess. - Many utility programs "buffer" their output; i.e., they save + Many utility programs "buffer" their output (i.e., they save information to write to a disk file or the screen in memory until there is enough for it to be worthwhile to send the data to the - output device. This is often more efficient than writing every + output device). This is often more efficient than writing every little bit of information as soon as it is ready. However, sometimes it is necessary to force a program to "flush" its - buffers; that is, write the information to its destination, even - if a buffer is not full. This is the purpose of the `fflush()' + buffers (i.e., write the information to its destination, even if a + buffer is not full). This is the purpose of the `fflush()' function--`gawk' also buffers its output and the `fflush()' function forces `gawk' to flush its buffers. - Brian Kernighan added `fflush()' to his `awk' in April of 1992. - For two decades, it was a common extension. In December, 2012, it - was accepted for inclusion into the POSIX standard. See the - Austin Group website (http://austingroupbugs.net/view.php?id=634). + Brian Kernighan added `fflush()' to his `awk' in April 1992. For + two decades, it was a common extension. In December 2012, it was + accepted for inclusion into the POSIX standard. See the Austin + Group website (http://austingroupbugs.net/view.php?id=634). - POSIX standardizes `fflush()' as follows: If there is no argument, + POSIX standardizes `fflush()' as follows: if there is no argument, or if the argument is the null string (`""'), then `awk' flushes the buffers for _all_ open output files and pipes. @@ -12765,6 +12784,38 @@ parameters are enclosed in square brackets ([ ]): or if FILENAME is not an open file, pipe, or coprocess. In such a case, `fflush()' returns -1, as well. + Interactive Versus Noninteractive Buffering + + As a side point, buffering issues can be even more confusing, + depending upon whether your program is "interactive" (i.e., + communicating with a user sitting at a keyboard).(1) + + Interactive programs generally "line buffer" their output (i.e., + they write out every line). Noninteractive programs wait until + they have a full buffer, which may be many lines of output. Here + is an example of the difference: + + $ awk '{ print $1 + $2 }' + 1 1 + -| 2 + 2 3 + -| 5 + Ctrl-d + + Each line of output is printed immediately. Compare that behavior + with this example: + + $ awk '{ print $1 + $2 }' | cat + 1 1 + 2 3 + Ctrl-d + -| 2 + -| 5 + + Here, no output is printed until after the `Ctrl-d' is typed, + because it is all buffered and sent down the pipe to `cat' in one + shot. + `system(COMMAND)' Execute the operating-system command COMMAND and then return to the `awk' program. Return COMMAND's exit status. @@ -12798,37 +12849,6 @@ parameters are enclosed in square brackets ([ ]): is disabled (*note Options::). - Interactive Versus Noninteractive Buffering - - As a side point, buffering issues can be even more confusing, -depending upon whether your program is "interactive", i.e., -communicating with a user sitting at a keyboard.(1) - - Interactive programs generally "line buffer" their output; i.e., they -write out every line. Noninteractive programs wait until they have a -full buffer, which may be many lines of output. Here is an example of -the difference: - - $ awk '{ print $1 + $2 }' - 1 1 - -| 2 - 2 3 - -| 5 - Ctrl-d - -Each line of output is printed immediately. Compare that behavior with -this example: - - $ awk '{ print $1 + $2 }' | cat - 1 1 - 2 3 - Ctrl-d - -| 2 - -| 5 - -Here, no output is printed until after the `Ctrl-d' is typed, because -it is all buffered and sent down the pipe to `cat' in one shot. - Controlling Output Buffering with `system()' The `fflush()' function provides explicit control over output @@ -12842,8 +12862,8 @@ argument: `gawk' treats this use of the `system()' function as a special case and is smart enough not to run a shell (or other command interpreter) with the empty command. Therefore, with `gawk', this idiom is not only -useful, it is also efficient. While this method should work with other -`awk' implementations, it does not necessarily avoid starting an +useful, it is also efficient. Although this method should work with +other `awk' implementations, it does not necessarily avoid starting an unnecessary shell. (Other implementations may only flush the buffer associated with the standard output and not necessarily all buffered output.) @@ -12934,14 +12954,14 @@ enclosed in square brackets ([ ]): Otherwise, the value is formatted for the local time zone. The TIMESTAMP is in the same format as the value returned by the `systime()' function. If no TIMESTAMP argument is supplied, - `gawk' uses the current time of day as the timestamp. If no - FORMAT argument is supplied, `strftime()' uses the value of + `gawk' uses the current time of day as the timestamp. Without a + FORMAT argument, `strftime()' uses the value of `PROCINFO["strftime"]' as the format string (*note Built-in Variables::). The default string value is `"%a %b %e %H:%M:%S %Z %Y"'. This format string produces output that is equivalent to that of the `date' utility. You can assign a new value to `PROCINFO["strftime"]' to change the default - format; see below for the various format directives. + format; see the following list for the various format directives. `systime()' Return the current time as the number of seconds since the system @@ -13005,9 +13025,9 @@ the following date format specifications: `%g' The year modulo 100 of the ISO 8601 week number, as a decimal - number (00-99). For example, January 1, 2012 is in week 53 of + number (00-99). For example, January 1, 2012, is in week 53 of 2011. Thus, the year of its ISO 8601 week number is 2011, even - though its year is 2012. Similarly, December 31, 2012 is in week + though its year is 2012. Similarly, December 31, 2012, is in week 1 of 2013. Thus, the year of its ISO week number is 2013, even though its year is 2012. @@ -13101,15 +13121,15 @@ the following date format specifications: `%Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH' `%OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy' - "Alternate representations" for the specifications that use only + "Alternative representations" for the specifications that use only the second letter (`%c', `%C', and so on).(5) (These facilitate compliance with the POSIX `date' utility.) `%%' A literal `%'. - If a conversion specifier is not one of the above, the behavior is -undefined.(6) + If a conversion specifier is not one of those just listed, the +behavior is undefined.(6) For systems that are not yet fully standards-compliant, `gawk' supplies a copy of `strftime()' from the GNU C Library. It supports @@ -13129,8 +13149,8 @@ format specifications are available: The time as a decimal timestamp in seconds since the epoch. - Additionally, the alternate representations are recognized but their -normal representations are used. + Additionally, the alternative representations are recognized but +their normal representations are used. The following example is an `awk' implementation of the POSIX `date' utility. Normally, the `date' utility prints the current date and time @@ -13218,7 +13238,7 @@ table-bitwise-ops::. 0 | 0 0 | 0 1 | 0 1 1 | 0 1 | 1 1 | 1 0 -Table 9.5: Bitwise Operations +Table 9.5: Bitwise operations As you can see, the result of an AND operation is 1 only when _both_ bits are 1. The result of an OR operation is 1 if _either_ bit is 1. @@ -13255,7 +13275,7 @@ are enclosed in square brackets ([ ]): Return the bitwise XOR of the arguments. There must be at least two. - For all of these functions, first the double precision + For all of these functions, first the double-precision floating-point value is converted to the widest C unsigned integer type, then the bitwise operation is performed. If the result cannot be represented exactly as a C `double', leading nonzero bits are removed @@ -13313,7 +13333,7 @@ or not. If so, a `"1"' is concatenated onto the front of the string. Otherwise, a `"0"' is added. The value is then shifted right by one bit and the loop continues until there are no more 1 bits. - If the initial value is zero it returns a simple `"0"'. Otherwise, + If the initial value is zero, it returns a simple `"0"'. Otherwise, at the end, it pads the value with zeros to represent multiples of 8-bit quantities. This is typical in modern computers. @@ -13349,11 +13369,11 @@ user-defined function (not discussed yet; *note User-defined::), to test if a parameter is an array or not. NOTE: Using `isarray()' at the global level to test variables - makes no sense. Since you are the one writing the program, you are - supposed to know if your variables are arrays or not. And in fact, - due to the way `gawk' works, if you pass the name of a variable - that has not been previously used to `isarray()', `gawk' ends up - turning it into a scalar. + makes no sense. Because you are the one writing the program, you + are supposed to know if your variables are arrays or not. And in + fact, due to the way `gawk' works, if you pass the name of a + variable that has not been previously used to `isarray()', `gawk' + ends up turning it into a scalar. File: gawk.info, Node: I18N Functions, Prev: Type Functions, Up: Built-in @@ -13399,8 +13419,8 @@ File: gawk.info, Node: User-defined, Next: Indirect Calls, Prev: Built-in, U Complicated `awk' programs can often be simplified by defining your own functions. User-defined functions can be called just like built-in -ones (*note Function Calls::), but it is up to you to define them, -i.e., to tell `awk' what they should do. +ones (*note Function Calls::), but it is up to you to define them +(i.e., to tell `awk' what they should do). * Menu: @@ -13513,7 +13533,7 @@ function: func foo() { a = sqrt($1) ; print a } -Instead it defines a rule that, for each record, concatenates the value +Instead, it defines a rule that, for each record, concatenates the value of the variable `func' with the return value of the function `foo'. If the resulting string is non-null, the action is executed. This is probably not what is desired. (`awk' accepts this input as @@ -13525,7 +13545,7 @@ keyword `function' when defining a function. ---------- Footnotes ---------- - (1) This program won't actually run, since `foo()' is undefined. + (1) This program won't actually run, because `foo()' is undefined. File: gawk.info, Node: Function Example, Next: Function Caveats, Prev: Definition Syntax, Up: User-defined @@ -13579,7 +13599,7 @@ POSIX standard.) string as an input parameter and returns the string in backwards order. Recursive functions must always have a test that stops the recursion. In this case, the recursion terminates when the input string is already -empty. +empty: function rev(str) { @@ -13615,9 +13635,9 @@ an `awk' version of `ctime()': } You might think that `ctime()' could use `PROCINFO["strftime"]' for -its format string. That would be a mistake, since `ctime()' is supposed -to return the time formatted in a standard fashion, and user-level code -could have changed `PROCINFO["strftime"]'. +its format string. That would be a mistake, because `ctime()' is +supposed to return the time formatted in a standard fashion, and +user-level code could have changed `PROCINFO["strftime"]'. ---------- Footnotes ---------- @@ -13642,7 +13662,7 @@ the function. File: gawk.info, Node: Calling A Function, Next: Variable Scope, Up: Function Caveats -9.2.3.1 Writing A Function Call +9.2.3.1 Writing a Function Call ............................... A function call consists of the function name followed by the arguments @@ -13655,10 +13675,10 @@ string concatenation): foo(x y, "lose", 4 * z) CAUTION: Whitespace characters (spaces and TABs) are not allowed - between the function name and the open-parenthesis of the argument - list. If you write whitespace by mistake, `awk' might think that - you mean to concatenate a variable with an expression in - parentheses. However, it notices that you used a function name + between the function name and the opening parenthesis of the + argument list. If you write whitespace by mistake, `awk' might + think that you mean to concatenate a variable with an expression + in parentheses. However, it notices that you used a function name and not a variable name, and reports an error. @@ -13711,7 +13731,7 @@ variable instance: top's i=3 If you want `i' to be local to both `foo()' and `bar()' do as -follows (the extra-space before `i' is a coding convention to indicate +follows (the extra space before `i' is a coding convention to indicate that `i' is a local variable, not an argument): function bar( i) @@ -13784,20 +13804,17 @@ create new arrays. Consider this example: File: gawk.info, Node: Pass By Value/Reference, Prev: Variable Scope, Up: Function Caveats -9.2.3.3 Passing Function Arguments By Value Or By Reference +9.2.3.3 Passing Function Arguments by Value Or by Reference ........................................................... In `awk', when you declare a function, there is no way to declare explicitly whether the arguments are passed "by value" or "by reference". - Instead the passing convention is determined at runtime when the -function is called according to the following rule: - - * If the argument is an array variable, then it is passed by - reference, - - * Otherwise the argument is passed by value. + Instead, the passing convention is determined at runtime when the +function is called according to the following rule: if the argument is +an array variable, then it is passed by reference. Otherwise, the +argument is passed by value. Passing an argument by value means that when a function is called, it is given a _copy_ of the value of this argument. The caller may use a @@ -13874,7 +13891,7 @@ undefined functions. Some `awk' implementations generate a runtime error if you use either the `next' statement or the `nextfile' statement (*note Next -Statement::, also *note Nextfile Statement::) inside a user-defined +Statement::, and *note Nextfile Statement::) inside a user-defined function. `gawk' does not have this limitation. @@ -13923,11 +13940,12 @@ a value for the largest number among the elements of an array: } You call `maxelt()' with one argument, which is an array name. The -local variables `i' and `ret' are not intended to be arguments; while -there is nothing to stop you from passing more than one argument to -`maxelt()', the results would be strange. The extra space before `i' -in the function parameter list indicates that `i' and `ret' are local -variables. You should follow this convention when defining functions. +local variables `i' and `ret' are not intended to be arguments; there +is nothing to stop you from passing more than one argument to +`maxelt()' but the results would be strange. The extra space before +`i' in the function parameter list indicates that `i' and `ret' are +local variables. You should follow this convention when defining +functions. The following program uses the `maxelt()' function. It loads an array, calls `maxelt()', and then reports the maximum number in that @@ -14041,15 +14059,15 @@ function calls, you tell `gawk' to use the _value_ of a variable as the _name_ of the function to call. The syntax is similar to that of a regular function call: an -identifier immediately followed by a left parenthesis, any arguments, -and then a closing right parenthesis, with the addition of a leading `@' -character: +identifier immediately followed by an opening parenthesis, any +arguments, and then a closing parenthesis, with the addition of a +leading `@' character: the_func = "sum" result = @the_func() # calls the sum() function Here is a full program that processes the previously shown data, -using indirect function calls. +using indirect function calls: # indirectcall.awk --- Demonstrate indirect function calls @@ -14077,7 +14095,7 @@ using indirect function calls. These two functions expect to work on fields; thus the parameters `first' and `last' indicate where in the fields to start and end. -Otherwise they perform the expected computations and are not unusual. +Otherwise they perform the expected computations and are not unusual: # For each record, print the class name and the requested statistics { @@ -14354,7 +14372,7 @@ File: gawk.info, Node: Functions Summary, Prev: Indirect Calls, Up: Functions * POSIX `awk' provides three kinds of built-in functions: numeric, string, and I/O. `gawk' provides functions that sort arrays, work with values representing time, do bit manipulation, determine - variable type (array vs. scalar), and internationalize and + variable type (array versus scalar), and internationalize and localize programs. `gawk' also provides several extensions to some of standard functions, typically in the form of additional arguments. @@ -14444,8 +14462,8 @@ functions and would like to contribute them to the `awk' user community, see *note How To Contribute::, for more information. The programs in this major node and in *note Sample Programs::, -freely use features that are `gawk'-specific. Rewriting these programs -for different implementations of `awk' is pretty straightforward. +freely use `gawk'-specific features. Rewriting these programs for +different implementations of `awk' is pretty straightforward: * Diagnostic error messages are sent to `/dev/stderr'. Use `| "cat 1>&2"' instead of `> "/dev/stderr"' if your system does not have a @@ -14503,8 +14521,8 @@ specific function). There is no intermediate state analogous to Library functions often need to have global variables that they can use to preserve state information between calls to the function--for example, `getopt()''s variable `_opti' (*note Getopt Function::). Such -variables are called "private", since the only functions that need to -use them are the ones in the library. +variables are called "private", as the only functions that need to use +them are the ones in the library. When writing a library function, you should try to choose names for your private variables that will not conflict with any variables used by @@ -14521,7 +14539,7 @@ will be accidentally shared with the user's program. In addition, several of the library functions use a prefix that helps indicate what function or set of functions use the variables--for example, `_pw_byname()' in the user database routines (*note Passwd -Functions::). This convention is recommended, since it even further +Functions::). This convention is recommended, as it even further decreases the chance of inadvertent conflict among variable names. Note that this convention is used equally well for variable names and for private function names.(1) @@ -14562,9 +14580,9 @@ merely recommend that you do so. ---------- Footnotes ---------- - (1) While all the library routines could have been rewritten to use -this convention, this was not done, in order to show how our own `awk' -programming style has evolved and to provide some basis for this + (1) Although all the library routines could have been rewritten to +use this convention, this was not done, in order to show how our own +`awk' programming style has evolved and to provide some basis for this discussion. (2) `gawk''s `--dump-variables' command-line option is useful for @@ -14598,7 +14616,7 @@ programming use. File: gawk.info, Node: Strtonum Function, Next: Assert Function, Up: General Functions -10.2.1 Converting Strings To Numbers +10.2.1 Converting Strings to Numbers ------------------------------------ The `strtonum()' function (*note String Functions::) is a `gawk' @@ -14665,8 +14683,8 @@ then `mystrtonum()' loops through each character in the string. It sets `k' to the index in `"1234567"' of the current octal digit. The return value will either be the same number as the digit, or zero if the character is not there, which will be true for a `0'. This is -safe, since the regexp test in the `if' ensures that only octal values -are converted. +safe, because the regexp test in the `if' ensures that only octal +values are converted. Similar logic applies to the code that checks for and converts a hexadecimal value, which starts with `0x' or `0X'. The use of @@ -14895,8 +14913,8 @@ distant past, at least one minicomputer manufacturer used ASCII, but with mark parity, meaning that the leftmost bit in the byte is always 1. This means that on those systems, characters have numeric values from 128 to 255. Finally, large mainframe systems use the EBCDIC -character set, which uses all 256 values. While there are other -character sets in use on some older systems, they are not really worth +character set, which uses all 256 values. There are other character +sets in use on some older systems, but they are not really worth worrying about: function ord(str, c) @@ -14954,7 +14972,7 @@ application programs (*note Sample Programs::). but it should also have a reasonable default behavior. It is called with an array as well as the beginning and ending indices of the elements in the array to be merged. This assumes that the array -indices are numeric--a reasonable assumption since the array was likely +indices are numeric--a reasonable assumption, as the array was likely created with `split()' (*note String Functions::): # join.awk --- join an array into a string @@ -14994,7 +15012,7 @@ File: gawk.info, Node: Getlocaltime Function, Next: Readfile Function, Prev: The `systime()' and `strftime()' functions described in *note Time Functions::, provide the minimum functionality necessary for dealing -with the time of day in human readable form. While `strftime()' is +with the time of day in human-readable form. Although `strftime()' is extensive, the control formats are not necessarily easy to remember or intuitively obvious when reading a program. @@ -15071,7 +15089,7 @@ optional timestamp value to use instead of the current time. File: gawk.info, Node: Readfile Function, Next: Shell Quoting, Prev: Getlocaltime Function, Up: General Functions -10.2.8 Reading A Whole File At Once +10.2.8 Reading a Whole File At Once ----------------------------------- Often, it is convenient to have the entire contents of a file available @@ -15134,7 +15152,7 @@ also reads an entire file into memory. File: gawk.info, Node: Shell Quoting, Prev: Readfile Function, Up: General Functions -10.2.9 Quoting Strings to Pass to The Shell +10.2.9 Quoting Strings to Pass to the Shell ------------------------------------------- Michael Brennan offers the following programming pattern, which he uses @@ -15162,7 +15180,7 @@ frequently: Note the need for shell quoting. The function `shell_quote()' does it. `SINGLE' is the one-character string `"'"' and `QSINGLE' is the -three-character string `"\"'\""'. +three-character string `"\"'\""': # shell_quote --- quote an argument for passing to the shell @@ -15206,7 +15224,7 @@ File: gawk.info, Node: Filetrans Function, Next: Rewind Function, Up: Data Fi 10.3.1 Noting Data File Boundaries ---------------------------------- -The `BEGIN' and `END' rules are each executed exactly once at the +The `BEGIN' and `END' rules are each executed exactly once, at the beginning and end of your `awk' program, respectively (*note BEGIN/END::). We (the `gawk' authors) once had a user who mistakenly thought that the `BEGIN' rule is executed at the beginning of each data @@ -15266,7 +15284,7 @@ again the value of multiple `BEGIN' and `END' rules should be clear. pass and at the beginning of the second pass. The following version solves the problem: - # ftrans.awk --- handle data file transitions + # ftrans.awk --- handle datafile transitions # # user supplies beginfile() and endfile() functions @@ -15282,7 +15300,7 @@ solves the problem: *note Wc Program::, shows how this library function can be used and how it simplifies writing the main program. - So Why Does `gawk' have `BEGINFILE' and `ENDFILE'? + So Why Does `gawk' Have `BEGINFILE' and `ENDFILE'? You are probably wondering, if `beginfile()' and `endfile()' functions can do the job, why does `gawk' have `BEGINFILE' and @@ -15290,7 +15308,7 @@ functions can do the job, why does `gawk' have `BEGINFILE' and Good question. Normally, if `awk' cannot open a file, this causes an immediate fatal error. In this case, there is no way for a -user-defined function to deal with the problem, since the mechanism for +user-defined function to deal with the problem, as the mechanism for calling it relies on the file being open and at the first record. Thus, the main reason for `BEGINFILE' is to give you a "hook" to catch files that cannot be processed. `ENDFILE' exists for symmetry, and because @@ -15334,8 +15352,8 @@ over with it from the top. For lack of a better name, we'll call it Auto-set::), which is specific to `gawk'. It also relies on the `nextfile' keyword (*note Nextfile Statement::). Because of this, you should not call it from an `ENDFILE' rule. (This isn't necessary -anyway, since as soon as an `ENDFILE' rule finishes `gawk' goes to the -next file!) +anyway, because `gawk' goes to the next file as soon as an `ENDFILE' +rule finishes!) File: gawk.info, Node: File Checking, Next: Empty Files, Prev: Rewind Function, Up: Data File Management @@ -15363,12 +15381,12 @@ following program to your `awk' program: } This works, because the `getline' won't be fatal. Removing the -element from `ARGV' with `delete' skips the file (since it's no longer -in the list). See also *note ARGC and ARGV::. +element from `ARGV' with `delete' skips the file (because it's no +longer in the list). See also *note ARGC and ARGV::. - The regular expression check purposely does not use character classes -such as `[:alpha:]' and `[:alnum:]' (*note Bracket Expressions::) since -`awk' variable names only allow the English letters. + Because `awk' variable names only allow the English letters, the +regular expression check purposely does not use character classes such +as `[:alpha:]' and `[:alnum:]' (*note Bracket Expressions::) ---------- Footnotes ---------- @@ -15476,11 +15494,11 @@ File: gawk.info, Node: Getopt Function, Next: Passwd Functions, Prev: Data Fi 10.4 Processing Command-Line Options ==================================== -Most utilities on POSIX compatible systems take options on the command +Most utilities on POSIX-compatible systems take options on the command line that can be used to change the way a program behaves. `awk' is an example of such a program (*note Options::). Often, options take -"arguments"; i.e., data that the program needs to correctly obey the -command-line option. For example, `awk''s `-F' option requires a +"arguments" (i.e., data that the program needs to correctly obey the +command-line option). For example, `awk''s `-F' option requires a string to use as the field separator. The first occurrence on the command line of either `--' or a string that does not begin with `-' ends the options. @@ -15705,10 +15723,10 @@ next element in `argv'. If neither condition is true, then only on the next call to `getopt()'. The `BEGIN' rule initializes both `Opterr' and `Optind' to one. -`Opterr' is set to one, since the default behavior is for `getopt()' to -print a diagnostic message upon seeing an invalid option. `Optind' is -set to one, since there's no reason to look at the program name, which -is in `ARGV[0]': +`Opterr' is set to one, because the default behavior is for `getopt()' +to print a diagnostic message upon seeing an invalid option. `Optind' +is set to one, because there's no reason to look at the program name, +which is in `ARGV[0]': BEGIN { Opterr = 1 # default is to diagnose @@ -15748,14 +15766,14 @@ result of two sample runs of the test program: In both runs, the first `--' terminates the arguments to `awk', so that it does not try to interpret the `-a', etc., as its own options. - NOTE: After `getopt()' is through, user level code must clear out + NOTE: After `getopt()' is through, user-level code must clear out all the elements of `ARGV' from 1 to `Optind', so that `awk' does not try to process the command-line options as file names. Using `#!' with the `-E' option may help avoid conflicts between -your program's options and `gawk''s options, since `-E' causes `gawk' -to abandon processing of further options (*note Executable Scripts::, -and *note Options::). +your program's options and `gawk''s options, as `-E' causes `gawk' to +abandon processing of further options (*note Executable Scripts::, and +*note Options::). Several of the sample programs presented in *note Sample Programs::, use `getopt()' to process their arguments. @@ -15764,7 +15782,7 @@ use `getopt()' to process their arguments. (1) This function was written before `gawk' acquired the ability to split strings into single characters using `""' as the separator. We -have left it alone, since using `substr()' is more portable. +have left it alone, as using `substr()' is more portable. File: gawk.info, Node: Passwd Functions, Next: Group Functions, Prev: Getopt Function, Up: Library Functions @@ -15789,7 +15807,7 @@ function is `getpwent()', for "get password entry." The "password" comes from the original user database file, `/etc/passwd', which stores user information, along with the encrypted passwords (hence the name). - While an `awk' program could simply read `/etc/passwd' directly, + Although an `awk' program could simply read `/etc/passwd' directly, this file may not contain complete information about the system's set of users.(1) To be sure you are able to produce a readable and complete version of the user database, it is necessary to write a small C @@ -15834,13 +15852,13 @@ Encrypted password systems. User-ID - The user's numeric user ID number. (On some systems it's a C + The user's numeric user ID number. (On some systems, it's a C `long', and not an `int'. Thus we cast it to `long' for all cases.) Group-ID The user's numeric group ID number. (Similar comments about - `long' vs. `int' apply here.) + `long' versus `int' apply here.) Full name The user's full name, and perhaps other information associated @@ -15857,7 +15875,7 @@ Login shell A few lines representative of `pwcat''s output are as follows: $ pwcat - -| root:3Ov02d5VaUPB6:0:1:Operator:/:/bin/sh + -| root:x:0:1:Operator:/:/bin/sh -| nobody:*:65534:65534::/: -| daemon:*:1:1::/: -| sys:*:2:2::/:/bin/csh @@ -15918,14 +15936,14 @@ you might want it to be in a different directory on your system. into three associative arrays. The arrays are indexed by username (`_pw_byname'), by user ID number (`_pw_byuid'), and by order of occurrence (`_pw_bycount'). The variable `_pw_inited' is used for -efficiency, since `_pw_init()' needs to be called only once. +efficiency, as `_pw_init()' needs to be called only once. Because this function uses `getline' to read information from `pwcat', it first saves the values of `FS', `RS', and `$0'. It notes in the variable `using_fw' whether field splitting with `FIELDWIDTHS' -is in effect or not. Doing so is necessary, since these functions -could be called from anywhere within a user's program, and the user may -have his or her own way of splitting records and fields. This makes it +is in effect or not. Doing so is necessary, as these functions could +be called from anywhere within a user's program, and the user may have +his or her own way of splitting records and fields. This makes it possible to restore the correct field-splitting mechanism later. The test can only be true for `gawk'. It is false if using `FS' or `FPAT', or on some other `awk' implementation. @@ -15996,8 +16014,8 @@ simplifies the code but runs an extra process that may never be needed.) once. If you are worried about squeezing every last cycle out of your `awk' program, the check of `_pw_inited' could be moved out of `_pw_init()' and duplicated in all the other functions. In practice, -this is not necessary, since most `awk' programs are I/O-bound, and -such a change would clutter up the code. +this is not necessary, as most `awk' programs are I/O-bound, and such a +change would clutter up the code. The `id' program in *note Id Program::, uses these functions. @@ -16067,7 +16085,7 @@ Group ID Number cases.) Group Member List - A comma-separated list of user names. These users are members of + A comma-separated list of usernames. These users are members of the group. Modern Unix systems allow users to be members of several groups simultaneously. If your system does, then there are elements `"group1"' through `"groupN"' in `PROCINFO' for those @@ -16158,7 +16176,7 @@ used, and to restore the appropriate field splitting mechanism. The group information is stored is several associative arrays. The arrays are indexed by group name (`_gr_byname'), by group ID number (`_gr_bygid'), and by position in the database (`_gr_bycount'). There -is an additional array indexed by user name (`_gr_groupsbyuser'), which +is an additional array indexed by username (`_gr_groupsbyuser'), which is a space-separated list of groups to which each user belongs. Unlike the user database, it is possible to have multiple records in @@ -16170,7 +16188,7 @@ following: tvpeople:*:101:david,conan,tom,joan For this reason, `_gr_init()' looks to see if a group name or group -ID number is already seen. If it is, then the user names are simply +ID number is already seen. If it is, the usernames are simply concatenated onto the previous list of users.(1) Finally, `_gr_init()' closes the pipeline to `grcat', restores `FS' @@ -16198,7 +16216,7 @@ looks up the information associated with that group ID: } The `getgruser()' function does not have a C counterpart. It takes a -user name and returns the list of groups that have the user as a member: +username and returns the list of groups that have the user as a member: function getgruser(user) { @@ -16310,7 +16328,7 @@ File: gawk.info, Node: Library Functions Summary, Next: Library Exercises, Pr * The functions presented here fit into the following categories: General problems - Number to string conversion, assertions, rounding, random + Number-to-string conversion, assertions, rounding, random number generation, converting characters to numbers, joining strings, getting easily usable time-of-day information, and reading a whole file in one shot. @@ -16439,7 +16457,7 @@ programming for "real world" tasks. File: gawk.info, Node: Cut Program, Next: Egrep Program, Up: Clones -11.2.1 Cutting out Fields and Columns +11.2.1 Cutting Out Fields and Columns ------------------------------------- The `cut' utility selects, or "cuts," characters or fields from its @@ -16656,10 +16674,10 @@ filler fields: nfields = j - 1 } - Next is the rule that actually processes the data. If the `-s' -option is given, then `suppress' is true. The first `if' statement -makes sure that the input record does have the field separator. If -`cut' is processing fields, `suppress' is true, and the field separator + Next is the rule that processes the data. If the `-s' option is +given, then `suppress' is true. The first `if' statement makes sure +that the input record does have the field separator. If `cut' is +processing fields, `suppress' is true, and the field separator character is not in the record, then the record is skipped. If the record is valid, then `gawk' has split the data into fields, @@ -16684,8 +16702,8 @@ out between the fields: } This version of `cut' relies on `gawk''s `FIELDWIDTHS' variable to -do the character-based cutting. While it is possible in other `awk' -implementations to use `substr()' (*note String Functions::), it is +do the character-based cutting. It is possible in other `awk' +implementations to use `substr()' (*note String Functions::), but it is also extremely painful. The `FIELDWIDTHS' variable supplies an elegant solution to the problem of picking the input line apart by characters. @@ -16796,14 +16814,14 @@ the matched lines in the output: # pattern = tolower(pattern) } - The last two lines are commented out, since they are not needed in + The last two lines are commented out, as they are not needed in `gawk'. They should be uncommented if you have to use another version of `awk'. The next set of lines should be uncommented if you are not using `gawk'. This rule translates all the characters in the input line into lowercase if the `-i' option is specified.(1) The rule is commented out -since it is not necessary with `gawk': +as it is not necessary with `gawk': #{ # if (IGNORECASE) @@ -16915,7 +16933,7 @@ the translated line, not the original. File: gawk.info, Node: Id Program, Next: Split Program, Prev: Egrep Program, Up: Clones -11.2.3 Printing out User Information +11.2.3 Printing Out User Information ------------------------------------ The `id' utility lists a user's real and effective user ID numbers, @@ -16999,7 +17017,7 @@ and the group numbers: The test in the `for' loop is worth noting. Any supplementary groups in the `PROCINFO' array have the indices `"group1"' through -`"groupN"' for some N, i.e., the total number of supplementary groups. +`"groupN"' for some N (i.e., the total number of supplementary groups). However, we don't know in advance how many of these groups there are. This loop works by starting at one, concatenating the value with @@ -17028,11 +17046,11 @@ is as follows:(1) `split' [`-COUNT'] [FILE] [PREFIX] By default, the output files are named `xaa', `xab', and so on. Each -file has 1000 lines in it, with the likely exception of the last file. +file has 1,000 lines in it, with the likely exception of the last file. To change the number of lines in each file, supply a number on the -command line preceded with a minus; e.g., `-500' for files with 500 -lines in them instead of 1000. To change the name of the output files -to something like `myfileaa', `myfileab', and so on, supply an +command line preceded with a minus (e.g., `-500' for files with 500 +lines in them instead of 1,000). To change the name of the output +files to something like `myfileaa', `myfileab', and so on, supply an additional argument that specifies the file name prefix. Here is a version of `split' in `awk'. It uses the `ord()' and @@ -17065,7 +17083,7 @@ output file names: } # test argv in case reading from stdin instead of file if (i in ARGV) - i++ # skip data file name + i++ # skip datafile name if (i in ARGV) { outfile = ARGV[i] ARGV[i] = "" @@ -17137,8 +17155,8 @@ files named on the command line. Its usage is as follows: truncating them and starting over. The `BEGIN' rule first makes a copy of all the command-line arguments -into an array named `copy'. `ARGV[0]' is not copied, since it is not -needed. `tee' cannot use `ARGV' directly, since `awk' attempts to +into an array named `copy'. `ARGV[0]' is not needed, so it is not +copied. `tee' cannot use `ARGV' directly, because `awk' attempts to process each file name in `ARGV' as input data. If the first argument is `-a', then the flag variable `append' is @@ -17170,7 +17188,7 @@ input by setting `ARGV[1]' to `"-"' and `ARGC' to two: ARGC = 2 } - The following single rule does all the work. Since there is no + The following single rule does all the work. Because there is no pattern, it is executed for each line of input. The body of the rule simply prints the line into each file on the command line, and then to the standard output: @@ -17194,11 +17212,12 @@ It is also possible to write the loop this way: else print > copy[i] -This is more concise but it is also less efficient. The `if' is tested -for each record and for each output file. By duplicating the loop -body, the `if' is only tested once for each input record. If there are -N input records and M output files, the first method only executes N -`if' statements, while the second executes N`*'M `if' statements. +This is more concise, but it is also less efficient. The `if' is +tested for each record and for each output file. By duplicating the +loop body, the `if' is only tested once for each input record. If +there are N input records and M output files, the first method only +executes N `if' statements, while the second executes N`*'M `if' +statements. Finally, the `END' rule cleans up by closing all the output files: @@ -17376,13 +17395,13 @@ to. depending upon the results of `are_equal()''s comparison. If `uniq' is counting repeated lines, and the lines are equal, then it increments the `count' variable. Otherwise, it prints the line and resets `count', -since the two lines are not equal. +because the two lines are not equal. If `uniq' is not counting, and if the lines are equal, `count' is -incremented. Nothing is printed, since the point is to remove -duplicates. Otherwise, if `uniq' is counting repeated lines and more -than one line is seen, or if `uniq' is counting nonrepeated lines and -only one line is seen, then the line is printed, and `count' is reset. +incremented. Nothing is printed, as the point is to remove duplicates. +Otherwise, if `uniq' is counting repeated lines and more than one line +is seen, or if `uniq' is counting nonrepeated lines and only one line +is seen, then the line is printed, and `count' is reset. Finally, similar logic is used in the `END' rule to print the final line of input data: @@ -17454,10 +17473,10 @@ follows: `-c' Count only characters. - Implementing `wc' in `awk' is particularly elegant, since `awk' does -a lot of the work for us; it splits lines into words (i.e., fields) and -counts them, it counts lines (i.e., records), and it can easily tell us -how long a line is. + Implementing `wc' in `awk' is particularly elegant, because `awk' +does a lot of the work for us; it splits lines into words (i.e., +fields) and counts them, it counts lines (i.e., records), and it can +easily tell us how long a line is. This program uses the `getopt()' library function (*note Getopt Function::) and the file-transition functions (*note Filetrans @@ -17564,7 +17583,7 @@ in its length. Next, `lines' is incremented for each line read, and ---------- Footnotes ---------- - (1) Since `gawk' understands multibyte locales, this code counts + (1) Because `gawk' understands multibyte locales, this code counts characters, not bytes. @@ -17878,14 +17897,15 @@ record: print } - While it is possible to do character transliteration in a user-level -function, it is not necessarily efficient, and we (the `gawk' authors) -started to consider adding a built-in function. However, shortly after -writing this program, we learned that Brian Kernighan had added the -`toupper()' and `tolower()' functions to his `awk' (*note String -Functions::). These functions handle the vast majority of the cases -where character transliteration is necessary, and so we chose to simply -add those functions to `gawk' as well and then leave well enough alone. + It is possible to do character transliteration in a user-level +function, but it is not necessarily efficient, and we (the `gawk' +developers) started to consider adding a built-in function. However, +shortly after writing this program, we learned that Brian Kernighan had +added the `toupper()' and `tolower()' functions to his `awk' (*note +String Functions::). These functions handle the vast majority of the +cases where character transliteration is necessary, and so we chose to +simply add those functions to `gawk' as well and then leave well enough +alone. An obvious improvement to this program would be to set up the `t_ar' array only once, in a `BEGIN' rule. However, this assumes that the @@ -17922,7 +17942,7 @@ been read. The `BEGIN' rule simply sets `RS' to the empty string, so that `awk' splits records at blank lines (*note Records::). It sets `MAXLINES' to -100, since 100 is the maximum number of lines on the page (20 * 5 = +100, because 100 is the maximum number of lines on the page (20 * 5 = 100). Most of the work is done in the `printpage()' function. The label @@ -18046,9 +18066,9 @@ on real text files: * The `awk' language considers upper- and lowercase characters to be distinct. Therefore, "bartender" and "Bartender" are not treated - as the same word. This is undesirable, since in normal text, words - are capitalized if they begin sentences, and a frequency analyzer - should not be sensitive to capitalization. + as the same word. This is undesirable, because words are + capitalized if they begin sentences in normal text, and a + frequency analyzer should not be sensitive to capitalization. * Words are detected using the `awk' convention that fields are separated just by whitespace. Other characters in the input @@ -18171,9 +18191,9 @@ File: gawk.info, Node: Extract Program, Next: Simple Sed, Prev: History Sorti The nodes *note Library Functions::, and *note Sample Programs::, are the top level nodes for a large number of `awk' programs. If you want -to experiment with these programs, it is tedious to have to type them -in by hand. Here we present a program that can extract parts of a -Texinfo input file into separate files. +to experiment with these programs, it is tedious to type them in by +hand. Here we present a program that can extract parts of a Texinfo +input file into separate files. This Info file is written in Texinfo (http://www.gnu.org/software/texinfo/), the GNU project's document @@ -18230,7 +18250,7 @@ file looks something like this: @example @c file examples/messages.awk - END @{ print "Always avoid bored archeologists!" @} + END @{ print "Always avoid bored archaeologists!" @} @c end file @end example ... @@ -18366,15 +18386,15 @@ File: gawk.info, Node: Simple Sed, Next: Igawk Program, Prev: Extract Program The `sed' utility is a stream editor, a program that reads a stream of data, makes changes to it, and passes it on. It is often used to make global changes to a large file or to a stream of data generated by a -pipeline of commands. While `sed' is a complicated program in its own -right, its most common use is to perform global substitutions in the -middle of a pipeline: +pipeline of commands. Although `sed' is a complicated program in its +own right, its most common use is to perform global substitutions in +the middle of a pipeline: COMMAND1 < orig.data | sed 's/old/new/g' | COMMAND2 > result Here, `s/old/new/g' tells `sed' to look for the regexp `old' on each -input line and globally replace it with the text `new', i.e., all the -occurrences on a line. This is similar to `awk''s `gsub()' function +input line and globally replace it with the text `new' (i.e., all the +occurrences on a line). This is similar to `awk''s `gsub()' function (*note String Functions::). The following program, `awksed.awk', accepts at least two @@ -18435,7 +18455,7 @@ arguments and calling `usage()' if there is a problem. Then it sets (*note ARGC and ARGV::). The `usage()' function prints an error message and exits. Finally, -the single rule handles the printing scheme outlined above, using +the single rule handles the printing scheme outlined earlier, using `print' or `printf' as appropriate, depending upon the value of `RT'. @@ -18473,10 +18493,10 @@ to be able to write programs in the following manner: The following program, `igawk.sh', provides this service. It simulates `gawk''s searching of the `AWKPATH' variable and also allows -"nested" includes; i.e., a file that is included with `@include' can -contain further `@include' statements. `igawk' makes an effort to only -include files once, so that nested includes don't accidentally include -a library function twice. +"nested" includes (i.e., a file that is included with `@include' can +contain further `@include' statements). `igawk' makes an effort to +only include files once, so that nested includes don't accidentally +include a library function twice. `igawk' should behave just like `gawk' externally. This means it should accept all of `gawk''s command-line arguments, including the @@ -18497,8 +18517,8 @@ language.(1) It works as follows: b. Source file names, provided with `-f'. We use a neat trick and append `@include FILENAME' to the shell variable's - contents. Since the file-inclusion program works the way - `gawk' does, this gets the text of the file included into the + contents. Because the file-inclusion program works the way + `gawk' does, this gets the text of the file included in the program at the correct point. 3. Run an `awk' program (naturally) over the shell variable's @@ -18758,13 +18778,13 @@ is saved as a single string, even if the results contain whitespace. It's done in these steps: 1. Run `gawk' with the `@include'-processing program (the value of - the `expand_prog' shell variable) on standard input. + the `expand_prog' shell variable) reading standard input. 2. Standard input is the contents of the user's program, from the - shell variable `program'. Its contents are fed to `gawk' via a - here document. + shell variable `program'. Feed its contents to `gawk' via a here + document. - 3. The results of this processing are saved in the shell variable + 3. Save the results of this processing in the shell variable `processed_program' by using command substitution. The last step is to call `gawk' with the expanded program, along @@ -18821,23 +18841,23 @@ use of `awk' programs as Web CGI scripts. File: gawk.info, Node: Anagram Program, Next: Signature Program, Prev: Igawk Program, Up: Miscellaneous Programs -11.3.10 Finding Anagrams From A Dictionary +11.3.10 Finding Anagrams from a Dictionary ------------------------------------------ An interesting programming challenge is to search for "anagrams" in a word list (such as `/usr/share/dict/words' on many GNU/Linux systems). One word is an anagram of another if both words contain the same letters -(for example, "babbling" and "blabbing"). +(e.g., "babbling" and "blabbing"). - Column 2, Problem C of Jon Bentley's `Programming Pearls', second -edition, presents an elegant algorithm. The idea is to give words that + Column 2, Problem C, of Jon Bentley's `Programming Pearls', Second +Edition, presents an elegant algorithm. The idea is to give words that are anagrams a common signature, sort all the words together by their signature, and then print them. Dr. Bentley observes that taking the letters in each word and sorting them produces that common signature. The following program uses arrays of arrays to bring together words with the same signature and array sorting to print the words in sorted -order. +order: # anagram.awk --- An implementation of the anagram finding algorithm # from Jon Bentley's "Programming Pearls", 2nd edition. @@ -18874,8 +18894,8 @@ back together: } Finally, the `END' rule traverses the array and prints out the -anagram lists. It sends the output to the system `sort' command, since -otherwise the anagrams would appear in arbitrary order: +anagram lists. It sends the output to the system `sort' command +because otherwise the anagrams would appear in arbitrary order: END { sort = "sort" @@ -18910,7 +18930,7 @@ otherwise the anagrams would appear in arbitrary order: File: gawk.info, Node: Signature Program, Prev: Anagram Program, Up: Miscellaneous Programs -11.3.11 And Now For Something Completely Different +11.3.11 And Now for Something Completely Different -------------------------------------------------- The following program was written by Davide Brini and is published on @@ -19191,7 +19211,7 @@ in a particular order that you, the programmer, choose. `gawk' lets you do this. *note Controlling Scanning::, describes how you can assign special, -pre-defined values to `PROCINFO["sorted_in"]' in order to control the +predefined values to `PROCINFO["sorted_in"]' in order to control the order in which `gawk' traverses an array during a `for' loop. In addition, the value of `PROCINFO["sorted_in"]' can be a function @@ -19348,7 +19368,7 @@ Running the program produces the following output: The comparison should normally always return the same value when given a specific pair of array elements as its arguments. If -inconsistent results are returned then the order is undefined. This +inconsistent results are returned, then the order is undefined. This behavior can be exploited to introduce random order into otherwise seemingly ordered data: @@ -19358,7 +19378,7 @@ seemingly ordered data: return (2 - 4 * rand()) } - As mentioned above, the order of the indices is arbitrary if two + As already mentioned, the order of the indices is arbitrary if two elements compare equal. This is usually not a problem, but letting the tied elements come out in arbitrary order can be an issue, especially when comparing item values. The partial ordering of the equal elements @@ -19392,16 +19412,16 @@ such a function. When string comparisons are made during a sort, either for element values where one or both aren't numbers, or for element indices handled as strings, the value of `IGNORECASE' (*note Built-in Variables::) -controls whether the comparisons treat corresponding uppercase and +controls whether the comparisons treat corresponding upper- and lowercase letters as equivalent or distinct. - Another point to keep in mind is that in the case of subarrays the + Another point to keep in mind is that in the case of subarrays, the element values can themselves be arrays; a production comparison function should use the `isarray()' function (*note Type Functions::), to check for this, and choose a defined sorting order for subarrays. All sorting based on `PROCINFO["sorted_in"]' is disabled in POSIX -mode, since the `PROCINFO' array is not special in that case. +mode, because the `PROCINFO' array is not special in that case. As a side note, sorting the array indices before traversing the array has been reported to add 15% to 20% overhead to the execution @@ -19420,10 +19440,10 @@ File: gawk.info, Node: Array Sorting Functions, Prev: Controlling Array Traver --------------------------------------------------- In most `awk' implementations, sorting an array requires writing a -`sort()' function. While this can be educational for exploring -different sorting algorithms, usually that's not the point of the -program. `gawk' provides the built-in `asort()' and `asorti()' -functions (*note String Functions::) for sorting arrays. For example: +`sort()' function. This can be educational for exploring different +sorting algorithms, but usually that's not the point of the program. +`gawk' provides the built-in `asort()' and `asorti()' functions (*note +String Functions::) for sorting arrays. For example: POPULATE THE ARRAY data n = asort(data) @@ -19504,8 +19524,8 @@ comparisons are based on character values only.(1) ---------- Footnotes ---------- (1) This is true because locale-based comparison occurs only when in -POSIX compatibility mode, and since `asort()' and `asorti()' are `gawk' -extensions, they are not available in that case. +POSIX-compatibility mode, and because `asort()' and `asorti()' are +`gawk' extensions, they are not available in that case. File: gawk.info, Node: Two-way I/O, Next: TCP/IP Networking, Prev: Array Sorting, Up: Advanced Features @@ -19534,7 +19554,7 @@ the program be run in a directory that cannot be shared among users; for example, `/tmp' will not do, as another user might happen to be using a temporary file with the same name.(1) However, with `gawk', it is possible to open a _two-way_ pipe to another process. The second -process is termed a "coprocess", since it runs in parallel with `gawk'. +process is termed a "coprocess", as it runs in parallel with `gawk'. The two-way connection is created using the `|&' operator (borrowed from the Korn shell, `ksh'):(2) @@ -19613,7 +19633,7 @@ per-command basis, by setting a special element in the `PROCINFO' array command = "sort -nr" # command, save in convenience variable PROCINFO[command, "pty"] = 1 # update PROCINFO - print ... |& command # start two-way pipe + print ... |& command # start two-way pipe ... Using ptys usually avoids the buffer deadlock issues described earlier, @@ -19650,7 +19670,7 @@ connection. You can think of this as just a _very long_ two-way pipeline to a coprocess. The way `gawk' decides that you want to use TCP/IP networking is by recognizing special file names that begin with one of -`/inet/', `/inet4/' or `/inet6/'. +`/inet/', `/inet4/', or `/inet6/'. The full syntax of the special file name is `/NET-TYPE/PROTOCOL/LOCAL-PORT/REMOTE-HOST/REMOTE-PORT'. The @@ -19676,7 +19696,7 @@ LOCAL-PORT `getaddrinfo()' function. REMOTE-HOST - The IP address or fully-qualified domain name of the Internet host + The IP address or fully qualified domain name of the Internet host to which you want to connect. REMOTE-PORT @@ -19724,7 +19744,7 @@ used to change the name of the file where `gawk' will write the profile: gawk --profile=myprog.prof -f myprog.awk data1 data2 -In the above example, `gawk' places the profile in `myprog.prof' +In the preceding example, `gawk' places the profile in `myprog.prof' instead of in `awkprof.out'. Here is a sample session showing a simple `awk' program, its input @@ -19855,9 +19875,9 @@ output. They are as follows: * Parentheses are used only where needed, as indicated by the structure of the program and the precedence rules. For example, - `(3 + 5) * 4' means add three plus five, then multiply the total - by four. However, `3 + 5 * 4' has no parentheses, and means `3 + - (5 * 4)'. + `(3 + 5) * 4' means add three and five, then multiply the total by + four. However, `3 + 5 * 4' has no parentheses, and means `3 + (5 + * 4)'. * Parentheses are used around the arguments to `print' and `printf' only when the `print' or `printf' statement is followed by a @@ -20062,12 +20082,12 @@ components--programs written in C or C++, as well as scripts written in named `guide'. Internationalization consists of the following steps, in this order: - 1. The programmer goes through the source for all of `guide''s - components and marks each string that is a candidate for - translation. For example, `"`-F': option required"' is a good - candidate for translation. A table with strings of option names - is not (e.g., `gawk''s `--profile' option should remain the same, - no matter what the local language). + 1. The programmer reviews the source for all of `guide''s components + and marks each string that is a candidate for translation. For + example, `"`-F': option required"' is a good candidate for + translation. A table with strings of option names is not (e.g., + `gawk''s `--profile' option should remain the same, no matter what + the local language). 2. The programmer indicates the application's text domain (`"guide"') to the `gettext' library, by calling the `textdomain()' function. @@ -20136,8 +20156,8 @@ are: a different category.) `LC_COLLATE' - Text-collation information; i.e., how different characters and/or - groups of characters sort in a given language. + Text-collation information (i.e., how different characters and/or + groups of characters sort in a given language). `LC_CTYPE' Character-type information (alphabetic, digit, upper- or @@ -20442,7 +20462,7 @@ them to other versions of `awk'. Consider this program: As written, it won't work on other versions of `awk'. However, it is actually almost portable, requiring very little change: - * Assignments to `TEXTDOMAIN' won't have any effect, since + * Assignments to `TEXTDOMAIN' won't have any effect, because `TEXTDOMAIN' is not special in other `awk' implementations. * Non-GNU versions of `awk' treat marked strings as the @@ -20478,10 +20498,10 @@ actually almost portable, requiring very little change: and arguments unchanged to the underlying C library version of `sprintf()', but only one format and argument at a time. What happens if a positional specification is used is anybody's guess. - However, since the positional specifications are primarily for use - in _translated_ format strings, and since non-GNU `awk's never - retrieve the translated string, this should not be a problem in - practice. + However, because the positional specifications are primarily for + use in _translated_ format strings, and because non-GNU `awk's + never retrieve the translated string, this should not be a problem + in practice. ---------- Footnotes ---------- @@ -20544,7 +20564,7 @@ Following are the translations: The next step is to make the directory to hold the binary message object file and then to create the `guide.mo' file. We pretend that -our file is to be used in the `en_US.UTF-8' locale, since we have to +our file is to be used in the `en_US.UTF-8' locale, because we have to use a locale name known to the C `gettext' routines. The directory layout shown here is standard for GNU `gettext' on GNU/Linux systems. Other versions of `gettext' may use a different layout: @@ -20565,7 +20585,7 @@ proper directory (using the `-o' option) so that `gawk' can find it: -| Like, the scoop is 42 -| Pardon me, Zaphod who? - If the three replacement functions for `dcgettext()', `dcngettext()' + If the three replacement functions for `dcgettext()', `dcngettext()', and `bindtextdomain()' (*note I18N Portability::) are in a file named `libintl.awk', then we can run `guide.awk' unchanged as follows: @@ -20654,7 +20674,7 @@ program is easy. File: gawk.info, Node: Debugging, Next: Sample Debugging Session, Up: Debugger -14.1 Introduction to The `gawk' Debugger +14.1 Introduction to the `gawk' Debugger ======================================== This minor node introduces debugging in general and begins the @@ -20676,9 +20696,9 @@ File: gawk.info, Node: Debugging Concepts, Next: Debugging Terms, Up: Debuggi ahead to the next section on the specific features of the `gawk' debugger.) - Of course, a debugging program cannot remove bugs for you, since it -has no way of knowing what you or your users consider a "bug" and what -is a "feature." (Sometimes, we humans have a hard time with this + Of course, a debugging program cannot remove bugs for you, because +it has no way of knowing what you or your users consider a "bug" versus +a "feature." (Sometimes, we humans have a hard time with this ourselves.) In that case, what can you expect from such a tool? The answer to that depends on the language being debugged, but in general, you can expect at least the following: @@ -20694,7 +20714,7 @@ you can expect at least the following: * The chance to see the values of data in the program at any point in execution, and also to change that data on the fly, to see how that - affects what happens afterwards. (This often includes the ability + affects what happens afterward. (This often includes the ability to look at internal data structures besides the variables you actually defined in your code.) @@ -20714,9 +20734,9 @@ File: gawk.info, Node: Debugging Terms, Next: Awk Debugging, Prev: Debugging Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. The following list -defines terms used throughout the rest of this major node. +defines terms used throughout the rest of this major node: -"Stack Frame" +"Stack frame" Programs generally call functions during the course of their execution. One function can call another, or a function can call itself (recursion). You can view the chain of called functions @@ -20752,11 +20772,11 @@ defines terms used throughout the rest of this major node. breakpoints are oriented around the code: stop when a certain point in the code is reached. A watchpoint, however, specifies that program execution should stop when a _data value_ is changed. - This is useful, since sometimes it happens that a variable - receives an erroneous value, and it's hard to track down where - this happens just by looking at the code. By using a watchpoint, - you can stop whenever a variable is assigned to, and usually find - the errant code quite quickly. + This is useful, as sometimes it happens that a variable receives + an erroneous value, and it's hard to track down where this happens + just by looking at the code. By using a watchpoint, you can stop + whenever a variable is assigned to, and usually find the errant + code quite quickly. File: gawk.info, Node: Awk Debugging, Prev: Debugging Terms, Up: Debugging @@ -20767,16 +20787,16 @@ File: gawk.info, Node: Awk Debugging, Prev: Debugging Terms, Up: Debugging Debugging an `awk' program has some specific aspects that are not shared with other programming languages. - First of all, the fact that `awk' programs usually take input -line-by-line from a file or files and operate on those lines using -specific rules makes it especially useful to organize viewing the -execution of the program in terms of these rules. As we will see, each -`awk' rule is treated almost like a function call, with its own -specific block of instructions. + First of all, the fact that `awk' programs usually take input line +by line from a file or files and operate on those lines using specific +rules makes it especially useful to organize viewing the execution of +the program in terms of these rules. As we will see, each `awk' rule +is treated almost like a function call, with its own specific block of +instructions. - In addition, since `awk' is by design a very concise language, it is -easy to lose sight of everything that is going on "inside" each line of -`awk' code. The debugger provides the opportunity to look at the + In addition, because `awk' is by design a very concise language, it +is easy to lose sight of everything that is going on "inside" each line +of `awk' code. The debugger provides the opportunity to look at the individual primitive instructions carried out by the higher-level `awk' commands. @@ -20887,8 +20907,8 @@ the current stack frames: -| #1 in main() at `awklib/eg/prog/uniq.awk':88 This tells us that `are_equal()' was called by the main program at -line 88 of `uniq.awk'. (This is not a big surprise, since this is the -only call to `are_equal()' in the program, but in more complex +line 88 of `uniq.awk'. (This is not a big surprise, because this is +the only call to `are_equal()' in the program, but in more complex programs, knowing who called a function and with what parameters can be the key to finding the source of the problem.) @@ -20900,7 +20920,7 @@ Actually, the debugger gives us: gawk> p n -| n = untyped variable -In this case, `n' is an uninitialized local variable, since the +In this case, `n' is an uninitialized local variable, because the function was called without arguments (*note Function Calls::). A more useful variable to display might be the current record: @@ -20908,8 +20928,8 @@ function was called without arguments (*note Function Calls::). gawk> p $0 -| $0 = "gawk is a wonderful program!" -This might be a bit puzzling at first since this is the second line of -our test input above. Let's look at `NR': +This might be a bit puzzling at first, as this is the second line of +our test input. Let's look at `NR': gawk> p NR -| NR = 2 @@ -20940,7 +20960,7 @@ typing `n' (for "next"): This tells us that `gawk' is now ready to execute line 66, which decides whether to give the lines the special "field skipping" treatment indicated by the `-1' command-line option. (Notice that we skipped -from where we were before at line 63 to here, since the condition in +from where we were before at line 63 to here, because the condition in line 63 `if (fcount == 0 && charcount == 0)' was false.) Continuing to step, we now get to the splitting of the current and @@ -20965,9 +20985,9 @@ split into, so we try to look: This is kind of disappointing, though. All we found out is that there are five elements in `alast'; `m' and `aline' don't have values -since we are at line 68 but haven't executed it yet. This information -is useful enough (we now know that none of the words were accidentally -left out), but what if we want to see inside the array? +because we are at line 68 but haven't executed it yet. This +information is useful enough (we now know that none of the words were +accidentally left out), but what if we want to see inside the array? The first choice would be to use subscripts: @@ -21049,7 +21069,7 @@ abbreviation on a second description line. A debugger command name may also be truncated if that partial name is unambiguous. The debugger has the built-in capability to automatically repeat the previous command just by hitting <Enter>. This works for the commands `list', `next', -`nexti', `step', `stepi' and `continue' executed without any argument. +`nexti', `step', `stepi', and `continue' executed without any argument. * Menu: @@ -21067,10 +21087,10 @@ File: gawk.info, Node: Breakpoint Control, Next: Debugger Execution Control, 14.3.1 Control of Breakpoints ----------------------------- -As we saw above, the first thing you probably want to do in a debugging -session is to get your breakpoints set up, since otherwise your program -will just run as if it was not under the debugger. The commands for -controlling breakpoints are: +As we saw earlier, the first thing you probably want to do in a +debugging session is to get your breakpoints set up, because your +program will otherwise just run as if it was not under the debugger. +The commands for controlling breakpoints are: `break' [[FILENAME`:']N | FUNCTION] [`"EXPRESSION"'] `b' [[FILENAME`:']N | FUNCTION] [`"EXPRESSION"'] @@ -21122,8 +21142,8 @@ controlling breakpoints are: reached. If the condition is true, then the debugger stops execution and prompts for a command. Otherwise, the debugger continues executing the program. If the condition expression is - not specified, any existing condition is removed; i.e., the - breakpoint or watchpoint is made unconditional. + not specified, any existing condition is removed (i.e., the + breakpoint or watchpoint is made unconditional). `delete' [N1 N2 ...] [N-M] `d' [N1 N2 ...] [N-M] @@ -21214,7 +21234,7 @@ execution of the program than we saw in our earlier example: Cancel execution of a function call. If VALUE (either a string or a number) is specified, it is used as the function's return value. If used in a frame other than the innermost one (the currently - executing function, i.e., frame number 0), discard all inner + executing function; i.e., frame number 0), discard all inner frames in addition to the selected one, and the caller of that frame becomes the innermost frame. @@ -21262,7 +21282,7 @@ The commands for viewing and changing variables inside of `gawk' are: gawk> display x -| 10: x = 1 - displays the assigned item number, the variable name and its + This displays the assigned item number, the variable name, and its current value. If the display variable refers to a function parameter, it is silently deleted from the list as soon as the execution reaches a context where no such variable of the given @@ -21311,7 +21331,7 @@ AWK STATEMENTS (`"'...`"'). You can also set special `awk' variables, such as `FS', `NF', - `NR', etc. + `NR', and son on. `watch' VAR | `$'N [`"EXPRESSION"'] `w' VAR | `$'N [`"EXPRESSION"'] @@ -21355,8 +21375,8 @@ are: innermost COUNT frames if COUNT > 0. Print the outermost COUNT frames if COUNT < 0. The backtrace displays the name and arguments to each function, the source file name, and the line - number. The alias `where' for `backtrace' is provided for - long-time GDB users who may be used to that command. + number. The alias `where' for `backtrace' is provided for longtime + GDB users who may be used to that command. `down' [COUNT] Move COUNT (default 1) frames down the stack toward the innermost @@ -21378,7 +21398,7 @@ are: File: gawk.info, Node: Debugger Info, Next: Miscellaneous Debugger Commands, Prev: Execution Stack, Up: List of Debugger Commands -14.3.5 Obtaining Information about the Program and the Debugger State +14.3.5 Obtaining Information About the Program and the Debugger State --------------------------------------------------------------------- Besides looking at the values of variables, there is often a need to get @@ -21504,39 +21524,39 @@ categories, as follows: gawk> dump -| # BEGIN -| - -| [ 1:0xfcd340] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] - -| [ 1:0xfcc240] Op_push_i : "~" [MALLOC|STRING|STRCUR] - -| [ 1:0xfcc2a0] Op_push_i : "~" [MALLOC|STRING|STRCUR] - -| [ 1:0xfcc280] Op_match : - -| [ 1:0xfcc1e0] Op_store_var : O - -| [ 1:0xfcc2e0] Op_push_i : "==" [MALLOC|STRING|STRCUR] - -| [ 1:0xfcc340] Op_push_i : "==" [MALLOC|STRING|STRCUR] - -| [ 1:0xfcc320] Op_equal : - -| [ 1:0xfcc200] Op_store_var : o - -| [ 1:0xfcc380] Op_push : o - -| [ 1:0xfcc360] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER] - -| [ 1:0xfcc220] Op_push_lhs : o [do_reference = true] - -| [ 1:0xfcc300] Op_assign_plus : - -| [ :0xfcc2c0] Op_pop : - -| [ 1:0xfcc400] Op_push : O - -| [ 1:0xfcc420] Op_push_i : "" [MALLOC|STRING|STRCUR] - -| [ :0xfcc4a0] Op_no_op : - -| [ 1:0xfcc480] Op_push : O - -| [ :0xfcc4c0] Op_concat : [expr_count = 3] [concat_flag = 0] - -| [ 1:0xfcc3c0] Op_store_var : x - -| [ 1:0xfcc440] Op_push_lhs : X [do_reference = true] - -| [ 1:0xfcc3a0] Op_postincrement : - -| [ 1:0xfcc4e0] Op_push : x - -| [ 1:0xfcc540] Op_push : o - -| [ 1:0xfcc500] Op_plus : - -| [ 1:0xfcc580] Op_push : o - -| [ 1:0xfcc560] Op_plus : - -| [ 1:0xfcc460] Op_leq : - -| [ :0xfcc5c0] Op_jmp_false : [target_jmp = 0xfcc5e0] - -| [ 1:0xfcc600] Op_push_i : "%c" [MALLOC|STRING|STRCUR] - -| [ :0xfcc660] Op_no_op : - -| [ 1:0xfcc520] Op_assign_concat : c - -| [ :0xfcc620] Op_jmp : [target_jmp = 0xfcc440] + -| [ 1:0xfcd340] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] + -| [ 1:0xfcc240] Op_push_i : "~" [MALLOC|STRING|STRCUR] + -| [ 1:0xfcc2a0] Op_push_i : "~" [MALLOC|STRING|STRCUR] + -| [ 1:0xfcc280] Op_match : + -| [ 1:0xfcc1e0] Op_store_var : O + -| [ 1:0xfcc2e0] Op_push_i : "==" [MALLOC|STRING|STRCUR] + -| [ 1:0xfcc340] Op_push_i : "==" [MALLOC|STRING|STRCUR] + -| [ 1:0xfcc320] Op_equal : + -| [ 1:0xfcc200] Op_store_var : o + -| [ 1:0xfcc380] Op_push : o + -| [ 1:0xfcc360] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER] + -| [ 1:0xfcc220] Op_push_lhs : o [do_reference = true] + -| [ 1:0xfcc300] Op_assign_plus : + -| [ :0xfcc2c0] Op_pop : + -| [ 1:0xfcc400] Op_push : O + -| [ 1:0xfcc420] Op_push_i : "" [MALLOC|STRING|STRCUR] + -| [ :0xfcc4a0] Op_no_op : + -| [ 1:0xfcc480] Op_push : O + -| [ :0xfcc4c0] Op_concat : [expr_count = 3] [concat_flag = 0] + -| [ 1:0xfcc3c0] Op_store_var : x + -| [ 1:0xfcc440] Op_push_lhs : X [do_reference = true] + -| [ 1:0xfcc3a0] Op_postincrement : + -| [ 1:0xfcc4e0] Op_push : x + -| [ 1:0xfcc540] Op_push : o + -| [ 1:0xfcc500] Op_plus : + -| [ 1:0xfcc580] Op_push : o + -| [ 1:0xfcc560] Op_plus : + -| [ 1:0xfcc460] Op_leq : + -| [ :0xfcc5c0] Op_jmp_false : [target_jmp = 0xfcc5e0] + -| [ 1:0xfcc600] Op_push_i : "%c" [MALLOC|STRING|STRCUR] + -| [ :0xfcc660] Op_no_op : + -| [ 1:0xfcc520] Op_assign_concat : c + -| [ :0xfcc620] Op_jmp : [target_jmp = 0xfcc440] -| ... -| @@ -21587,10 +21607,10 @@ categories, as follows: `q' Exit the debugger. Debugging is great fun, but sometimes we all have to tend to other obligations in life, and sometimes we find - the bug, and are free to go on to the next one! As we saw above, - if you are running a program, the debugger warns you if you - accidentally type `q' or `quit', to make sure you really want to - quit. + the bug, and are free to go on to the next one! As we saw + earlier, if you are running a program, the debugger warns you if + you accidentally type `q' or `quit', to make sure you really want + to quit. `trace' [`on' | `off'] Turn on or off a continuous printing of instructions which are @@ -21649,7 +21669,8 @@ some limitations. A few which are worth being aware of are: Commands:: (or if you are already familiar with `gawk' internals), you will realize that much of the internal manipulation of data in `gawk', as in many interpreters, is done on a stack. `Op_push', - `Op_pop', etc., are the "bread and butter" of most `gawk' code. + `Op_pop', and the like, are the "bread and butter" of most `gawk' + code. Unfortunately, as of now, the `gawk' debugger does not allow you to examine the stack's contents. That is, the intermediate @@ -21661,7 +21682,7 @@ some limitations. A few which are worth being aware of are: * There is no way to look "inside" the process of compiling regular expressions to see if you got it right. As an `awk' programmer, - you are expected to know what `/[^[:alnum:][:blank:]]/' means. + you are expected to know the meaning of `/[^[:alnum:][:blank:]]/'. * The `gawk' debugger is designed to be used by running a program (with all its parameters) on the command line, as described in @@ -21705,17 +21726,17 @@ File: gawk.info, Node: Debugging Summary, Prev: Limitations, Up: Debugger File: gawk.info, Node: Arbitrary Precision Arithmetic, Next: Dynamic Extensions, Prev: Debugger, Up: Top -15 Arithmetic and Arbitrary Precision Arithmetic with `gawk' +15 Arithmetic and Arbitrary-Precision Arithmetic with `gawk' ************************************************************ This major node introduces some basic concepts relating to how computers do arithmetic and defines some important terms. It then proceeds to describe floating-point arithmetic, which is what `awk' -uses for all its computations, including a discussion of arbitrary -precision floating point arithmetic, which is a feature available only -in `gawk'. It continues on to present arbitrary precision integers, and -concludes with a description of some points where `gawk' and the POSIX -standard are not quite in agreement. +uses for all its computations, including a discussion of +arbitrary-precision floating-point arithmetic, which is a feature +available only in `gawk'. It continues on to present +arbitrary-precision integers, and concludes with a description of some +points where `gawk' and the POSIX standard are not quite in agreement. NOTE: Most users of `gawk' can safely skip this chapter. But if you want to do scientific calculations with `gawk', this is the @@ -21775,37 +21796,37 @@ Integer arithmetic In computers, integer values come in two flavors: "signed" and "unsigned". Signed values may be negative or positive, whereas - unsigned values are always positive (that is, greater than or equal + unsigned values are always positive (i.e., greater than or equal to zero). In computer systems, integer arithmetic is exact, but the possible range of values is limited. Integer arithmetic is generally - faster than floating point arithmetic. + faster than floating-point arithmetic. -Floating point arithmetic +Floating-point arithmetic Floating-point numbers represent what were called in school "real" - numbers; i.e., those that have a fractional part, such as - 3.1415927. The advantage to floating-point numbers is that they + numbers (i.e., those that have a fractional part, such as + 3.1415927). The advantage to floating-point numbers is that they can represent a much larger range of values than can integers. The disadvantage is that there are numbers that they cannot represent exactly. - Modern systems support floating point arithmetic in hardware, with + Modern systems support floating-point arithmetic in hardware, with a limited range of values. There are software libraries that allow - the use of arbitrary precision floating point calculations. + the use of arbitrary-precision floating-point calculations. - POSIX `awk' uses "double precision" floating-point numbers, which - can hold more digits than "single precision" floating-point - numbers. `gawk' has facilities for performing arbitrary precision - floating point arithmetic, which we describe in more detail + POSIX `awk' uses "double-precision" floating-point numbers, which + can hold more digits than "single-precision" floating-point + numbers. `gawk' has facilities for performing arbitrary-precision + floating-point arithmetic, which we describe in more detail shortly. - Computers work with integer and floating point values of different -ranges. Integer values are usually either 32 or 64 bits in size. Single -precision floating point values occupy 32 bits, whereas double precision -floating point values occupy 64 bits. Floating point values are always -signed. The possible ranges of values are shown in *note -table-numeric-ranges::. + Computers work with integer and floating-point values of different +ranges. Integer values are usually either 32 or 64 bits in size. +Single-precision floating-point values occupy 32 bits, whereas +double-precision floating-point values occupy 64 bits. Floating-point +values are always signed. The possible ranges of values are shown in +*note table-numeric-ranges::. Numeric representation Minimum value Maximum value --------------------------------------------------------------------------- @@ -21813,14 +21834,14 @@ Numeric representation Minimum value Maximum value 32-bit unsigned integer 0 4,294,967,295 64-bit signed integer -9,223,372,036,854,775,8089,223,372,036,854,775,807 64-bit unsigned integer 0 18,446,744,073,709,551,615 -Single precision `1.175494e-38' `3.402823e+38' +Single-precision `1.175494e-38' `3.402823e+38' floating point (approximate) -Double precision `2.225074e-308' `1.797693e+308' +Double-precision `2.225074e-308' `1.797693e+308' floating point (approximate) -Table 15.1: Value Ranges for Different Numeric Representations +Table 15.1: Value ranges for different numeric representations ---------- Footnotes ---------- @@ -21829,7 +21850,7 @@ Table 15.1: Value Ranges for Different Numeric Representations File: gawk.info, Node: Math Definitions, Next: MPFR features, Prev: Computer Arithmetic, Up: Arbitrary Precision Arithmetic -15.2 Other Stuff To Know +15.2 Other Stuff to Know ======================== The rest of this major node uses a number of terms. Here are some @@ -21888,7 +21909,7 @@ material here. are provided later. "Significand" - A floating point value consists the significand multiplied by 10 + A floating-point value consists the significand multiplied by 10 to the power of the exponent. For example, in `1.2345e67', the significand is `1.2345'. @@ -21904,10 +21925,10 @@ information on some of those terms. On modern systems, floating-point hardware uses the representation and operations defined by the IEEE 754 standard. Three of the standard -IEEE 754 types are 32-bit single precision, 64-bit double precision and -128-bit quadruple precision. The standard also specifies extended +IEEE 754 types are 32-bit single precision, 64-bit double precision, +and 128-bit quadruple precision. The standard also specifies extended precision formats to allow greater precisions and larger exponent -ranges. (`awk' uses only the 64-bit double precision format.) +ranges. (`awk' uses only the 64-bit double-precision format.) *note table-ieee-formats:: lists the precision and exponent field values for the basic IEEE 754 binary formats: @@ -21919,7 +21940,7 @@ Single 32 24 -126 +127 Double 64 53 -1022 +1023 Quadruple 128 113 -16382 +16383 -Table 15.2: Basic IEEE Format Values +Table 15.2: Basic IEEE format values NOTE: The precision numbers include the implied leading one that gives them one extra bit of significand. @@ -21932,13 +21953,13 @@ paraphrased, and for the examples. File: gawk.info, Node: MPFR features, Next: FP Math Caution, Prev: Math Definitions, Up: Arbitrary Precision Arithmetic -15.3 Arbitrary Precision Arithmetic Features In `gawk' +15.3 Arbitrary-Precision Arithmetic Features in `gawk' ====================================================== -By default, `gawk' uses the double precision floating-point values +By default, `gawk' uses the double-precision floating-point values supplied by the hardware of the system it runs on. However, if it was -compiled to do so, `gawk' uses the `http://www.mpfr.org GNU MPFR' and -GNU MP (http://gmplib.org) (GMP) libraries for arbitrary precision +compiled to do so, `gawk' uses the GNU MPFR (http://www.mpfr.org) and +GNU MP (http://gmplib.org) (GMP) libraries for arbitrary-precision arithmetic on numbers. You can see if MPFR support is available like so: @@ -21970,7 +21991,7 @@ more information. File: gawk.info, Node: FP Math Caution, Next: Arbitrary Precision Integers, Prev: MPFR features, Up: Arbitrary Precision Arithmetic -15.4 Floating Point Arithmetic: Caveat Emptor! +15.4 Floating-Point Arithmetic: Caveat Emptor! ============================================== Math class is tough! -- Teen Talk Barbie, July 1992 @@ -22004,7 +22025,7 @@ in computer science. File: gawk.info, Node: Inexactness of computations, Next: Getting Accuracy, Up: FP Math Caution -15.4.1 Floating Point Arithmetic Is Not Exact +15.4.1 Floating-Point Arithmetic Is Not Exact --------------------------------------------- Binary floating-point representations and arithmetic are inexact. @@ -22012,9 +22033,10 @@ Simple values like 0.1 cannot be precisely represented using binary floating-point numbers, and the limited precision of floating-point numbers means that slight changes in the order of operations or the precision of intermediate storage can change the result. To make -matters worse, with arbitrary precision floating-point, you can set the -precision before starting a computation, but then you cannot be sure of -the number of significant decimal places in the final result. +matters worse, with arbitrary-precision floating-point arithmetic, you +can set the precision before starting a computation, but then you +cannot be sure of the number of significant decimal places in the final +result. * Menu: @@ -22036,8 +22058,8 @@ the following example: y = 0.425 Unlike the number in `y', the number stored in `x' is exactly -representable in binary since it can be written as a finite sum of one -or more fractions whose denominators are all powers of two. When +representable in binary because it can be written as a finite sum of +one or more fractions whose denominators are all powers of two. When `gawk' reads a floating-point number from program source, it automatically rounds that number to whatever precision your machine supports. If you try to print the numeric content of a variable using @@ -22070,7 +22092,7 @@ work like you would expect: The general wisdom when comparing floating-point values is to see if they are within some small range of each other (called a "delta", or "tolerance"). You have to decide how small a delta is important to -you. Code to do this looks something like this: +you. Code to do this looks something like the following: delta = 0.00001 # for example difference = abs(a) - abs(b) # subtract the two values @@ -22090,7 +22112,7 @@ File: gawk.info, Node: Errors accumulate, Prev: Comparing FP Values, Up: Inex The loss of accuracy during a single computation with floating-point numbers usually isn't enough to worry about. However, if you compute a -value which is the result of a sequence of floating point operations, +value which is the result of a sequence of floating-point operations, the error can accumulate and greatly affect the computation itself. Here is an attempt to compute the value of pi using one of its many series representations: @@ -22133,10 +22155,10 @@ representations yield an unexpected result: File: gawk.info, Node: Getting Accuracy, Next: Try To Round, Prev: Inexactness of computations, Up: FP Math Caution -15.4.2 Getting The Accuracy You Need +15.4.2 Getting the Accuracy You Need ------------------------------------ -Can arbitrary precision arithmetic give exact results? There are no +Can arbitrary-precision arithmetic give exact results? There are no easy answers. The standard rules of algebra often do not apply when using floating-point arithmetic. Among other things, the distributive and associative laws do not hold completely, and order of operation may @@ -22144,7 +22166,7 @@ be important for your computation. Rounding error, cumulative precision loss and underflow are often troublesome. When `gawk' tests the expressions `0.1 + 12.2' and `12.3' for -equality using the machine double precision arithmetic, it decides that +equality using the machine double-precision arithmetic, it decides that they are not equal! (*Note Comparing FP Values::.) You can get the result you want by increasing the precision; 56 bits in this case does the job: @@ -22163,15 +22185,15 @@ value of `PREC': forget that the finite number of bits used to store the value is often just an approximation after proper rounding. The test for equality succeeds if and only if _all_ bits in the two operands are exactly the -same. Since this is not necessarily true after floating-point +same. Because this is not necessarily true after floating-point computations with a particular precision and effective rounding mode, a straight test for equality may not work. Instead, compare the two numbers to see if they are within the desirable delta of each other. In applications where 15 or fewer decimal places suffice, hardware -double precision arithmetic can be adequate, and is usually much faster. +double-precision arithmetic can be adequate, and is usually much faster. But you need to keep in mind that every floating-point operation can -suffer a new rounding error with catastrophic consequences as +suffer a new rounding error with catastrophic consequences, as illustrated by our earlier attempt to compute the value of pi. Extra precision can greatly enhance the stability and the accuracy of your computation in such cases. @@ -22193,10 +22215,10 @@ hand is often the correct approach in such situations. File: gawk.info, Node: Try To Round, Next: Setting precision, Prev: Getting Accuracy, Up: FP Math Caution -15.4.3 Try A Few Extra Bits of Precision and Rounding +15.4.3 Try a Few Extra Bits of Precision and Rounding ----------------------------------------------------- -Instead of arbitrary precision floating-point arithmetic, often all you +Instead of arbitrary-precision floating-point arithmetic, often all you need is an adjustment of your logic or a different order for the operations in your calculation. The stability and the accuracy of the computation of pi in the earlier example can be enhanced by using the @@ -22204,7 +22226,7 @@ following simple algebraic transformation: (sqrt(x * x + 1) - 1) / x == x / (sqrt(x * x + 1) + 1) -After making this, change the program converges to pi in under 30 +After making this change, the program converges to pi in under 30 iterations: $ gawk -f pi2.awk @@ -22220,7 +22242,7 @@ iterations: File: gawk.info, Node: Setting precision, Next: Setting the rounding mode, Prev: Try To Round, Up: FP Math Caution -15.4.4 Setting The Precision +15.4.4 Setting the Precision ---------------------------- `gawk' uses a global working precision; it does not keep track of the @@ -22234,13 +22256,13 @@ binary format. `PREC' IEEE 754 Binary Format --------------------------------------------------- -`"half"' 16-bit half-precision. -`"single"' Basic 32-bit single precision. -`"double"' Basic 64-bit double precision. -`"quad"' Basic 128-bit quadruple precision. -`"oct"' 256-bit octuple precision. +`"half"' 16-bit half-precision +`"single"' Basic 32-bit single precision +`"double"' Basic 64-bit double precision +`"quad"' Basic 128-bit quadruple precision +`"oct"' 256-bit octuple precision -Table 15.3: Predefined Precision Strings For `PREC' +Table 15.3: Predefined precision strings for `PREC' The following example illustrates the effects of changing precision on arithmetic operations: @@ -22277,7 +22299,7 @@ on arithmetic operations: File: gawk.info, Node: Setting the rounding mode, Prev: Setting precision, Up: FP Math Caution -15.4.5 Setting The Rounding Mode +15.4.5 Setting the Rounding Mode -------------------------------- The `ROUNDMODE' variable provides program level control over the @@ -22293,13 +22315,13 @@ Round toward zero `roundTowardZero' `"Z"' or `"z"' Round to nearest, ties away `roundTiesToAway' `"A"' or `"a"' from zero -Table 15.4: `gawk' Rounding Modes +Table 15.4: `gawk' rounding modes `ROUNDMODE' has the default value `"N"', which selects the IEEE 754 rounding mode `roundTiesToEven'. In *note Table 15.4: table-gawk-rounding-modes, the value `"A"' selects `roundTiesToAway'. This is only available if your version of the MPFR library supports it; -otherwise setting `ROUNDMODE' to `"A"' has no effect. +otherwise, setting `ROUNDMODE' to `"A"' has no effect. The default mode `roundTiesToEven' is the most preferred, but the least intuitive. This method does the obvious thing for most values, by @@ -22367,16 +22389,16 @@ to round halfway cases for `printf'. File: gawk.info, Node: Arbitrary Precision Integers, Next: POSIX Floating Point Problems, Prev: FP Math Caution, Up: Arbitrary Precision Arithmetic -15.5 Arbitrary Precision Integer Arithmetic with `gawk' +15.5 Arbitrary-Precision Integer Arithmetic with `gawk' ======================================================= When given the `-M' option, `gawk' performs all integer arithmetic -using GMP arbitrary precision integers. Any number that looks like an -integer in a source or data file is stored as an arbitrary precision +using GMP arbitrary-precision integers. Any number that looks like an +integer in a source or data file is stored as an arbitrary-precision integer. The size of the integer is limited only by the available memory. For example, the following computes 5^4^3^2, the result of -which is beyond the limits of ordinary hardware double precision -floating point values: +which is beyond the limits of ordinary hardware double-precision +floating-point values: $ gawk -M 'BEGIN { > x = 5^4^3^2 @@ -22386,10 +22408,10 @@ floating point values: -| number of digits = 183231 -| 62060698786608744707 ... 92256259918212890625 - If instead you were to compute the same value using arbitrary -precision floating-point values, the precision needed for correct -output (using the formula `prec = 3.322 * dps'), would be 3.322 x -183231, or 608693. + If instead you were to compute the same value using +arbitrary-precision floating-point values, the precision needed for +correct output (using the formula `prec = 3.322 * dps'), would be 3.322 +x 183231, or 608693. The result from an arithmetic operation with an integer and a floating-point value is a floating-point value with a precision equal @@ -22412,10 +22434,10 @@ case), or replace the floating-point constant `2.0' with an integer, to perform all computations using integer arithmetic to get the correct output. - Sometimes `gawk' must implicitly convert an arbitrary precision -integer into an arbitrary precision floating-point value. This is + Sometimes `gawk' must implicitly convert an arbitrary-precision +integer into an arbitrary-precision floating-point value. This is primarily because the MPFR library does not always provide the relevant -interface to process arbitrary precision integers or mixed-mode numbers +interface to process arbitrary-precision integers or mixed-mode numbers as needed by an operation or function. In such a case, the precision is set to the minimum value necessary for exact conversion, and the working precision is not used for this purpose. If this is not what you need or @@ -22429,8 +22451,8 @@ floating-point value to begin with: gawk -M 'BEGIN { n = 13.0; print n % 2.0 }' - Note that for the particular example above, it is likely best to -just use the following: + Note that for this particular example, it is likely best to just use +the following: gawk -M 'BEGIN { n = 13; print n % 2 }' @@ -22512,12 +22534,12 @@ that `awk' only understands decimal numbers (base 10), and not octal interpreted to imply that `awk' should support additional features. These features are: - * Interpretation of floating point data values specified in + * Interpretation of floating-point data values specified in hexadecimal notation (e.g., `0xDEADBEEF'). (Note: data values, _not_ source code constants.) - * Support for the special IEEE 754 floating point values "Not A - Number" (NaN), positive Infinity ("inf") and negative Infinity + * Support for the special IEEE 754 floating-point values "Not A + Number" (NaN), positive Infinity ("inf"), and negative Infinity ("-inf"). In particular, the format for these values is as specified by the ISO 1999 C standard, which ignores case and can allow implementation-dependent additional characters after the @@ -22526,9 +22548,9 @@ These features are: The first problem is that both of these are clear changes to historical practice: - * The `gawk' maintainer feels that supporting hexadecimal floating - point values, in particular, is ugly, and was never intended by the - original designers to be part of the language. + * The `gawk' maintainer feels that supporting hexadecimal + floating-point values, in particular, is ugly, and was never + intended by the original designers to be part of the language. * Allowing completely alphabetic strings to have valid numeric values is also a very severe departure from historical practice. @@ -22539,10 +22561,10 @@ interpretation of the standard, which requires a certain amount of intended by the standard developers. In other words, "we see how you got where you are, but we don't think that that's where you want to be." - Recognizing the above issues, but attempting to provide compatibility + Recognizing these issues, but attempting to provide compatibility with the earlier versions of the standard, the 2008 POSIX standard added explicit wording to allow, but not require, that `awk' support -hexadecimal floating point values and special values for "Not A Number" +hexadecimal floating-point values and special values for "Not A Number" and infinity. Although the `gawk' maintainer continues to feel that providing @@ -22591,11 +22613,11 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob ============ * Most computer arithmetic is done using either integers or - floating-point values. Standard `awk' uses double precision + floating-point values. Standard `awk' uses double-precision floating-point values. - * In the early 1990's, Barbie mistakenly said "Math class is tough!" - While math isn't tough, floating-point arithmetic isn't the same + * In the early 1990s, Barbie mistakenly said "Math class is tough!" + Although math isn't tough, floating-point arithmetic isn't the same as pencil and paper math, and care must be taken: - Not all numbers can be represented exactly. @@ -22616,7 +22638,7 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob set the precision in bits, and `ROUNDMODE' to set the IEEE 754 rounding mode. - * With `-M', `gawk' performs arbitrary precision integer arithmetic + * With `-M', `gawk' performs arbitrary-precision integer arithmetic using the GMP library. This is faster and more space efficient than using MPFR for the same calculations. @@ -22628,7 +22650,7 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob results from floating-point arithmetic. The lesson to remember is that floating-point arithmetic is always more complex than arithmetic using pencil and paper. In order to take advantage of - the power of computer floating-point, you need to know its + the power of computer floating point, you need to know its limitations and work within them. For most casual use of floating-point arithmetic, you will often get the expected result if you simply round the display of your final results to the @@ -22690,8 +22712,8 @@ routines that could be of use. As with most software, "the sky is the limit;" if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! - Extensions are written in C or C++, using the "Application -Programming Interface" (API) defined for this purpose by the `gawk' + Extensions are written in C or C++, using the "application +programming interface" (API) defined for this purpose by the `gawk' developers. The rest of this major node explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents the sample extensions included in @@ -22722,7 +22744,7 @@ the symbol exists in the global scope. Something like this is enough: File: gawk.info, Node: Extension Mechanism Outline, Next: Extension API Description, Prev: Plugin License, Up: Dynamic Extensions -16.3 At A High Level How It Works +16.3 How It Works at a High Level ================================= Communication between `gawk' and an extension is two-way. First, when @@ -22754,7 +22776,7 @@ figure-load-extension::. +-------+-+---+-+---+-+------------------+--------------------+ gawk Main Program Address Space Extension -Figure 16.1: Loading The Extension +Figure 16.1: Loading the extension The extension can call functions inside `gawk' through these function pointers, at runtime, without needing (link-time) access to @@ -22774,7 +22796,7 @@ figure-register-new-function::. +-------+-+---+-+---+-+------------------+--------------+-+---+ gawk Main Program Address Space Extension -Figure 16.2: Registering A New Function +Figure 16.2: Registering a new function In the other direction, the extension registers its new functions with `gawk' by passing function pointers to the functions that provide @@ -22795,7 +22817,7 @@ calling convention. This is shown in *note figure-call-new-function::. +-------+-+---+-+---+-+------------------+--------------+-+---+ gawk Main Program Address Space Extension -Figure 16.3: Calling The New Function +Figure 16.3: Calling the new function The `do_XXX()' function, in turn, then uses the function pointers in the API `struct' to do its work, such as updating variables or arrays, @@ -22868,17 +22890,19 @@ operations: * Allocating, reallocating, and releasing memory. * Registration functions. You may register: - - extension functions, - - exit callbacks, + - Extension functions - - a version string, + - Exit callbacks - - input parsers, + - A version string - - output wrappers, + - Input parsers + + - Output wrappers + + - Two-way processors - - and two-way processors. All of these are discussed in detail, later in this major node. * Printing fatal, warning, and "lint" warning messages. @@ -22910,8 +22934,8 @@ operations: Some points about using the API: - * The following types and/or macros and/or functions are referenced - in `gawkapi.h'. For correct use, you must therefore include the + * The following types, macros, and/or functions are referenced in + `gawkapi.h'. For correct use, you must therefore include the corresponding standard header file _before_ including `gawkapi.h': C Entity Header File @@ -22950,7 +22974,7 @@ operations: * The API defines several simple `struct's that map values as seen from `awk'. A value can be a `double', a string, or an array (as in multidimensional arrays, or when creating a new array). String - values maintain both pointer and length since embedded NUL + values maintain both pointer and length, because embedded NUL characters are allowed. NOTE: By intent, strings are maintained using the current @@ -22971,16 +22995,16 @@ operations: message (such as "scalar passed where array expected"). - While you may call the API functions by using the function pointers -directly, the interface is not so pretty. To make extension code look -more like regular code, the `gawkapi.h' header file defines several + You may call the API functions by using the function pointers +directly, but the interface is not so pretty. To make extension code +look more like regular code, the `gawkapi.h' header file defines several macros that you should use in your code. This minor node presents the macros as if they were functions. File: gawk.info, Node: General Data Types, Next: Memory Allocation Functions, Prev: Extension API Functions Introduction, Up: Extension API Description -16.4.2 General Purpose Data Types +16.4.2 General-Purpose Data Types --------------------------------- I have a true love/hate relationship with unions. -- Arnold @@ -22989,10 +23013,10 @@ File: gawk.info, Node: General Data Types, Next: Memory Allocation Functions, That's the thing about unions: the compiler will arrange things so they can accommodate both love and hate. -- Chet Ramey - The extension API defines a number of simple types and structures -for general purpose use. Additional, more specialized, data structures -are introduced in subsequent minor nodes, together with the functions -that use them. + The extension API defines a number of simple types and structures for +general-purpose use. Additional, more specialized, data structures are +introduced in subsequent minor nodes, together with the functions that +use them. `typedef void *awk_ext_id_t;' A value of this type is received from `gawk' when an extension is @@ -23017,8 +23041,8 @@ that use them. `} awk_string_t;' This represents a mutable string. `gawk' owns the memory pointed to if it supplied the value. Otherwise, it takes ownership of the - memory pointed to. *Such memory must come from calling one of the - `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()' functions!* + memory pointed to. _Such memory must come from calling one of the + `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()' functions!_ As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -23059,13 +23083,13 @@ that use them. `typedef void *awk_scalar_t;' Scalars can be represented as an opaque type. These values are obtained from `gawk' and then passed back into it. This is - discussed in a general fashion below, and in more detail in *note - Symbol table by cookie::. + discussed in a general fashion in the text following this list, + and in more detail in *note Symbol table by cookie::. `typedef void *awk_value_cookie_t;' A "value cookie" is an opaque type representing a cached value. - This is also discussed in a general fashion below, and in more - detail in *note Cached values::. + This is also discussed in a general fashion in the text following + this list, and in more detail in *note Cached values::. Scalar values in `awk' are either numbers or strings. The @@ -23073,7 +23097,7 @@ that use them. indicates what is in the `union'. Representing numbers is easy--the API uses a C `double'. Strings -require more work. Since `gawk' allows embedded NUL bytes in string +require more work. Because `gawk' allows embedded NUL bytes in string values, a string must be represented as a pair containing a data-pointer and length. This is the `awk_string_t' type. @@ -23085,15 +23109,14 @@ Manipulation::. The various macros listed earlier make it easier to use the elements of the `union' as if they were fields in a `struct'; this is a common -coding practice in C. Such code is easier to write and to read, -however it remains _your_ responsibility to make sure that the -`val_type' member correctly reflects the type of the value in the -`awk_value_t'. +coding practice in C. Such code is easier to write and to read, but it +remains _your_ responsibility to make sure that the `val_type' member +correctly reflects the type of the value in the `awk_value_t'. Conceptually, the first three members of the `union' (number, string, and array) are all that is needed for working with `awk' values. -However, since the API provides routines for accessing and changing the -value of global scalar variables only by using the variable's name, +However, because the API provides routines for accessing and changing +the value of global scalar variables only by using the variable's name, there is a performance penalty: `gawk' must find the variable each time it is accessed and changed. This turns out to be a real issue, not just a theoretical one. @@ -23131,7 +23154,7 @@ File: gawk.info, Node: Memory Allocation Functions, Next: Constructor Function The API provides a number of "memory allocation" functions for allocating memory that can be passed to `gawk', as well as a number of convenience macros. This node presents them all as function -prototypes, in the way that extension code would use them. +prototypes, in the way that extension code would use them: `void *gawk_malloc(size_t size);' Call the correct version of `malloc()' to allocate storage that may @@ -23168,8 +23191,8 @@ as if they were procedure calls that do not return a value. The pointer variable to point at the allocated storage. `type' - The type of the pointer variable, used to create a cast for - the call to `gawk_malloc()'. + The type of the pointer variable. This is used to create a + cast for the call to `gawk_malloc()'. `size' The total number of bytes to be allocated. @@ -23207,7 +23230,7 @@ File: gawk.info, Node: Constructor Functions, Next: Registration Functions, P The API provides a number of "constructor" functions for creating string and numeric values, as well as a number of convenience macros. This node presents them all as function prototypes, in the way that -extension code would use them. +extension code would use them: `static inline awk_value_t *' `make_const_string(const char *string, size_t length, awk_value_t *result)' @@ -23284,7 +23307,7 @@ Extension functions are described by the following record: functionality. The function must fill in `*result' with either a number or a string. `gawk' takes ownership of any string memory. As mentioned earlier, string memory *must* come from one of - `gawk_malloc()', `gawk_calloc()' or `gawk_realloc()'. + `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()'. The `num_actual_args' argument tells the C function how many actual parameters were passed from the calling `awk' code. @@ -23317,7 +23340,7 @@ An "exit callback" function is a function that `gawk' calls before it exits. Such functions are useful if you have general "cleanup" tasks that should be performed in your extension (such as closing database connections or other resource deallocations). You can register such a -function with `gawk' using the following function. +function with `gawk' using the following function: `void awk_atexit(void (*funcp)(void *data, int exit_status),' ` void *arg0);' @@ -23333,7 +23356,7 @@ function with `gawk' using the following function. A pointer to private data which `gawk' saves in order to pass to the function pointed to by `funcp'. - Exit callback functions are called in Last-In-First-Out (LIFO) + Exit callback functions are called in last-in-first-out (LIFO) order--that is, in the reverse order in which they are registered with `gawk'. @@ -23347,8 +23370,9 @@ You can register a version string which indicates the name and version of your extension, with `gawk', as follows: `void register_ext_version(const char *version);' - Register the string pointed to by `version' with `gawk'. `gawk' - does _not_ copy the `version' string, so it should not be changed. + Register the string pointed to by `version' with `gawk'. Note + that `gawk' does _not_ copy the `version' string, so it should not + be changed. `gawk' prints all registered extension version strings when it is invoked with the `--version' option. @@ -23373,14 +23397,14 @@ used for `RT', if any. To provide an input parser, you must first provide two functions (where XXX is a prefix name for your extension): -`awk_bool_t XXX_can_take_file(const awk_input_buf_t *iobuf)' +`awk_bool_t XXX_can_take_file(const awk_input_buf_t *iobuf);' This function examines the information available in `iobuf' (which we discuss shortly). Based on the information there, it decides if the input parser should be used for this file. If so, it should return true. Otherwise, it should return false. It should not change any state (variable values, etc.) within `gawk'. -`awk_bool_t XXX_take_control_of(awk_input_buf_t *iobuf)' +`awk_bool_t XXX_take_control_of(awk_input_buf_t *iobuf);' When `gawk' decides to hand control of the file over to the input parser, it calls this function. This function in turn must fill in certain fields in the `awk_input_buf_t' structure, and ensure @@ -23421,7 +23445,7 @@ used for `RT', if any. 2. When your extension is loaded, register your input parser with `gawk' using the `register_input_parser()' API function (described - below). + next). An `awk_input_buf_t' looks like this: @@ -23459,14 +23483,14 @@ decide if the input parser should be used for the file. The decision can be made based upon `gawk' state (the value of a variable defined previously by the extension and set by `awk' code), the name of the file, whether or not the file descriptor is valid, the information in -the `struct stat', or any combination of the above. +the `struct stat', or any combination of these factors. Once `XXX_can_take_file()' has returned true, and `gawk' has decided to use your input parser, it calls `XXX_take_control_of()'. That function then fills one of either the `get_record' field or the `read_func' field in the `awk_input_buf_t'. It must also ensure that -`fd' is _not_ set to `INVALID_HANDLE'. All of the fields that may be -filled by `XXX_take_control_of()' are as follows: +`fd' is _not_ set to `INVALID_HANDLE'. The following list describes +the fields that may be filled by `XXX_take_control_of()': `void *opaque;' This is used to hold any state information needed by the input @@ -23480,13 +23504,13 @@ filled by `XXX_take_control_of()' are as follows: ` size_t *rt_len);' This function pointer should point to a function that creates the input records. Said function is the core of the input parser. - Its behavior is described below. + Its behavior is described in the text following this list. `ssize_t (*read_func)();' This function pointer should point to function that has the same behavior as the standard POSIX `read()' system call. It is an alternative to the `get_record' pointer. Its behavior is also - described below. + described in the text following this list. `void (*close_func)(struct awk_input *iobuf);' This function pointer should point to a function that does the @@ -23611,8 +23635,8 @@ an extension to take over the output to a file opened with the `>' or The function pointed to by this field is called when `gawk' decides to let the output wrapper take control of the file. It should fill in appropriate members of the `awk_output_buf_t' - structure, as described below, and return true if successful, - false otherwise. + structure, as described next, and return true if successful, false + otherwise. `awk_const struct output_wrapper *awk_const next;' This is for use by `gawk'; therefore it is marked `awk_const' so @@ -23743,8 +23767,8 @@ File: gawk.info, Node: Printing Messages, Next: Updating `ERRNO', Prev: Regis ------------------------ You can print different kinds of warning messages from your extension, -as described below. Note that for these functions, you must pass in -the extension id received from `gawk' when the extension was loaded.(1) +as described here. Note that for these functions, you must pass in the +extension id received from `gawk' when the extension was loaded:(1) `void fatal(awk_ext_id_t id, const char *format, ...);' Print a message and then cause `gawk' to exit immediately. @@ -23804,7 +23828,7 @@ message, or reissue the request for the actual value type, as appropriate. This behavior is summarized in *note table-value-types-returned::. - Type of Actual Value: + Type of Actual Value -------------------------------------------------------------------------- String Number Array Undefined @@ -23814,12 +23838,12 @@ table-value-types-returned::. be converted, else false Type Array false false Array false -Requested: Scalar Scalar Scalar false false +Requested Scalar Scalar Scalar false false Undefined String Number Array Undefined Value false false false false Cookie -Table 16.1: API Value Types Returned +Table 16.1: API value types returned File: gawk.info, Node: Accessing Parameters, Next: Symbol Table Access, Prev: Requesting Values, Up: Extension API Description @@ -23900,8 +23924,8 @@ cannot change any of those variables. CAUTION: It is possible for the lookup of `PROCINFO' to fail. This happens if the `awk' program being run does not reference - `PROCINFO'; in this case `gawk' doesn't bother to create the array - and populate it. + `PROCINFO'; in this case, `gawk' doesn't bother to create the + array and populate it. File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev: Symbol table by name, Up: Symbol Table Access @@ -23912,9 +23936,9 @@ File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev: Sym A "scalar cookie" is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in `gawk''s symbol table every time access is needed. This -was discussed earlier, in *note General Data Types::. +was discussed earlier in *note General Data Types::. - The following functions let you work with scalar cookies. + The following functions let you work with scalar cookies: `awk_bool_t sym_lookup_scalar(awk_scalar_t cookie,' ` awk_valtype_t wanted,' @@ -23955,7 +23979,7 @@ variable based on the result of that evaluation, like so: This code looks (and is) simple and straightforward. So what's the problem? - Consider what happens if `awk'-level code associated with your + Well, consider what happens if `awk'-level code associated with your extension calls the `magic()' function (implemented in C by `do_magic()'), once per record, while processing hundreds of thousands or millions of records. The `MAGIC_VAR' variable is looked up in the @@ -24030,7 +24054,7 @@ variables using `sym_update()' or `sym_update_scalar()', as you like. However, you can understand the point of cached values if you remember that _every_ string value's storage _must_ come from -`gawk_malloc()', `gawk_calloc()' or `gawk_realloc()'. If you have 20 +`gawk_malloc()', `gawk_calloc()', or `gawk_realloc()'. If you have 20 variables, all of which have the same string value, you must create 20 identical copies of the string.(1) @@ -24042,8 +24066,8 @@ follows: `awk_bool_t create_value(awk_value_t *value, awk_value_cookie_t *result);' Create a cached string or numeric value from `value' for efficient later assignment. Only values of type `AWK_NUMBER' and - `AWK_STRING' are allowed. Any other type is rejected. While - `AWK_UNDEFINED' could be allowed, doing so would result in + `AWK_STRING' are allowed. Any other type is rejected. + `AWK_UNDEFINED' could be allowed, but doing so would result in inferior performance. `awk_bool_t release_value(awk_value_cookie_t vc);' @@ -24090,7 +24114,7 @@ of variables: ... } -Using value cookies in this way saves considerable storage, since all of +Using value cookies in this way saves considerable storage, as all of `VAR1' through `VAR100' share the same value. You might be wondering, "Is this sharing problematic? What happens @@ -24138,7 +24162,7 @@ arrays of arrays (*note General Data Types::). ---------- Footnotes ---------- - (1) Okay, the only data structure. + (1) OK, the only data structure. File: gawk.info, Node: Array Data Types, Next: Array Functions, Up: Array Manipulation @@ -24146,7 +24170,7 @@ File: gawk.info, Node: Array Data Types, Next: Array Functions, Up: Array Man 16.4.11.1 Array Data Types .......................... -The data types associated with arrays are listed below. +The data types associated with arrays are as follows: `typedef void *awk_array_t;' If you request the value of an array variable, you get back an @@ -24291,7 +24315,7 @@ File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev: Array 16.4.11.3 Working With All The Elements of an Array ................................................... -To "flatten" an array is create a structure that represents the full +To "flatten" an array is to create a structure that represents the full array in a fashion that makes it easy for C code to traverse the entire array. Test code in `extension/testext.c' does this, and also serves as a nice example showing how to use the APIs. @@ -24437,7 +24461,7 @@ this code) once you have called `release_flattened_array()': goto out; } - Finally, since everything was successful, the function sets the + Finally, because everything was successful, the function sets the return value to success, and returns: make_number(1.0, result); @@ -24472,7 +24496,7 @@ them and manipulate them. There are two important points about creating arrays from extension code: - 1. You must install a new array into `gawk''s symbol table + * You must install a new array into `gawk''s symbol table immediately upon creating it. Once you have done so, you can then populate the array. @@ -24486,7 +24510,7 @@ code: previously existing array using `set_array_element()'. We show example code shortly. - 2. Due to gawk internals, after using `sym_update()' to install an + * Due to `gawk' internals, after using `sym_update()' to install an array into `gawk', you have to retrieve the array cookie from the value passed in to `sym_update()' before doing anything else with it, like so: @@ -24570,7 +24594,7 @@ Note how `a_cookie' is reset from the `array_cookie' field in the } } - Here is sample script that loads the extension and then dumps the + Here is a sample script that loads the extension and then dumps the array: @load "subarray" @@ -24678,8 +24702,7 @@ invoked. The variables are: This variable is true if `gawk' was invoked with `--debug' option. `do_lint' - This variable is true if `gawk' was invoked with `--lint' option - (*note Options::). + This variable is true if `gawk' was invoked with `--lint' option. `do_mpfr' This variable is true if `gawk' was invoked with `--bignum' option. @@ -24709,8 +24732,8 @@ File: gawk.info, Node: Extension API Boilerplate, Prev: Extension API Variable As mentioned earlier (*note Extension Mechanism Outline::), the function definitions as presented are really macros. To use these macros, your extension must provide a small amount of boilerplate code (variables and -functions) towards the top of your source file, using pre-defined names -as described below. The boilerplate needed is also provided in comments +functions) toward the top of your source file, using predefined names +as described here. The boilerplate needed is also provided in comments in the `gawkapi.h' header file: /* Boiler plate code: */ @@ -24784,9 +24807,9 @@ in the `gawkapi.h' header file: This macro expands to a `dl_load()' function that performs all the necessary initializations. - The point of the all the variables and arrays is to let the -`dl_load()' function (from the `dl_load_func()' macro) do all the -standard work. It does the following: + The point of all the variables and arrays is to let the `dl_load()' +function (from the `dl_load_func()' macro) do all the standard work. It +does the following: 1. Check the API versions. If the extension major version does not match `gawk''s, or if the extension minor version is greater than @@ -24820,7 +24843,7 @@ File: gawk.info, Node: Extension Example, Next: Extension Samples, Prev: Find 16.6 Example: Some File Functions ================================= - No matter where you go, there you are. -- Buckaroo Bonzai + No matter where you go, there you are. -- Buckaroo Banzai Two useful functions that are not in `awk' are `chdir()' (so that an `awk' program can change its directory) and `stat()' (so that an `awk' @@ -24976,7 +24999,7 @@ Here is the C code for these extensions.(1) includes the `gawkapi.h' header file which provides the API definitions. Those are followed by the necessary variable declarations to make use of the API macros and boilerplate code (*note Extension API -Boilerplate::). +Boilerplate::): #ifdef HAVE_CONFIG_H #include <config.h> @@ -25013,7 +25036,7 @@ Boilerplate::). implements it is called `do_foo()'. The function should have two arguments: the first is an `int' usually called `nargs', that represents the number of actual arguments for the function. The second -is a pointer to an `awk_value_t', usually named `result'. +is a pointer to an `awk_value_t', usually named `result': /* do_chdir --- provide dynamically loaded chdir() function for gawk */ @@ -25031,11 +25054,11 @@ is a pointer to an `awk_value_t', usually named `result'. "expecting 1")); The `newdir' variable represents the new directory to change to, -retrieved with `get_argument()'. Note that the first argument is -numbered zero. +which is retrieved with `get_argument()'. Note that the first argument +is numbered zero. If the argument is retrieved successfully, the function calls the -`chdir()' system call. If the `chdir()' fails, `ERRNO' is updated. +`chdir()' system call. If the `chdir()' fails, `ERRNO' is updated: if (get_argument(0, AWK_STRING, & newdir)) { ret = chdir(newdir.str_value.str); @@ -25216,7 +25239,7 @@ initialized to point to `lstat()' (instead of `stat()') to get the file information, in case the file is a symbolic link. However, if there were three arguments, `statfunc' is set point to `stat()', instead. - Here is the `do_stat()' function. It starts with variable + Here is the `do_stat()' function, which starts with variable declarations and argument checking: /* do_stat --- provide a stat() function for gawk */ @@ -25322,7 +25345,7 @@ version. File: gawk.info, Node: Using Internal File Ops, Prev: Internal File Ops, Up: Extension Example -16.6.3 Integrating The Extensions +16.6.3 Integrating the Extensions --------------------------------- Now that the code is written, it must be possible to add it at runtime @@ -25334,7 +25357,7 @@ create a GNU/Linux shared library: $ gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g -IIDIR filefuncs.c $ gcc -o filefuncs.so -shared filefuncs.o - Once the library exists, it is loaded by using the `@load' keyword. + Once the library exists, it is loaded by using the `@load' keyword: # file testff.awk @load "filefuncs" @@ -25395,21 +25418,21 @@ directory and run the program: ---------- Footnotes ---------- - (1) In practice, you would probably want to use the GNU -Autotools--Automake, Autoconf, Libtool, and `gettext'--to configure and -build your libraries. Instructions for doing so are beyond the scope of -this Info file. *Note gawkextlib::, for Internet links to the tools. + (1) In practice, you would probably want to use the GNU Autotools +(Automake, Autoconf, Libtool, and `gettext') to configure and build +your libraries. Instructions for doing so are beyond the scope of this +Info file. *Note gawkextlib::, for Internet links to the tools. File: gawk.info, Node: Extension Samples, Next: gawkextlib, Prev: Extension Example, Up: Dynamic Extensions -16.7 The Sample Extensions In The `gawk' Distribution +16.7 The Sample Extensions in the `gawk' Distribution ===================================================== This minor node provides brief overviews of the sample extensions that come in the `gawk' distribution. Some of them are intended for -production use, such the `filefuncs', `readdir' and `inplace' -extensions. Others mainly provide example code that shows how to use +production use (e.g., the `filefuncs', `readdir' and `inplace' +extensions). Others mainly provide example code that shows how to use the extension API. * Menu: @@ -25433,11 +25456,11 @@ the extension API. File: gawk.info, Node: Extension Sample File Functions, Next: Extension Sample Fnmatch, Up: Extension Samples -16.7.1 File Related Functions +16.7.1 File-Related Functions ----------------------------- The `filefuncs' extension provides three different functions, as -follows: The usage is: +follows. The usage is: `@load "filefuncs"' This is how you load the extension. @@ -25445,13 +25468,13 @@ follows: The usage is: `result = chdir("/some/directory")' The `chdir()' function is a direct hook to the `chdir()' system call to change the current directory. It returns zero upon - success or less than zero upon error. In the latter case it + success or less than zero upon error. In the latter case, it updates `ERRNO'. `result = stat("/some/path", statdata' [`, follow']`)' The `stat()' function provides a hook into the `stat()' system call. It returns zero upon success or less than zero upon error. - In the latter case it updates `ERRNO'. + In the latter case, it updates `ERRNO'. By default, it uses the `lstat()' system call. However, if passed a third argument, it uses `stat()' instead. @@ -25494,9 +25517,9 @@ follows: The usage is: `flags = or(FTS_PHYSICAL, ...)' `result = fts(pathlist, flags, filedata)' Walk the file trees provided in `pathlist' and fill in the - `filedata' array as described below. `flags' is the bitwise OR of - several predefined values, also described below. Return zero if - there were no errors, otherwise return -1. + `filedata' array as described next. `flags' is the bitwise OR of + several predefined values, also described in a moment. Return + zero if there were no errors, otherwise return -1. The `fts()' function provides a hook to the C library `fts()' routines for traversing file hierarchies. Instead of returning data @@ -25540,7 +25563,7 @@ requested hierarchies. By default, the C library `fts()' routines do not return entries for `.' (dot) and `..' (dot-dot). This option causes entries for dot-dot to also be included. (The extension - always includes an entry for dot, see below.) + always includes an entry for dot; more on this in a moment.) `FTS_XDEV' During a traversal, do not cross onto a different mounted @@ -25550,7 +25573,7 @@ requested hierarchies. The `filedata' array is first cleared. Then, `fts()' creates an element in `filedata' for every element in `pathlist'. The index is the name of the directory or file given in `pathlist'. The - element for this index is itself an array. There are two cases. + element for this index is itself an array. There are two cases: _The path is a file_ In this case, the array contains two or three elements: @@ -25573,10 +25596,10 @@ requested hierarchies. _The path is a directory_ In this case, the array contains one element for each entry - in the directory. If an entry is a file, that element is as - for files, just described. If the entry is a directory, that - element is (recursively), an array describing the - subdirectory. If `FTS_SEEDOT' was provided in the flags, + in the directory. If an entry is a file, that element is the + same as for files, just described. If the entry is a + directory, that element is (recursively) an array describing + the subdirectory. If `FTS_SEEDOT' was provided in the flags, then there will also be an element named `".."'. This element will be an array containing the data as provided by `stat()'. @@ -25592,8 +25615,8 @@ Otherwise it returns -1. of the C library `fts()' routines, choosing instead to provide an interface that is based on associative arrays, which is more comfortable to use from an `awk' program. This includes the lack - of a comparison function, since `gawk' already provides powerful - array sorting facilities. While an `fts_read()'-like interface + of a comparison function, because `gawk' already provides powerful + array sorting facilities. Although an `fts_read()'-like interface could have been provided, this felt less natural than simply creating a multidimensional array to represent the file hierarchy and its information. @@ -25604,7 +25627,7 @@ the `fts()' extension function. File: gawk.info, Node: Extension Sample Fnmatch, Next: Extension Sample Fork, Prev: Extension Sample File Functions, Up: Extension Samples -16.7.2 Interface To `fnmatch()' +16.7.2 Interface to `fnmatch()' ------------------------------- This extension provides an interface to the C library `fnmatch()' @@ -25615,11 +25638,12 @@ function. The usage is: `result = fnmatch(pattern, string, flags)' The return value is zero on success, `FNM_NOMATCH' if the string - did not match the pattern, or a different non-zero value if an + did not match the pattern, or a different nonzero value if an error occurred. - Besides the `fnmatch()' function, the `fnmatch' extension adds one -constant (`FNM_NOMATCH'), and an array of flag values named `FNM'. + In addition to the `fnmatch()' function, the `fnmatch' extension +adds one constant (`FNM_NOMATCH'), and an array of flag values named +`FNM'. The arguments to `fnmatch()' are: @@ -25633,7 +25657,7 @@ constant (`FNM_NOMATCH'), and an array of flag values named `FNM'. Either zero, or the bitwise OR of one or more of the flags in the `FNM' array. - The flags are follows: + The flags are as follows: Array element Corresponding flag defined by `fnmatch()' -------------------------------------------------------------------------- @@ -25655,10 +25679,10 @@ Array element Corresponding flag defined by `fnmatch()' File: gawk.info, Node: Extension Sample Fork, Next: Extension Sample Inplace, Prev: Extension Sample Fnmatch, Up: Extension Samples -16.7.3 Interface To `fork()', `wait()' and `waitpid()' ------------------------------------------------------- +16.7.3 Interface to `fork()', `wait()', and `waitpid()' +------------------------------------------------------- -The `fork' extension adds three functions, as follows. +The `fork' extension adds three functions, as follows: `@load "fork"' This is how you load the extension. @@ -25741,7 +25765,7 @@ File: gawk.info, Node: Extension Sample Ord, Next: Extension Sample Readdir, -------------------------------------------------------- The `ordchr' extension adds two functions, named `ord()' and `chr()', -as follows. +as follows: `@load "ordchr"' This is how you load the extension. @@ -25794,7 +25818,7 @@ Letter File Type `s' Socket `u' Anything else (unknown) -Table 16.2: File Types Returned By The `readdir' Extension +Table 16.2: File types returned by the `readdir' extension On systems without the file type information, the third field is always `u'. @@ -25819,7 +25843,7 @@ File: gawk.info, Node: Extension Sample Revout, Next: Extension Sample Rev2way ----------------------- The `revoutput' extension adds a simple output wrapper that reverses -the characters in each output line. It's main purpose is to show how to +the characters in each output line. Its main purpose is to show how to write an output wrapper, although it may be mildly amusing for the unwary. Here is an example: @@ -25840,9 +25864,9 @@ File: gawk.info, Node: Extension Sample Rev2way, Next: Extension Sample Read w The `revtwoway' extension adds a simple two-way processor that reverses the characters in each line sent to it for reading back by the `awk' -program. It's main purpose is to show how to write a two-way -processor, although it may also be mildly amusing. The following -example shows how to use it: +program. Its main purpose is to show how to write a two-way processor, +although it may also be mildly amusing. The following example shows +how to use it: @load "revtwoway" @@ -25859,7 +25883,7 @@ example shows how to use it: File: gawk.info, Node: Extension Sample Read write array, Next: Extension Sample Readfile, Prev: Extension Sample Rev2way, Up: Extension Samples -16.7.9 Dumping and Restoring An Array +16.7.9 Dumping and Restoring an Array ------------------------------------- The `rwarray' extension adds two functions, named `writea()' and @@ -25882,15 +25906,15 @@ The `rwarray' extension adds two functions, named `writea()' and The array created by `reada()' is identical to that written by `writea()' in the sense that the contents are the same. However, due to -implementation issues, the array traversal order of the recreated array -is likely to be different from that of the original array. As array -traversal order in `awk' is by default undefined, this is (technically) -not a problem. If you need to guarantee a particular traversal order, -use the array sorting features in `gawk' to do so (*note Array -Sorting::). +implementation issues, the array traversal order of the re-created +array is likely to be different from that of the original array. As +array traversal order in `awk' is by default undefined, this is +(technically) not a problem. If you need to guarantee a particular +traversal order, use the array sorting features in `gawk' to do so +(*note Array Sorting::). The file contains binary data. All integral values are written in -network byte order. However, double precision floating-point values +network byte order. However, double-precision floating-point values are written as native binary data. Thus, arrays containing only string data can theoretically be dumped on systems with one byte order and restored on systems with a different one, but this has not been tried. @@ -25906,7 +25930,7 @@ restored on systems with a different one, but this has not been tried. File: gawk.info, Node: Extension Sample Readfile, Next: Extension Sample Time, Prev: Extension Sample Read write array, Up: Extension Samples -16.7.10 Reading An Entire File +16.7.10 Reading an Entire File ------------------------------ The `readfile' extension adds a single function named `readfile()', and @@ -25950,7 +25974,7 @@ The `time' extension adds two functions, named `gettimeofday()' and `the_time = gettimeofday()' Return the time in seconds that has elapsed since 1970-01-01 UTC - as a floating point value. If the time is unavailable on this + as a floating-point value. If the time is unavailable on this platform, return -1 and set `ERRNO'. The returned time should have sub-second precision, but the actual precision may vary based on the platform. If the standard C `gettimeofday()' system call @@ -25990,19 +26014,21 @@ provides a number of `gawk' extensions, including one for processing XML files. This is the evolution of the original `xgawk' (XML `gawk') project. - As of this writing, there are five extensions: + As of this writing, there are six extensions: - * GD graphics library extension. + * GD graphics library extension - * PDF extension. + * PDF extension - * PostgreSQL extension. + * PostgreSQL extension - * MPFR library extension. This provides access to a number of MPFR - functions which `gawk''s native MPFR support does not. + * MPFR library extension (this provides access to a number of MPFR + functions which `gawk''s native MPFR support does not) + + * Redis extension * XML parser extension, using the Expat - (http://expat.sourceforge.net) XML parsing library. + (http://expat.sourceforge.net) XML parsing library You can check out the code for the `gawkextlib' project using the Git (http://git-scm.com) distributed source code control system. The @@ -26042,8 +26068,8 @@ You may also need to use the `sudo' utility to install both `gawk' and `gawkextlib', depending upon how your system works. If you write an extension that you wish to share with other `gawk' -users, please consider doing so through the `gawkextlib' project. See -the project's web site for more information. +users, consider doing so through the `gawkextlib' project. See the +project's website for more information. File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: gawkextlib, Up: Dynamic Extensions @@ -26052,7 +26078,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga ============ * You can write extensions (sometimes called plug-ins) for `gawk' in - C or C++ using the Application Programming Interface (API) defined + C or C++ using the application programming interface (API) defined by the `gawk' developers. * Extensions must have a license compatible with the GNU General @@ -26078,31 +26104,31 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga * API function pointers are provided for the following kinds of operations: - * Allocating, reallocating, and releasing memory. + * Allocating, reallocating, and releasing memory - * Registration functions. You may register extension functions, + * Registration functions (you may register extension functions, exit callbacks, a version string, input parsers, output - wrappers, and two-way processors. + wrappers, and two-way processors) - * Printing fatal, warning, and "lint" warning messages. + * Printing fatal, warning, and "lint" warning messages - * Updating `ERRNO', or unsetting it. + * Updating `ERRNO', or unsetting it * Accessing parameters, including converting an undefined - parameter into an array. + parameter into an array - * Symbol table access: retrieving a global variable, creating - one, or changing one. + * Symbol table access (retrieving a global variable, creating + one, or changing one) * Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be - a big performance win. + a big performance win - * Manipulating arrays: retrieving, adding, deleting, and + * Manipulating arrays (retrieving, adding, deleting, and modifying elements; getting the count of elements in an array; creating a new array; clearing an array; and flattening an array for easy C style looping over all its indices and - elements. + elements) * The API defines a number of standard data types for representing `awk' values, array elements, and arrays. @@ -26124,8 +26150,8 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga that loaded it. * It is easiest to start a new extension by copying the boilerplate - code described in this major node. Macros in the `gawkapi.h' make - this easier to do. + code described in this major node. Macros in the `gawkapi.h' + header file make this easier to do. * The `gawk' distribution includes a number of small but useful sample extensions. The `gawkextlib' project includes several more, @@ -26161,7 +26187,7 @@ Appendix A The Evolution of the `awk' Language ********************************************** This Info file describes the GNU implementation of `awk', which follows -the POSIX specification. Many long-time `awk' users learned `awk' +the POSIX specification. Many longtime `awk' users learned `awk' programming with the original `awk' implementation in Version 7 Unix. (This implementation was the basis for `awk' in Berkeley Unix, through 4.3-Reno. Subsequent versions of Berkeley Unix, and, for a while, some @@ -26343,7 +26369,7 @@ Brian Kernighan has made his version available via his home page (*note Other Versions::). This minor node describes common extensions that originally appeared -in his version of `awk'. +in his version of `awk': * The `**' and `**=' operators (*note Arithmetic Ops:: and *note Assignment Ops::). @@ -26385,7 +26411,7 @@ the current version of `gawk'. - The `/inet', `/inet4', and `/inet6' special files for TCP/IP networking using `|&' to specify which version of the IP - protocol to use. (*note TCP/IP Networking::). + protocol to use (*note TCP/IP Networking::). * Changes and/or additions to the language: @@ -26411,7 +26437,7 @@ the current version of `gawk'. * New keywords: - - The `BEGINFILE' and `ENDFILE' special patterns. (*note + - The `BEGINFILE' and `ENDFILE' special patterns (*note BEGINFILE/ENDFILE::). - The `switch' statement (*note Switch Statement::). @@ -26436,7 +26462,7 @@ the current version of `gawk'. translations easier (*note Printf Ordering::). - The `split()' function's additional optional fourth argument - which is an array to hold the text of the field separators. + which is an array to hold the text of the field separators (*note String Functions::). * Additional functions only in `gawk': @@ -26909,7 +26935,7 @@ A.7 Common Extensions Summary ============================= The following table summarizes the common extensions supported by -`gawk', Brian Kernighan's `awk', and `mawk', the three most widely-used +`gawk', Brian Kernighan's `awk', and `mawk', the three most widely used freely available versions of `awk' (*note Other Versions::). Feature BWK Awk Mawk GNU Awk Now standard @@ -26927,7 +26953,7 @@ Feature BWK Awk Mawk GNU Awk Now standard `func' keyword X X `BINMODE' variable X X `RS' as regexp X X -Time related functions X X +Time-related functions X X File: gawk.info, Node: Ranges and Locales, Next: Contributors, Prev: Common Extensions, Up: Language History @@ -26945,7 +26971,7 @@ first character in the range and the last character in the range, inclusive. Ordering was based on the numeric value of each character in the machine's native character set. Thus, on ASCII-based systems, `[a-z]' matched all the lowercase letters, and only the lowercase -letters, since the numeric values for the letters from `a' through `z' +letters, as the numeric values for the letters from `a' through `z' were contiguous. (On an EBCDIC system, the range `[a-z]' includes additional, non-alphabetic characters as well.) @@ -26956,9 +26982,9 @@ as working in this fashion, and in particular, would teach that the this was true.(1) The 1992 POSIX standard introduced the idea of locales (*note -Locales::). Since many locales include other letters besides the plain -twenty-six letters of the American English alphabet, the POSIX standard -added character classes (*note Bracket Expressions::) as a way to match +Locales::). Because many locales include other letters besides the +plain 26 letters of the English alphabet, the POSIX standard added +character classes (*note Bracket Expressions::) as a way to match different kinds of characters besides the traditional ones in the ASCII character set. @@ -26973,7 +26999,7 @@ than `B'. In other words, these locales sort characters in dictionary order, and `[a-dx-z]' is typically not equivalent to `[abcdxyz]'; instead it might be equivalent to `[ABCXYabcdxyz]', for example. - This point needs to be emphasized: Much literature teaches that you + This point needs to be emphasized: much literature teaches that you should use `[a-z]' to match a lowercase character. But on systems with non-ASCII locales, this also matches all of the uppercase characters except `A' or `Z'! This was a continuous cause of confusion, even well @@ -26986,9 +27012,9 @@ the intent is to remove trailing uppercase characters: $ echo something1234abc | gawk-3.1.8 '{ sub("[A-Z]*$", ""); print }' -| something1234a -This output is unexpected, since the `bc' at the end of -`something1234abc' should not normally match `[A-Z]*'. This result is -due to the locale setting (and thus you may not see it on your system). +This output is unexpected, as the `bc' at the end of `something1234abc' +should not normally match `[A-Z]*'. This result is due to the locale +setting (and thus you may not see it on your system). Similar considerations apply to other ranges. For example, `["-/]' is perfectly valid in ASCII, but is not valid in many Unicode locales, @@ -27005,7 +27031,7 @@ like "why does `[A-Z]' match lowercase letters?!?" This situation existed for close to 10 years, if not more, and the `gawk' maintainer grew weary of trying to explain that `gawk' was being -nicely standards-compliant, and that the issue was in the user's +nicely standards compliant, and that the issue was in the user's locale. During the development of version 4.0, he modified `gawk' to always treat ranges in the original, pre-POSIX fashion, unless `--posix' was used (*note Options::).(2) @@ -27136,7 +27162,7 @@ Info file, in approximate chronological order: statements. * Patrick T.J. McPhee contributed the code for dynamic loading in - Windows32 environments. (This is no longer supported) + Windows32 environments. (This is no longer supported.) * Anders Wallin helped keep the VMS port going for several years. @@ -27150,8 +27176,8 @@ Info file, in approximate chronological order: - The addition of true arrays of arrays. - - The additional modifications for support of arbitrary - precision arithmetic. + - The additional modifications for support of + arbitrary-precision arithmetic. - The initial text of *note Arbitrary Precision Arithmetic::. @@ -27190,7 +27216,7 @@ A.10 Summary ============ * The `awk' language has evolved over time. The first release was - with V7 Unix circa 1978. In 1987 for System V Release 3.1, major + with V7 Unix circa 1978. In 1987, for System V Release 3.1, major additions, including user-defined functions, were made to the language. Additional changes were made for System V Release 4, in 1989. Since then, further minor changes happen under the auspices @@ -27224,8 +27250,8 @@ Appendix B Installing `gawk' This appendix provides instructions for installing `gawk' on the various platforms that are supported by the developers. The primary developer supports GNU/Linux (and Unix), whereas the other ports are -contributed. *Note Bugs::, for the electronic mail addresses of the -people who maintain the respective ports. +contributed. *Note Bugs::, for the email addresses of the people who +maintain the respective ports. * Menu: @@ -27271,7 +27297,7 @@ There are two ways to get GNU software: wget http://ftp.gnu.org/gnu/gawk/gawk-4.1.2.tar.gz The GNU software archive is mirrored around the world. The -up-to-date list of mirror sites is available from the main FSF web site +up-to-date list of mirror sites is available from the main FSF website (http://www.gnu.org/order/ftp.html). Try to use one of the mirrors; they will be less busy, and you can usually find one closer to your site. @@ -27287,9 +27313,9 @@ compression programs: `gzip', `bzip2', and `xz'. For simplicity, the rest of these instructions assume you are using the one compressed with the GNU Zip program, `gzip'. - Once you have the distribution (for example, `gawk-4.1.2.tar.gz'), -use `gzip' to expand the file and then use `tar' to extract it. You -can use the following pipeline to produce the `gawk' distribution: + Once you have the distribution (e.g., `gawk-4.1.2.tar.gz'), use +`gzip' to expand the file and then use `tar' to extract it. You can +use the following pipeline to produce the `gawk' distribution: gzip -d -c gawk-4.1.2.tar.gz | tar -xvpf - @@ -27367,7 +27393,7 @@ Various `.c', `.y', and `.h' files `doc/awkforai.txt' Pointers to the original draft of a short article describing why - `gawk' is a good language for Artificial Intelligence (AI) + `gawk' is a good language for artificial intelligence (AI) programming. `doc/bc_notes' @@ -27499,7 +27525,7 @@ Various `.c', `.y', and `.h' files File: gawk.info, Node: Unix Installation, Next: Non-Unix Installation, Prev: Gawk Distribution, Up: Installation -B.2 Compiling and Installing `gawk' on Unix-like Systems +B.2 Compiling and Installing `gawk' on Unix-Like Systems ======================================================== Usually, you can compile and install `gawk' by typing only two @@ -27516,7 +27542,7 @@ configure `gawk' for your system yourself. File: gawk.info, Node: Quick Installation, Next: Shell Startup Files, Up: Unix Installation -B.2.1 Compiling `gawk' for Unix-like Systems +B.2.1 Compiling `gawk' for Unix-Like Systems -------------------------------------------- The normal installation steps should work on all modern commercial @@ -27559,8 +27585,7 @@ That's all there is to it! To verify that `gawk' is working properly, run `make check'. All of the tests should succeed. If these steps do not work, or if any of the tests fail, check the files in the `README_d' directory to see if you've found a known problem. If the -failure is not described there, please send in a bug report (*note -Bugs::). +failure is not described there, send in a bug report (*note Bugs::). Of course, once you've built `gawk', it is likely that you will wish to install it. To do so, you need to run the command `make install', @@ -27644,7 +27669,7 @@ command line when compiling `gawk' from scratch, including: for deficient systems. Use the command `./configure --help' to see the full list of options -that `configure' supplies. +supplied by `configure'. File: gawk.info, Node: Configuration Philosophy, Prev: Additional Configuration Options, Up: Unix Installation @@ -27678,15 +27703,15 @@ element in the `stat' structure. In this case, It is possible for your C compiler to lie to `configure'. It may do so by not exiting with an error when a library function is not -available. To get around this, edit the file `custom.h'. Use an +available. To get around this, edit the `custom.h' file. Use an `#ifdef' that is appropriate for your system, and either `#define' any constants that `configure' should have defined but didn't, or `#undef' -any constants that `configure' defined and should not have. `custom.h' -is automatically included by `config.h'. +any constants that `configure' defined and should not have. The +`custom.h' file is automatically included by the `config.h' file. It is also possible that the `configure' program generated by Autoconf will not work on your system in some other fashion. If you do -have a problem, the file `configure.ac' is the input for Autoconf. You +have a problem, the `configure.ac' file is the input for Autoconf. You may be able to change this file and generate a new version of `configure' that works on your system (*note Bugs::, for information on how to report problems in configuring `gawk'). The same mechanism may @@ -27722,8 +27747,8 @@ Microsoft Windows-95/98/ME/NT/2000/XP/Vista/7/8. operating systems) has meant that various "DOS extenders" are often used with programs such as `gawk'. The varying capabilities of Microsoft Windows 3.1 and Windows32 can add to the confusion. For an -overview of the considerations, please refer to `README_d/README.pc' in -the distribution. +overview of the considerations, refer to `README_d/README.pc' in the +distribution. * Menu: @@ -27852,8 +27877,8 @@ other set of (self-consistent) environment variables and compiler flags. ---------- Footnotes ---------- - (1) As of May, 2014, this site is still there, but the author could -not find a package for GNU Make. + (1) As of November 2014, this site is still there, but the author +could not find a package for GNU Make. File: gawk.info, Node: PC Testing, Next: PC Using, Prev: PC Compiling, Up: PC Installation @@ -28006,7 +28031,7 @@ use the `BINMODE' variable. This can cause problems with other Unix-like components that have been ported to MS-Windows that expect `gawk' to do automatic -translation of `"\r\n"', since it won't. +translation of `"\r\n"', because it won't. File: gawk.info, Node: VMS Installation, Prev: PC Installation, Up: Non-Unix Installation @@ -28074,7 +28099,7 @@ B.3.2.2 Compiling `gawk' Dynamic Extensions on VMS .................................................. The extensions that have been ported to VMS can be built using one of -the following commands. +the following commands: $ MMS/DESCRIPTION=[.vms]descrip.mms extensions @@ -28086,7 +28111,7 @@ or: logical name to find the dynamic extensions. Dynamic extensions need to be compiled with the same compiler -options for floating point, pointer size, and symbol name handling as +options for floating-point, pointer size, and symbol name handling as were used to compile `gawk' itself. Alpha and Itanium should use IEEE floating point. The pointer size is 32 bits, and the symbol name handling should be exact case with CRC shortening for symbols longer @@ -28202,12 +28227,11 @@ Note that uppercase and mixed-case text must be quoted. The VMS port of `gawk' includes a `DCL'-style interface in addition to the original shell-style interface (see the help entry for details). One side effect of dual command-line parsing is that if there is only a -single parameter (as in the quoted string program above), the command -becomes ambiguous. To work around this, the normally optional `--' -flag is required to force Unix-style parsing rather than `DCL' parsing. -If any other dash-type options (or multiple parameters such as data -files to process) are present, there is no ambiguity and `--' can be -omitted. +single parameter (as in the quoted string program), the command becomes +ambiguous. To work around this, the normally optional `--' flag is +required to force Unix-style parsing rather than `DCL' parsing. If any +other dash-type options (or multiple parameters such as data files to +process) are present, there is no ambiguity and `--' can be omitted. The `exit' value is a Unix-style value and is encoded into a VMS exit status value when the program exits. @@ -28283,17 +28307,17 @@ File: gawk.info, Node: Bugs, Next: Other Versions, Prev: Non-Unix Installatio B.4 Reporting Problems and Bugs =============================== - There is nothing more dangerous than a bored archeologist. -- The - Hitchhiker's Guide to the Galaxy + There is nothing more dangerous than a bored archaeologist. -- + Douglas Adams, `The Hitchhiker's Guide to the Galaxy' If you have problems with `gawk' or think that you have found a bug, -please report it to the developers; we cannot promise to do anything -but we might well want to fix it. +report it to the developers; we cannot promise to do anything but we +might well want to fix it. - Before reporting a bug, please make sure you have really found a -genuine bug. Carefully reread the documentation and see if it says you -can do what you're trying to do. If it's not clear whether you should -be able to do something or not, report that too; it's a bug in the + Before reporting a bug, make sure you have really found a genuine +bug. Carefully reread the documentation and see if it says you can do +what you're trying to do. If it's not clear whether you should be able +to do something or not, report that too; it's a bug in the documentation! Before reporting a bug or trying to fix it yourself, try to isolate @@ -28304,48 +28328,46 @@ compile `gawk', and the exact results `gawk' gave you. Also say what you expected to occur; this helps us decide whether the problem is really in the documentation. - Please include the version number of `gawk' you are using. You can -get this information with the command `gawk --version'. + Make sure to include the version number of `gawk' you are using. +You can get this information with the command `gawk --version'. Once you have a precise problem description, send email to <bug-gawk@gnu.org>. The `gawk' maintainers subscribe to this address and thus they will receive your bug report. Although you can send mail to the maintainers -directly, the bug reporting address is preferred since the email list +directly, the bug reporting address is preferred because the email list is archived at the GNU Project. _All email must be in English. This is the only language understood in common by all the maintainers._ CAUTION: Do _not_ try to report bugs in `gawk' by posting to the - Usenet/Internet newsgroup `comp.lang.awk'. While the `gawk' - developers do occasionally read this newsgroup, there is no - guarantee that we will see your posting. The steps described - above are the only official recognized way for reporting bugs. - Really. + Usenet/Internet newsgroup `comp.lang.awk'. The `gawk' developers + do occasionally read this newsgroup, but there is no guarantee + that we will see your posting. The steps described here are the + only officially recognized way for reporting bugs. Really. NOTE: Many distributions of GNU/Linux and the various BSD-based operating systems have their own bug reporting systems. If you - report a bug using your distribution's bug reporting system, - _please_ also send a copy to <bug-gawk@gnu.org>. + report a bug using your distribution's bug reporting system, you + should also send a copy to <bug-gawk@gnu.org>. - This is for two reasons. First, while some distributions forward - bug reports "upstream" to the GNU mailing list, many don't, so - there is a good chance that the `gawk' maintainers won't even see - the bug report! Second, mail to the GNU list is archived, and - having everything at the GNU project keeps things self-contained - and not dependant on other organizations. + This is for two reasons. First, although some distributions + forward bug reports "upstream" to the GNU mailing list, many + don't, so there is a good chance that the `gawk' maintainers + won't even see the bug report! Second, mail to the GNU list is + archived, and having everything at the GNU project keeps things + self-contained and not dependant on other organizations. Non-bug suggestions are always welcome as well. If you have questions about things that are unclear in the documentation or are just obscure features, ask on the bug list; we will try to help you out if we can. - If you find bugs in one of the non-Unix ports of `gawk', please send -an electronic mail message to the bug list, with a copy to the person -who maintains that port. They are named in the following list, as well -as in the `README' file in the `gawk' distribution. Information in the -`README' file should be considered authoritative if it conflicts with -this Info file. + If you find bugs in one of the non-Unix ports of `gawk', send an +email to the bug list, with a copy to the person who maintains that +port. They are named in the following list, as well as in the `README' +file in the `gawk' distribution. Information in the `README' file +should be considered authoritative if it conflicts with this Info file. The people maintaining the various `gawk' ports are: @@ -28356,8 +28378,8 @@ OS/2 Andreas Buening, <andreas.buening@nexgo.de>. VMS John Malmberg, <wb8tyw@qsl.net>. z/OS (OS/390) Dave Pitts, <dpitts@cozx.com>. - If your bug is also reproducible under Unix, please send a copy of -your report to the <bug-gawk@gnu.org> email list as well. + If your bug is also reproducible under Unix, send a copy of your +report to the <bug-gawk@gnu.org> email list as well. File: gawk.info, Node: Other Versions, Next: Installation summary, Prev: Bugs, Up: Installation @@ -28375,7 +28397,7 @@ This minor node briefly describes where to get them: Unix `awk' Brian Kernighan, one of the original designers of Unix `awk', has made his implementation of `awk' freely available. You can - retrieve this version via the World Wide Web from his home page + retrieve this version via his home page (http://www.cs.princeton.edu/~bwk). It is available in several archive formats: @@ -28392,10 +28414,10 @@ Unix `awk' git clone git://github.com/onetrueawk/awk bwkawk - The above command creates a copy of the Git - (http://www.git-scm.com) repository in a directory named `bwkawk'. - If you leave that argument off the `git' command line, the - repository copy is created in a directory named `awk'. + This command creates a copy of the Git (http://www.git-scm.com) + repository in a directory named `bwkawk'. If you leave that + argument off the `git' command line, the repository copy is + created in a directory named `awk'. This version requires an ISO C (1990 standard) compiler; the C compiler from GCC (the GNU Compiler Collection) works quite nicely. @@ -28403,6 +28425,10 @@ Unix `awk' *Note Common Extensions::, for a list of extensions in this `awk' that are not in POSIX `awk'. + As a side note, Dan Bornstein has created a Git repository tracking + all the versions of BWK `awk' that he could find. It's available + at `git://github.com/danfuzz/one-true-awk'. + `mawk' Michael Brennan wrote an independent implementation of `awk', called `mawk'. It is available under the GPL (*note Copying::), @@ -28464,8 +28490,8 @@ The OpenSolaris POSIX `awk' Automake) would take more work, and this has not been done, at least to our knowledge. - The source code used to be available from the OpenSolaris web site. - However, that project was ended and the web site shut down. + The source code used to be available from the OpenSolaris website. + However, that project was ended and the website shut down. Fortunately, the Illumos project (http://wiki.illumos.org/display/illumos/illumos+Home) makes this implementation available. You can view the files one at a time @@ -28481,7 +28507,7 @@ The OpenSolaris POSIX `awk' Libmawk This is an embeddable `awk' interpreter derived from `mawk'. For - more information see `http://repo.hu/projects/libmawk/'. + more information, see `http://repo.hu/projects/libmawk/'. `pawk' This is a Python module that claims to bring `awk'-like features @@ -28490,7 +28516,7 @@ Libmawk version of BWK `awk', described earlier.) QSE Awk - This is an embeddable `awk' interpreter. For more information see + This is an embeddable `awk' interpreter. For more information, see `http://code.google.com/p/qse/' and `http://awk.info/?tools/qse'. `QTawk' @@ -28503,9 +28529,10 @@ QSE Awk The project may also be frozen; no new code changes have been made since approximately 2008. -Other Versions - See also the Wikipedia article - (http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations), +Other versions + See also the "Versions and implementations" section of the + Wikipedia article + (http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations) for information on additional versions. @@ -28674,9 +28701,8 @@ possible to include them: document describes how GNU software should be written. If you haven't read it, please do so, preferably _before_ starting to modify `gawk'. (The `GNU Coding Standards' are available from the - GNU Project's web site - (http://www.gnu.org/prep/standards_toc.html). Texinfo, Info, and - DVI versions are also available.) + GNU Project's website (http://www.gnu.org/prep/standards_toc.html). + Texinfo, Info, and DVI versions are also available.) 5. Use the `gawk' coding style. The C code for `gawk' follows the instructions in the `GNU Coding Standards', with minor exceptions. @@ -29528,6 +29554,11 @@ Action pattern matches an input record, `awk' executes the rule's action. Actions are always enclosed in braces. (*Note Action Overview::.) +Ada + A programming language originally defined by the U.S. Department of + Defense for embedded programming. It was designed to enforce good + Software Engineering practices. + Amazing `awk' Assembler Henry Spencer at the University of Toronto wrote a retargetable assembler completely as `sed' and `awk' scripts. It is thousands @@ -29536,11 +29567,6 @@ Amazing `awk' Assembler been better written in another language. You can get it from `http://awk.info/?awk100/aaa'. -Ada - A programming language originally defined by the U.S. Department of - Defense for embedded programming. It was designed to enforce good - Software Engineering practices. - Amazingly Workable Formatter (`awf') Henry Spencer at the University of Toronto wrote a formatter that accepts a large subset of the `nroff -ms' and `nroff -man' @@ -31409,7 +31435,7 @@ Index * * (asterisk), * operator, as regexp operator: Regexp Operators. (line 89) * * (asterisk), * operator, null strings, matching: String Functions. - (line 535) + (line 536) * * (asterisk), ** operator <1>: Precedence. (line 49) * * (asterisk), ** operator: Arithmetic Ops. (line 81) * * (asterisk), **= operator <1>: Precedence. (line 95) @@ -31459,23 +31485,23 @@ Index * --non-decimal-data option: Options. (line 211) * --non-decimal-data option, strtonum() function and: Nondecimal Data. (line 35) -* --optimize option: Options. (line 237) +* --optimize option: Options. (line 236) * --posix option: Options. (line 254) * --posix option, --traditional option and: Options. (line 273) -* --pretty-print option: Options. (line 226) +* --pretty-print option: Options. (line 225) * --profile option <1>: Profiling. (line 12) * --profile option: Options. (line 242) * --re-interval option: Options. (line 279) * --sandbox option: Options. (line 286) * --sandbox option, disabling system() function: I/O Functions. - (line 96) + (line 128) * --sandbox option, input redirection with getline: Getline. (line 19) * --sandbox option, output redirection with print, printf: Redirection. (line 6) * --source option: Options. (line 117) * --traditional option: Options. (line 81) * --traditional option, --posix option and: Options. (line 273) -* --use-lc-numeric option: Options. (line 221) +* --use-lc-numeric option: Options. (line 220) * --version option: Options. (line 300) * --with-whiny-user-strftime configuration option: Additional Configuration Options. (line 35) @@ -31500,10 +31526,10 @@ Index * -L option: Options. (line 295) * -l option: Options. (line 173) * -M option: Options. (line 205) -* -N option: Options. (line 221) +* -N option: Options. (line 220) * -n option: Options. (line 211) -* -O option: Options. (line 237) -* -o option: Options. (line 226) +* -O option: Options. (line 236) +* -o option: Options. (line 225) * -P option: Options. (line 254) * -p option: Options. (line 242) * -r option: Options. (line 279) @@ -31614,7 +31640,7 @@ Index * \ (backslash), in bracket expressions: Bracket Expressions. (line 17) * \ (backslash), in escape sequences: Escape Sequences. (line 6) * \ (backslash), in escape sequences, POSIX and: Escape Sequences. - (line 121) + (line 108) * \ (backslash), in regexp constants: Computed Regexps. (line 29) * \ (backslash), in shell commands: Quoting. (line 48) * \ (backslash), regexp operator: Regexp Operators. (line 18) @@ -31643,17 +31669,17 @@ Index * actions, control statements in: Statements. (line 6) * actions, default: Very Simple. (line 34) * actions, empty: Very Simple. (line 39) -* Ada programming language: Glossary. (line 19) +* Ada programming language: Glossary. (line 11) * adding, features to gawk: Adding Code. (line 6) * adding, fields: Changing Fields. (line 53) -* advanced features, fixed-width data: Constant Size. (line 10) +* advanced features, fixed-width data: Constant Size. (line 6) * advanced features, gawk: Advanced Features. (line 6) * advanced features, network programming: TCP/IP Networking. (line 6) * advanced features, nondecimal input data: Nondecimal Data. (line 6) * advanced features, processes, communicating with: Two-way I/O. (line 6) * advanced features, specifying field content: Splitting By Content. - (line 10) + (line 9) * Aho, Alfred <1>: Contributors. (line 11) * Aho, Alfred: History. (line 17) * alarm clock example program: Alarm Program. (line 11) @@ -31661,7 +31687,7 @@ Index * algorithms: Basic High Level. (line 68) * allocating memory for extensions: Memory Allocation Functions. (line 6) -* amazing awk assembler (aaa): Glossary. (line 11) +* amazing awk assembler (aaa): Glossary. (line 16) * amazingly workable formatter (awf): Glossary. (line 24) * ambiguity, syntactic: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 148) @@ -31683,7 +31709,7 @@ Index (line 6) * arbitrary precision integers: Arbitrary Precision Integers. (line 6) -* archeologists: Bugs. (line 6) +* archaeologists: Bugs. (line 6) * arctangent: Numeric Functions. (line 11) * ARGC/ARGV variables: Auto-set. (line 15) * ARGC/ARGV variables, command-line arguments: Other Arguments. @@ -31705,13 +31731,13 @@ Index (line 6) * array scanning order, controlling: Controlling Scanning. (line 14) -* array, number of elements: String Functions. (line 200) +* array, number of elements: String Functions. (line 201) * arrays: Arrays. (line 6) * arrays of arrays: Arrays of Arrays. (line 6) * arrays, an example of using: Array Example. (line 6) * arrays, and IGNORECASE variable: Array Intro. (line 94) * arrays, as parameters to functions: Pass By Value/Reference. - (line 47) + (line 44) * arrays, associative: Array Intro. (line 50) * arrays, associative, library functions and: Library Names. (line 58) * arrays, deleting entire contents: Delete. (line 39) @@ -31721,7 +31747,7 @@ Index * arrays, elements, deleting: Delete. (line 6) * arrays, elements, order of access by in operator: Scanning an Array. (line 48) -* arrays, elements, retrieving number of: String Functions. (line 41) +* arrays, elements, retrieving number of: String Functions. (line 42) * arrays, for statement and: Scanning an Array. (line 20) * arrays, indexing: Array Intro. (line 50) * arrays, merging into strings: Join Function. (line 6) @@ -31747,12 +31773,12 @@ Index * ASCII: Ordinal Functions. (line 45) * asort <1>: Array Sorting Functions. (line 6) -* asort: String Functions. (line 41) +* asort: String Functions. (line 42) * asort() function (gawk), arrays, sorting: Array Sorting Functions. (line 6) * asorti <1>: Array Sorting Functions. (line 6) -* asorti: String Functions. (line 41) +* asorti: String Functions. (line 42) * asorti() function (gawk), arrays, sorting: Array Sorting Functions. (line 6) * assert() function (C library): Assert Function. (line 6) @@ -31770,7 +31796,7 @@ Index * asterisk (*), * operator, as regexp operator: Regexp Operators. (line 89) * asterisk (*), * operator, null strings, matching: String Functions. - (line 535) + (line 536) * asterisk (*), ** operator <1>: Precedence. (line 49) * asterisk (*), ** operator: Arithmetic Ops. (line 81) * asterisk (*), **= operator <1>: Precedence. (line 95) @@ -31831,7 +31857,7 @@ Index * awk, versions of, See Also Brian Kernighan's awk <1>: Other Versions. (line 13) * awk, versions of, See Also Brian Kernighan's awk: BTL. (line 6) -* awka compiler for awk: Other Versions. (line 64) +* awka compiler for awk: Other Versions. (line 68) * AWKLIBPATH environment variable: AWKLIBPATH Variable. (line 6) * AWKPATH environment variable <1>: PC Using. (line 10) * AWKPATH environment variable: AWKPATH Variable. (line 6) @@ -31883,12 +31909,12 @@ Index * backslash (\), in bracket expressions: Bracket Expressions. (line 17) * backslash (\), in escape sequences: Escape Sequences. (line 6) * backslash (\), in escape sequences, POSIX and: Escape Sequences. - (line 121) + (line 108) * backslash (\), in regexp constants: Computed Regexps. (line 29) * backslash (\), in shell commands: Quoting. (line 48) * backslash (\), regexp operator: Regexp Operators. (line 18) * backtrace debugger command: Execution Stack. (line 13) -* Beebe, Nelson H.F. <1>: Other Versions. (line 78) +* Beebe, Nelson H.F. <1>: Other Versions. (line 82) * Beebe, Nelson H.F.: Acknowledgments. (line 60) * BEGIN pattern <1>: Using BEGIN/END. (line 6) * BEGIN pattern <2>: BEGIN/END. (line 6) @@ -31896,7 +31922,7 @@ Index * BEGIN pattern, and profiling: Profiling. (line 62) * BEGIN pattern, assert() user-defined function and: Assert Function. (line 83) -* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 70) +* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 69) * BEGIN pattern, exit statement and: Exit Statement. (line 12) * BEGIN pattern, getline and: Getline Notes. (line 19) * BEGIN pattern, headings, adding: Print Examples. (line 43) @@ -31905,7 +31931,7 @@ Index * BEGIN pattern, next/nextfile statements and: I/O And BEGIN/END. (line 37) * BEGIN pattern, OFS/ORS variables, assigning values to: Output Separators. - (line 20) + (line 21) * BEGIN pattern, operators and: Using BEGIN/END. (line 17) * BEGIN pattern, print statement and: I/O And BEGIN/END. (line 16) * BEGIN pattern, pwcat program: Passwd Functions. (line 143) @@ -31913,7 +31939,7 @@ Index * BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n. (line 60) * BEGINFILE pattern: BEGINFILE/ENDFILE. (line 6) * BEGINFILE pattern, Boolean patterns and: Expression Patterns. - (line 70) + (line 69) * beginfile() user-defined function: Filetrans Function. (line 61) * Bentley, Jon: Glossary. (line 143) * Benzinger, Michael: Contributors. (line 97) @@ -31939,7 +31965,7 @@ Index * body, in actions: Statements. (line 10) * body, in loops: While Statement. (line 14) * Boolean expressions: Boolean Ops. (line 6) -* Boolean expressions, as patterns: Expression Patterns. (line 39) +* Boolean expressions, as patterns: Expression Patterns. (line 38) * Boolean operators, See Boolean expressions: Boolean Ops. (line 6) * Bourne shell, quoting rules for: Quoting. (line 18) * braces ({}): Profiling. (line 142) @@ -31974,10 +32000,10 @@ Index * Brennan, Michael <3>: Delete. (line 56) * Brennan, Michael <4>: Acknowledgments. (line 78) * Brennan, Michael <5>: Foreword4. (line 30) -* Brennan, Michael: Foreword3. (line 83) +* Brennan, Michael: Foreword3. (line 84) * Brian Kernighan's awk <1>: I/O Functions. (line 43) * Brian Kernighan's awk <2>: Gory Details. (line 19) -* Brian Kernighan's awk <3>: String Functions. (line 491) +* Brian Kernighan's awk <3>: String Functions. (line 492) * Brian Kernighan's awk <4>: Delete. (line 51) * Brian Kernighan's awk <5>: Nextfile Statement. (line 47) * Brian Kernighan's awk <6>: Continue Statement. (line 44) @@ -31988,8 +32014,8 @@ Index * Brian Kernighan's awk <11>: Regexp Field Splitting. (line 67) * Brian Kernighan's awk <12>: GNU Regexp Operators. - (line 83) -* Brian Kernighan's awk <13>: Escape Sequences. (line 125) + (line 82) +* Brian Kernighan's awk <13>: Escape Sequences. (line 112) * Brian Kernighan's awk: When. (line 21) * Brian Kernighan's awk, extensions: BTL. (line 6) * Brian Kernighan's awk, source code: Other Versions. (line 13) @@ -31999,12 +32025,12 @@ Index * Brown, Martin: Contributors. (line 82) * BSD-based operating systems: Glossary. (line 611) * bt debugger command (alias for backtrace): Execution Stack. (line 13) -* Buening, Andreas <1>: Bugs. (line 72) +* Buening, Andreas <1>: Bugs. (line 70) * Buening, Andreas <2>: Contributors. (line 92) * Buening, Andreas: Acknowledgments. (line 60) * buffering, input/output <1>: Two-way I/O. (line 52) -* buffering, input/output: I/O Functions. (line 139) -* buffering, interactive vs. noninteractive: I/O Functions. (line 108) +* buffering, input/output: I/O Functions. (line 140) +* buffering, interactive vs. noninteractive: I/O Functions. (line 75) * buffers, flushing: I/O Functions. (line 32) * buffers, operators for: GNU Regexp Operators. (line 48) @@ -32012,12 +32038,12 @@ Index * bug-gawk@gnu.org bug reporting address: Bugs. (line 30) * built-in functions: Functions. (line 6) * built-in functions, evaluation order: Calling Built-in. (line 30) -* Busybox Awk: Other Versions. (line 88) +* Busybox Awk: Other Versions. (line 92) * c.e., See common extensions: Conventions. (line 51) * call by reference: Pass By Value/Reference. - (line 47) + (line 44) * call by value: Pass By Value/Reference. - (line 18) + (line 15) * call stack, display in debugger: Execution Stack. (line 13) * caret (^), ^ operator: Precedence. (line 49) * caret (^), ^= operator <1>: Precedence. (line 95) @@ -32030,7 +32056,7 @@ Index * case sensitivity, and regexps: User-modified. (line 76) * case sensitivity, and string comparisons: User-modified. (line 76) * case sensitivity, array indices and: Array Intro. (line 94) -* case sensitivity, converting case: String Functions. (line 521) +* case sensitivity, converting case: String Functions. (line 522) * case sensitivity, example programs: Library Functions. (line 53) * case sensitivity, gawk: Case-sensitivity. (line 26) * case sensitivity, regexps and: Case-sensitivity. (line 6) @@ -32066,7 +32092,7 @@ Index * close() function, portability: Close Files And Pipes. (line 81) * close() function, return value: Close Files And Pipes. - (line 132) + (line 133) * close() function, two-way pipes and: Two-way I/O. (line 59) * Close, Diane <1>: Contributors. (line 20) * Close, Diane: Manual History. (line 34) @@ -32110,7 +32136,7 @@ Index * common extensions, delete to delete entire arrays: Delete. (line 39) * common extensions, func keyword: Definition Syntax. (line 93) * common extensions, length() applied to an array: String Functions. - (line 200) + (line 201) * common extensions, RS as a regexp: gawk split records. (line 6) * common extensions, single character fields: Single Character Fields. (line 6) @@ -32159,9 +32185,9 @@ Index * control statements: Statements. (line 6) * controlling array scanning order: Controlling Scanning. (line 14) -* convert string to lower case: String Functions. (line 522) -* convert string to number: String Functions. (line 389) -* convert string to upper case: String Functions. (line 528) +* convert string to lower case: String Functions. (line 523) +* convert string to number: String Functions. (line 390) +* convert string to upper case: String Functions. (line 529) * converting integer array subscripts: Numeric Array Subscripts. (line 31) * converting, dates to timestamps: Time Functions. (line 76) @@ -32208,7 +32234,7 @@ Index (line 43) * dark corner, break statement: Break Statement. (line 51) * dark corner, close() function: Close Files And Pipes. - (line 132) + (line 133) * dark corner, command-line arguments: Assignment Options. (line 43) * dark corner, continue statement: Continue Statement. (line 44) * dark corner, CONVFMT variable: Strings And Numbers. (line 40) @@ -32216,34 +32242,33 @@ Index * dark corner, escape sequences, for metacharacters: Escape Sequences. (line 143) * dark corner, exit statement: Exit Statement. (line 30) -* dark corner, field separators: Field Splitting Summary. - (line 46) -* dark corner, FILENAME variable <1>: Auto-set. (line 98) +* dark corner, field separators: Full Line Fields. (line 22) +* dark corner, FILENAME variable <1>: Auto-set. (line 104) * dark corner, FILENAME variable: Getline Notes. (line 19) -* dark corner, FNR/NR variables: Auto-set. (line 321) +* dark corner, FNR/NR variables: Auto-set. (line 328) * dark corner, format-control characters: Control Letters. (line 18) * dark corner, FS as null string: Single Character Fields. (line 20) * dark corner, input files: awk split records. (line 111) * dark corner, invoking awk: Command Line. (line 16) -* dark corner, length() function: String Functions. (line 186) +* dark corner, length() function: String Functions. (line 187) * dark corner, locale's decimal point character: Locale influences conversions. (line 17) * dark corner, multiline records: Multiple Line. (line 35) * dark corner, NF variable, decrementing: Changing Fields. (line 107) * dark corner, OFMT variable: OFMT. (line 27) * dark corner, regexp as second argument to index(): String Functions. - (line 164) + (line 165) * dark corner, regexp constants: Using Constant Regexps. (line 6) * dark corner, regexp constants, /= operator and: Assignment Ops. (line 148) * dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps. (line 43) -* dark corner, split() function: String Functions. (line 360) +* dark corner, split() function: String Functions. (line 361) * dark corner, strings, storing: gawk split records. (line 83) * dark corner, value of ARGV[0]: Auto-set. (line 39) -* data, fixed-width: Constant Size. (line 10) +* data, fixed-width: Constant Size. (line 6) * data-driven languages: Basic High Level. (line 85) * database, group, reading: Group Functions. (line 6) * database, users, reading: Passwd Functions. (line 6) @@ -32373,7 +32398,7 @@ Index * decimal point character, locale specific: Options. (line 270) * decrement operators: Increment Ops. (line 35) * default keyword: Switch Statement. (line 6) -* Deifik, Scott <1>: Bugs. (line 72) +* Deifik, Scott <1>: Bugs. (line 70) * Deifik, Scott <2>: Contributors. (line 53) * Deifik, Scott: Acknowledgments. (line 60) * delete ARRAY: Delete. (line 39) @@ -32387,7 +32412,7 @@ Index * deleting entire arrays: Delete. (line 39) * Demaille, Akim: Acknowledgments. (line 60) * describe call stack frame, in debugger: Debugger Info. (line 27) -* differences between gawk and awk: String Functions. (line 200) +* differences between gawk and awk: String Functions. (line 201) * differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV. (line 90) * differences in awk and gawk, ARGIND variable: Auto-set. (line 44) @@ -32409,12 +32434,12 @@ Index (line 81) * differences in awk and gawk, command-line directories: Command-line directories. (line 6) -* differences in awk and gawk, ERRNO variable: Auto-set. (line 82) +* differences in awk and gawk, ERRNO variable: Auto-set. (line 88) * differences in awk and gawk, error messages: Special FD. (line 19) * differences in awk and gawk, FIELDWIDTHS variable: User-modified. (line 37) * differences in awk and gawk, FPAT variable: User-modified. (line 43) -* differences in awk and gawk, FUNCTAB variable: Auto-set. (line 123) +* differences in awk and gawk, FUNCTAB variable: Auto-set. (line 130) * differences in awk and gawk, function arguments (gawk): Calling Built-in. (line 16) * differences in awk and gawk, getline command: Getline. (line 19) @@ -32434,10 +32459,10 @@ Index (line 34) * differences in awk and gawk, LINT variable: User-modified. (line 88) * differences in awk and gawk, match() function: String Functions. - (line 262) + (line 263) * differences in awk and gawk, print/printf statements: Format Modifiers. (line 13) -* differences in awk and gawk, PROCINFO array: Auto-set. (line 137) +* differences in awk and gawk, PROCINFO array: Auto-set. (line 144) * differences in awk and gawk, read timeouts: Read Timeout. (line 6) * differences in awk and gawk, record separators: awk split records. (line 125) @@ -32447,15 +32472,15 @@ Index (line 26) * differences in awk and gawk, RS/RT variables: gawk split records. (line 58) -* differences in awk and gawk, RT variable: Auto-set. (line 272) +* differences in awk and gawk, RT variable: Auto-set. (line 279) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. - (line 348) + (line 349) * differences in awk and gawk, strings: Scalar Constants. (line 20) * differences in awk and gawk, strings, storing: gawk split records. (line 77) -* differences in awk and gawk, SYMTAB variable: Auto-set. (line 276) +* differences in awk and gawk, SYMTAB variable: Auto-set. (line 283) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. (line 151) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. @@ -32496,8 +32521,8 @@ Index * dynamically loaded extensions: Dynamic Extensions. (line 6) * e debugger command (alias for enable): Breakpoint Control. (line 73) * EBCDIC: Ordinal Functions. (line 45) -* effective group ID of gawk user: Auto-set. (line 142) -* effective user ID of gawk user: Auto-set. (line 146) +* effective group ID of gawk user: Auto-set. (line 149) +* effective user ID of gawk user: Auto-set. (line 153) * egrep utility <1>: Egrep Program. (line 6) * egrep utility: Bracket Expressions. (line 26) * egrep.awk program: Egrep Program. (line 54) @@ -32525,7 +32550,7 @@ Index * END pattern, and profiling: Profiling. (line 62) * END pattern, assert() user-defined function and: Assert Function. (line 75) -* END pattern, Boolean patterns and: Expression Patterns. (line 70) +* END pattern, Boolean patterns and: Expression Patterns. (line 69) * END pattern, exit statement and: Exit Statement. (line 12) * END pattern, next/nextfile statements and <1>: Next Statement. (line 44) @@ -32534,7 +32559,7 @@ Index * END pattern, operators and: Using BEGIN/END. (line 17) * END pattern, print statement and: I/O And BEGIN/END. (line 16) * ENDFILE pattern: BEGINFILE/ENDFILE. (line 6) -* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 70) +* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 69) * endfile() user-defined function: Filetrans Function. (line 61) * endgrent() function (C library): Group Functions. (line 211) * endgrent() user-defined function: Group Functions. (line 214) @@ -32552,13 +32577,13 @@ Index (line 11) * EREs (Extended Regular Expressions): Bracket Expressions. (line 26) * ERRNO variable <1>: TCP/IP Networking. (line 54) -* ERRNO variable: Auto-set. (line 82) +* ERRNO variable: Auto-set. (line 88) * ERRNO variable, with BEGINFILE pattern: BEGINFILE/ENDFILE. (line 26) * ERRNO variable, with close() function: Close Files And Pipes. - (line 140) + (line 141) * ERRNO variable, with getline command: Getline. (line 19) * error handling: Special FD. (line 19) -* error handling, ERRNO variable and: Auto-set. (line 82) +* error handling, ERRNO variable and: Auto-set. (line 88) * error output: Special FD. (line 6) * escape processing, gsub()/gensub()/sub() functions: Gory Details. (line 6) @@ -32588,12 +32613,12 @@ Index * exclamation point (!), !~ operator: Regexp Usage. (line 19) * exit statement: Exit Statement. (line 6) * exit status, of gawk: Exit Status. (line 6) -* exit status, of VMS: VMS Running. (line 29) +* exit status, of VMS: VMS Running. (line 28) * exit the debugger: Miscellaneous Debugger Commands. (line 99) * exp: Numeric Functions. (line 33) * expand utility: Very Simple. (line 72) -* Expat XML parser library: gawkextlib. (line 31) +* Expat XML parser library: gawkextlib. (line 33) * exponent: Numeric Functions. (line 33) * expressions: Expressions. (line 6) * expressions, as patterns: Expression Patterns. (line 6) @@ -32612,7 +32637,7 @@ Index (line 6) * extension API version: Extension Versioning. (line 6) -* extension API, version number: Auto-set. (line 239) +* extension API, version number: Auto-set. (line 246) * extension example: Extension Example. (line 6) * extension registration: Registration Functions. (line 6) @@ -32633,7 +32658,7 @@ Index * extensions, common, fflush() function: I/O Functions. (line 43) * extensions, common, func keyword: Definition Syntax. (line 93) * extensions, common, length() applied to an array: String Functions. - (line 200) + (line 201) * extensions, common, RS as a regexp: gawk split records. (line 6) * extensions, common, single character fields: Single Character Fields. (line 6) @@ -32661,8 +32686,7 @@ Index * field separator, in multiline records: Multiple Line. (line 41) * field separator, on command line: Command Line Field Separator. (line 6) -* field separator, POSIX and: Field Splitting Summary. - (line 40) +* field separator, POSIX and: Full Line Fields. (line 16) * field separators <1>: User-modified. (line 50) * field separators: Field Separators. (line 15) * field separators, choice of: Field Separators. (line 51) @@ -32688,13 +32712,13 @@ Index * fields, single-character: Single Character Fields. (line 6) * FIELDWIDTHS variable <1>: User-modified. (line 37) -* FIELDWIDTHS variable: Constant Size. (line 23) +* FIELDWIDTHS variable: Constant Size. (line 22) * file descriptors: Special FD. (line 6) * file inclusion, @include directive: Include Files. (line 8) * file names, distinguishing: Auto-set. (line 56) * file names, in compatibility mode: Special Caveats. (line 9) * file names, standard streams in gawk: Special FD. (line 48) -* FILENAME variable <1>: Auto-set. (line 98) +* FILENAME variable <1>: Auto-set. (line 104) * FILENAME variable: Reading Files. (line 6) * FILENAME variable, getline, setting with: Getline Notes. (line 19) * filenames, assignments as: Ignoring Assigns. (line 6) @@ -32748,23 +32772,23 @@ Index * files, source, search path for: Programs Exercises. (line 70) * files, splitting: Split Program. (line 6) * files, Texinfo, extracting programs from: Extract Program. (line 6) -* find substring in string: String Functions. (line 155) +* find substring in string: String Functions. (line 156) * finding extensions: Finding Extensions. (line 6) * finish debugger command: Debugger Execution Control. (line 39) * Fish, Fred: Contributors. (line 50) -* fixed-width data: Constant Size. (line 10) +* fixed-width data: Constant Size. (line 6) * flag variables <1>: Tee Program. (line 20) * flag variables: Boolean Ops. (line 69) * floating-point, numbers, arbitrary precision: Arbitrary Precision Arithmetic. (line 6) -* floating-point, VAX/VMS: VMS Running. (line 51) +* floating-point, VAX/VMS: VMS Running. (line 50) * flush buffered output: I/O Functions. (line 28) * fnmatch() extension function: Extension Sample Fnmatch. (line 12) -* FNR variable <1>: Auto-set. (line 107) +* FNR variable <1>: Auto-set. (line 114) * FNR variable: Records. (line 6) -* FNR variable, changing: Auto-set. (line 321) +* FNR variable, changing: Auto-set. (line 328) * for statement: For Statement. (line 6) * for statement, looping over arrays: Scanning an Array. (line 20) * fork() extension function: Extension Sample Fork. @@ -32778,7 +32802,7 @@ Index * format time string: Time Functions. (line 48) * formats, numeric output: OFMT. (line 6) * formatting output: Printf. (line 6) -* formatting strings: String Functions. (line 382) +* formatting strings: String Functions. (line 383) * forward slash (/) to enclose regular expressions: Regexp. (line 10) * forward slash (/), / operator: Precedence. (line 55) * forward slash (/), /= operator <1>: Precedence. (line 95) @@ -32788,7 +32812,7 @@ Index * forward slash (/), patterns and: Expression Patterns. (line 24) * FPAT variable <1>: User-modified. (line 43) * FPAT variable: Splitting By Content. - (line 27) + (line 25) * frame debugger command: Execution Stack. (line 27) * Free Documentation License (FDL): GNU Free Documentation License. (line 7) @@ -32814,14 +32838,14 @@ Index * FSF (Free Software Foundation): Manual History. (line 6) * fts() extension function: Extension Sample File Functions. (line 61) -* FUNCTAB array: Auto-set. (line 123) +* FUNCTAB array: Auto-set. (line 130) * function calls: Function Calls. (line 6) * function calls, indirect: Indirect Calls. (line 6) * function calls, indirect, @-notation for: Indirect Calls. (line 47) * function definition example: Function Example. (line 6) * function pointers: Indirect Calls. (line 6) * functions, arrays as parameters to: Pass By Value/Reference. - (line 47) + (line 44) * functions, built-in <1>: Functions. (line 6) * functions, built-in: Function Calls. (line 10) * functions, built-in, evaluation order: Calling Built-in. (line 30) @@ -32852,7 +32876,7 @@ Index * functions, recursive: Definition Syntax. (line 83) * functions, string-translation: I18N Functions. (line 6) * functions, undefined: Pass By Value/Reference. - (line 71) + (line 68) * functions, user-defined: User-defined. (line 6) * functions, user-defined, calling: Function Caveats. (line 6) * functions, user-defined, counts, in a profile: Profiling. (line 137) @@ -32864,14 +32888,14 @@ Index * G-d: Acknowledgments. (line 94) * Garfinkle, Scott: Contributors. (line 34) * gawk program, dynamic profiling: Profiling. (line 178) -* gawk version: Auto-set. (line 214) +* gawk version: Auto-set. (line 221) * gawk, ARGIND variable in: Other Arguments. (line 15) * gawk, awk and <1>: This Manual. (line 14) * gawk, awk and: Preface. (line 21) * gawk, bitwise operations in: Bitwise Functions. (line 40) * gawk, break statement in: Break Statement. (line 51) * gawk, character classes and: Bracket Expressions. (line 100) -* gawk, coding style in: Adding Code. (line 39) +* gawk, coding style in: Adding Code. (line 38) * gawk, command-line options, and regular expressions: GNU Regexp Operators. (line 70) * gawk, configuring: Configuration Philosophy. @@ -32882,29 +32906,29 @@ Index * gawk, distribution: Distribution contents. (line 6) * gawk, ERRNO variable in <1>: TCP/IP Networking. (line 54) -* gawk, ERRNO variable in <2>: Auto-set. (line 82) +* gawk, ERRNO variable in <2>: Auto-set. (line 88) * gawk, ERRNO variable in <3>: BEGINFILE/ENDFILE. (line 26) * gawk, ERRNO variable in <4>: Close Files And Pipes. - (line 140) + (line 141) * gawk, ERRNO variable in: Getline. (line 19) -* gawk, escape sequences: Escape Sequences. (line 133) +* gawk, escape sequences: Escape Sequences. (line 120) * gawk, extensions, disabling: Options. (line 254) * gawk, features, adding: Adding Code. (line 6) * gawk, features, advanced: Advanced Features. (line 6) * gawk, field separators and: User-modified. (line 71) * gawk, FIELDWIDTHS variable in <1>: User-modified. (line 37) -* gawk, FIELDWIDTHS variable in: Constant Size. (line 23) +* gawk, FIELDWIDTHS variable in: Constant Size. (line 22) * gawk, file names in: Special Files. (line 6) * gawk, format-control characters: Control Letters. (line 18) * gawk, FPAT variable in <1>: User-modified. (line 43) * gawk, FPAT variable in: Splitting By Content. - (line 27) -* gawk, FUNCTAB array in: Auto-set. (line 123) + (line 25) +* gawk, FUNCTAB array in: Auto-set. (line 130) * gawk, function arguments and: Calling Built-in. (line 16) * gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42) * gawk, IGNORECASE variable in <1>: Array Sorting Functions. (line 83) -* gawk, IGNORECASE variable in <2>: String Functions. (line 57) +* gawk, IGNORECASE variable in <2>: String Functions. (line 58) * gawk, IGNORECASE variable in <3>: Array Intro. (line 94) * gawk, IGNORECASE variable in <4>: User-modified. (line 76) * gawk, IGNORECASE variable in: Case-sensitivity. (line 26) @@ -32931,7 +32955,7 @@ Index * gawk, predefined variables and: Built-in Variables. (line 14) * gawk, PROCINFO array in <1>: Two-way I/O. (line 99) * gawk, PROCINFO array in <2>: Time Functions. (line 47) -* gawk, PROCINFO array in: Auto-set. (line 137) +* gawk, PROCINFO array in: Auto-set. (line 144) * gawk, regexp constants and: Using Constant Regexps. (line 28) * gawk, regular expressions, case sensitivity: Case-sensitivity. @@ -32939,14 +32963,14 @@ Index * gawk, regular expressions, operators: GNU Regexp Operators. (line 6) * gawk, regular expressions, precedence: Regexp Operators. (line 161) -* gawk, RT variable in <1>: Auto-set. (line 272) +* gawk, RT variable in <1>: Auto-set. (line 279) * gawk, RT variable in <2>: Multiple Line. (line 129) * gawk, RT variable in: awk split records. (line 125) * gawk, See Also awk: Preface. (line 34) * gawk, source code, obtaining: Getting. (line 6) -* gawk, splitting fields and: Constant Size. (line 88) +* gawk, splitting fields and: Constant Size. (line 87) * gawk, string-translation functions: I18N Functions. (line 6) -* gawk, SYMTAB array in: Auto-set. (line 276) +* gawk, SYMTAB array in: Auto-set. (line 283) * gawk, TEXTDOMAIN variable in: User-modified. (line 151) * gawk, timestamps: Time Functions. (line 6) * gawk, uses for: Preface. (line 34) @@ -32965,7 +32989,7 @@ Index * General Public License (GPL): Glossary. (line 305) * General Public License, See GPL: Manual History. (line 11) * generate time values: Time Functions. (line 25) -* gensub <1>: String Functions. (line 89) +* gensub <1>: String Functions. (line 90) * gensub: Using Constant Regexps. (line 43) * gensub() function (gawk), escape processing: Gory Details. (line 6) @@ -33010,11 +33034,11 @@ Index * gettext() function (C library): Explaining gettext. (line 63) * gettimeofday() extension function: Extension Sample Time. (line 12) -* git utility <1>: Adding Code. (line 112) +* git utility <1>: Adding Code. (line 111) * git utility <2>: Accessing The Source. (line 10) * git utility <3>: Other Versions. (line 29) -* git utility: gawkextlib. (line 25) +* git utility: gawkextlib. (line 27) * Git, use of for gawk source code: Derived Files. (line 6) * GNITS mailing list: Acknowledgments. (line 52) * GNU awk, See gawk: Preface. (line 51) @@ -33038,12 +33062,12 @@ Index * Grigera, Juan: Contributors. (line 57) * group database, reading: Group Functions. (line 6) * group file: Group Functions. (line 6) -* group ID of gawk user: Auto-set. (line 187) +* group ID of gawk user: Auto-set. (line 194) * groups, information about: Group Functions. (line 6) -* gsub <1>: String Functions. (line 139) +* gsub <1>: String Functions. (line 140) * gsub: Using Constant Regexps. (line 43) -* gsub() function, arguments of: String Functions. (line 461) +* gsub() function, arguments of: String Functions. (line 462) * gsub() function, escape processing: Gory Details. (line 6) * h debugger command (alias for help): Miscellaneous Debugger Commands. (line 66) @@ -33085,8 +33109,8 @@ Index (line 53) * IGNORECASE variable, with ~ and !~ operators: Case-sensitivity. (line 26) -* Illumos: Other Versions. (line 105) -* Illumos, POSIX-compliant awk: Other Versions. (line 105) +* Illumos: Other Versions. (line 109) +* Illumos, POSIX-compliant awk: Other Versions. (line 109) * implementation issues, gawk: Notes. (line 6) * implementation issues, gawk, debugging: Compatibility Mode. (line 6) * implementation issues, gawk, limits <1>: Redirection. (line 129) @@ -33103,7 +33127,7 @@ Index * in operator, use in loops: Scanning an Array. (line 17) * including files, @include directive: Include Files. (line 8) * increment operators: Increment Ops. (line 6) -* index: String Functions. (line 155) +* index: String Functions. (line 156) * indexing arrays: Array Intro. (line 50) * indirect function calls: Indirect Calls. (line 6) * indirect function calls, @-notation: Indirect Calls. (line 47) @@ -33122,7 +33146,7 @@ Index * input files, running awk without: Read Terminal. (line 6) * input files, variable assignments and: Other Arguments. (line 26) * input pipeline: Getline/Pipe. (line 9) -* input record, length of: String Functions. (line 177) +* input record, length of: String Functions. (line 178) * input redirection: Getline/File. (line 6) * input, data, nondecimal: Nondecimal Data. (line 6) * input, explicit: Getline. (line 6) @@ -33146,7 +33170,7 @@ Index * integers, arbitrary precision: Arbitrary Precision Integers. (line 6) * integers, unsigned: Computer Arithmetic. (line 41) -* interacting with other programs: I/O Functions. (line 74) +* interacting with other programs: I/O Functions. (line 106) * internationalization <1>: I18N and L10N. (line 6) * internationalization: I18N Functions. (line 6) * internationalization, localization <1>: Internationalization. @@ -33167,7 +33191,7 @@ Index * interpreted programs: Basic High Level. (line 15) * interval expressions, regexp operator: Regexp Operators. (line 116) * inventory-shipped file: Sample Data Files. (line 32) -* invoke shell command: I/O Functions. (line 74) +* invoke shell command: I/O Functions. (line 106) * isarray: Type Functions. (line 11) * ISO: Glossary. (line 367) * ISO 8859-1: Glossary. (line 133) @@ -33175,9 +33199,9 @@ Index * Jacobs, Andrew: Passwd Functions. (line 90) * Jaegermann, Michal <1>: Contributors. (line 45) * Jaegermann, Michal: Acknowledgments. (line 60) -* Java implementation of awk: Other Versions. (line 113) +* Java implementation of awk: Other Versions. (line 117) * Java programming language: Glossary. (line 379) -* jawk: Other Versions. (line 113) +* jawk: Other Versions. (line 117) * Jedi knights: Undocumented. (line 6) * Johansen, Chris: Signature Program. (line 25) * join() user-defined function: Join Function. (line 18) @@ -33223,12 +33247,12 @@ Index * left shift: Bitwise Functions. (line 47) * left shift, bitwise: Bitwise Functions. (line 32) * leftmost longest match: Multiple Line. (line 26) -* length: String Functions. (line 170) -* length of input record: String Functions. (line 177) -* length of string: String Functions. (line 170) +* length: String Functions. (line 171) +* length of input record: String Functions. (line 178) +* length of string: String Functions. (line 171) * Lesser General Public License (LGPL): Glossary. (line 396) * LGPL (Lesser General Public License): Glossary. (line 396) -* libmawk: Other Versions. (line 121) +* libmawk: Other Versions. (line 125) * libraries of awk functions: Library Functions. (line 6) * libraries of awk functions, assertions: Assert Function. (line 6) * libraries of awk functions, associative arrays and: Library Names. @@ -33270,7 +33294,7 @@ Index * lint checking, POSIXLY_CORRECT environment variable: Options. (line 339) * lint checking, undefined functions: Pass By Value/Reference. - (line 88) + (line 85) * LINT variable: User-modified. (line 88) * Linux <1>: Glossary. (line 611) * Linux <2>: I18N Example. (line 55) @@ -33289,9 +33313,9 @@ Index * localization: I18N and L10N. (line 6) * localization, See internationalization, localization: I18N and L10N. (line 6) -* log: Numeric Functions. (line 45) +* log: Numeric Functions. (line 43) * log files, timestamps in: Time Functions. (line 6) -* logarithm: Numeric Functions. (line 45) +* logarithm: Numeric Functions. (line 43) * logical false/true: Truth Values. (line 6) * logical operators, See Boolean expressions: Boolean Ops. (line 6) * login information: Passwd Functions. (line 16) @@ -33312,7 +33336,7 @@ Index * mail-list file: Sample Data Files. (line 6) * mailing labels, printing: Labels Program. (line 6) * mailing list, GNITS: Acknowledgments. (line 52) -* Malmberg, John <1>: Bugs. (line 72) +* Malmberg, John <1>: Bugs. (line 70) * Malmberg, John: Acknowledgments. (line 60) * Malmberg, John E.: Contributors. (line 137) * mark parity: Ordinal Functions. (line 45) @@ -33320,20 +33344,20 @@ Index (line 6) * marked strings, extracting: String Extraction. (line 6) * Marx, Groucho: Increment Ops. (line 60) -* match: String Functions. (line 210) -* match regexp in string: String Functions. (line 210) +* match: String Functions. (line 211) +* match regexp in string: String Functions. (line 211) * match() function, RSTART/RLENGTH variables: String Functions. - (line 227) + (line 228) * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) -* matching, null strings: String Functions. (line 535) -* mawk utility <1>: Other Versions. (line 44) +* matching, null strings: String Functions. (line 536) +* mawk utility <1>: Other Versions. (line 48) * mawk utility <2>: Nextfile Statement. (line 47) * mawk utility <3>: Concatenation. (line 36) * mawk utility <4>: Getline/Pipe. (line 62) -* mawk utility: Escape Sequences. (line 133) -* maximum precision supported by MPFR library: Auto-set. (line 228) +* mawk utility: Escape Sequences. (line 120) +* maximum precision supported by MPFR library: Auto-set. (line 235) * McIlroy, Doug: Glossary. (line 149) * McPhee, Patrick: Contributors. (line 100) * message object files: Explaining gettext. (line 42) @@ -33346,7 +33370,7 @@ Index * messages from extensions: Printing Messages. (line 6) * metacharacters in regular expressions: Regexp Operators. (line 6) * metacharacters, escape sequences for: Escape Sequences. (line 139) -* minimum precision supported by MPFR library: Auto-set. (line 231) +* minimum precision supported by MPFR library: Auto-set. (line 238) * mktime: Time Functions. (line 25) * modifiers, in format specifiers: Format Modifiers. (line 6) * monetary information, localization: Explaining gettext. (line 104) @@ -33395,7 +33419,7 @@ Index (line 47) * nexti debugger command: Debugger Execution Control. (line 49) -* NF variable <1>: Auto-set. (line 112) +* NF variable <1>: Auto-set. (line 119) * NF variable: Fields. (line 33) * NF variable, decrementing: Changing Fields. (line 107) * ni debugger command (alias for nexti): Debugger Execution Control. @@ -33404,9 +33428,9 @@ Index * non-existent array elements: Reference to Elements. (line 23) * not Boolean-logic operator: Boolean Ops. (line 6) -* NR variable <1>: Auto-set. (line 132) +* NR variable <1>: Auto-set. (line 139) * NR variable: Records. (line 6) -* NR variable, changing: Auto-set. (line 321) +* NR variable, changing: Auto-set. (line 328) * null strings <1>: Basic Data Typing. (line 26) * null strings <2>: Truth Values. (line 6) * null strings <3>: Regexp Field Splitting. @@ -33418,9 +33442,9 @@ Index (line 43) * null strings, converting numbers to strings: Strings And Numbers. (line 21) -* null strings, matching: String Functions. (line 535) +* null strings, matching: String Functions. (line 536) * number as string of bits: Bitwise Functions. (line 110) -* number of array elements: String Functions. (line 200) +* number of array elements: String Functions. (line 201) * number sign (#), #! (executable scripts): Executable Scripts. (line 6) * number sign (#), commenting: Comments. (line 6) @@ -33451,7 +33475,7 @@ Index * OFS variable <2>: Output Separators. (line 6) * OFS variable: Changing Fields. (line 64) * OpenBSD: Glossary. (line 611) -* OpenSolaris: Other Versions. (line 96) +* OpenSolaris: Other Versions. (line 100) * operating systems, BSD-based: Manual History. (line 28) * operating systems, PC, gawk on: PC Using. (line 6) * operating systems, PC, gawk on, installing: PC Installation. @@ -33501,10 +33525,10 @@ Index * ord() user-defined function: Ordinal Functions. (line 16) * order of evaluation, concatenation: Concatenation. (line 41) * ORS variable <1>: User-modified. (line 118) -* ORS variable: Output Separators. (line 20) +* ORS variable: Output Separators. (line 21) * output field separator, See OFS variable: Changing Fields. (line 64) * output record separator, See ORS variable: Output Separators. - (line 20) + (line 21) * output redirection: Redirection. (line 6) * output wrapper: Output Wrappers. (line 6) * output, buffering: I/O Functions. (line 32) @@ -33515,16 +33539,16 @@ Index * output, formatted: Printf. (line 6) * output, pipes: Redirection. (line 57) * output, printing, See printing: Printing. (line 6) -* output, records: Output Separators. (line 20) +* output, records: Output Separators. (line 21) * output, standard: Special FD. (line 6) * p debugger command (alias for print): Viewing And Changing Data. (line 36) * Papadopoulos, Panos: Contributors. (line 128) -* parent process ID of gawk process: Auto-set. (line 196) +* parent process ID of gawk process: Auto-set. (line 203) * parentheses (), in a profile: Profiling. (line 146) * parentheses (), regexp operator: Regexp Operators. (line 81) * password file: Passwd Functions. (line 16) -* patsplit: String Functions. (line 296) +* patsplit: String Functions. (line 297) * patterns: Patterns and Actions. (line 6) * patterns, comparison expressions as: Expression Patterns. (line 14) @@ -33536,8 +33560,8 @@ Index * patterns, regexp constants as: Expression Patterns. (line 34) * patterns, types of: Pattern Overview. (line 15) * pawk (profiling version of Brian Kernighan's awk): Other Versions. - (line 78) -* pawk, awk-like facilities for Python: Other Versions. (line 125) + (line 82) +* pawk, awk-like facilities for Python: Other Versions. (line 129) * PC operating systems, gawk on: PC Using. (line 6) * PC operating systems, gawk on, installing: PC Installation. (line 6) * percent sign (%), % operator: Precedence. (line 55) @@ -33551,7 +33575,7 @@ Index (line 6) * pipe, input: Getline/Pipe. (line 9) * pipe, output: Redirection. (line 57) -* Pitts, Dave <1>: Bugs. (line 72) +* Pitts, Dave <1>: Bugs. (line 70) * Pitts, Dave: Acknowledgments. (line 60) * Plauger, P.J.: Library Functions. (line 12) * plug-in: Extension Intro. (line 6) @@ -33569,7 +33593,7 @@ Index * portability, ARGV variable: Executable Scripts. (line 59) * portability, backslash continuation and: Statements/Lines. (line 30) * portability, backslash in escape sequences: Escape Sequences. - (line 121) + (line 108) * portability, close() function and: Close Files And Pipes. (line 81) * portability, data files as single record: gawk split records. @@ -33580,15 +33604,15 @@ Index * portability, gawk: New Ports. (line 6) * portability, gettext library and: Explaining gettext. (line 11) * portability, internationalization and: I18N Portability. (line 6) -* portability, length() function: String Functions. (line 179) +* portability, length() function: String Functions. (line 180) * portability, new awk vs. old awk: Strings And Numbers. (line 57) * portability, next statement in user-defined functions: Pass By Value/Reference. - (line 91) + (line 88) * portability, NF variable, decrementing: Changing Fields. (line 115) * portability, operators: Increment Ops. (line 60) * portability, operators, not in POSIX awk: Precedence. (line 98) * portability, POSIXLY_CORRECT environment variable: Options. (line 359) -* portability, substr() function: String Functions. (line 511) +* portability, substr() function: String Functions. (line 512) * portable object files <1>: Translator i18n. (line 6) * portable object files: Explaining gettext. (line 37) * portable object files, converting to message object files: I18N Example. @@ -33608,7 +33632,7 @@ Index * POSIX awk, < operator and: Getline/File. (line 26) * POSIX awk, arithmetic operators and: Arithmetic Ops. (line 30) * POSIX awk, backslashes in string constants: Escape Sequences. - (line 121) + (line 108) * POSIX awk, BEGIN/END patterns: I/O And BEGIN/END. (line 16) * POSIX awk, bracket expressions and: Bracket Expressions. (line 26) * POSIX awk, bracket expressions and, character classes: Bracket Expressions. @@ -33618,13 +33642,12 @@ Index * POSIX awk, continue statement and: Continue Statement. (line 44) * POSIX awk, CONVFMT variable and: User-modified. (line 30) * POSIX awk, date utility and: Time Functions. (line 254) -* POSIX awk, field separators and <1>: Field Splitting Summary. - (line 40) +* POSIX awk, field separators and <1>: Full Line Fields. (line 16) * POSIX awk, field separators and: Fields. (line 6) * POSIX awk, FS variable and: User-modified. (line 60) * POSIX awk, function keyword in: Definition Syntax. (line 93) * POSIX awk, functions and, gsub()/sub(): Gory Details. (line 90) -* POSIX awk, functions and, length(): String Functions. (line 179) +* POSIX awk, functions and, length(): String Functions. (line 180) * POSIX awk, GNU long options and: Options. (line 15) * POSIX awk, interval expressions in: Regexp Operators. (line 135) * POSIX awk, next/nextfile statements and: Next Statement. (line 44) @@ -33687,24 +33710,24 @@ Index * printing, unduplicated lines of text: Uniq Program. (line 6) * printing, user information: Id Program. (line 6) * private variables: Library Names. (line 11) -* process group idIDof gawk process: Auto-set. (line 190) -* process ID of gawk process: Auto-set. (line 193) +* process group idIDof gawk process: Auto-set. (line 197) +* process ID of gawk process: Auto-set. (line 200) * processes, two-way communications with: Two-way I/O. (line 6) * processing data: Basic High Level. (line 6) * PROCINFO array <1>: Passwd Functions. (line 6) * PROCINFO array <2>: Time Functions. (line 47) -* PROCINFO array: Auto-set. (line 137) +* PROCINFO array: Auto-set. (line 144) * PROCINFO array, and communications via ptys: Two-way I/O. (line 99) * PROCINFO array, and group membership: Group Functions. (line 6) * PROCINFO array, and user and group ID numbers: Id Program. (line 15) * PROCINFO array, testing the field splitting: Passwd Functions. (line 154) -* PROCINFO array, uses: Auto-set. (line 249) +* PROCINFO array, uses: Auto-set. (line 256) * PROCINFO, values of sorted_in: Controlling Scanning. (line 26) * profiling awk programs: Profiling. (line 6) * profiling awk programs, dynamically: Profiling. (line 178) -* program identifiers: Auto-set. (line 155) +* program identifiers: Auto-set. (line 162) * program, definition of: Getting Started. (line 21) * programming conventions, --non-decimal-data option: Nondecimal Data. (line 35) @@ -33721,7 +33744,7 @@ Index * programming conventions, private variable names: Library Names. (line 23) * programming language, recipe for: History. (line 6) -* programming languages, Ada: Glossary. (line 19) +* programming languages, Ada: Glossary. (line 11) * programming languages, data-driven vs. procedural: Getting Started. (line 12) * programming languages, Java: Glossary. (line 379) @@ -33730,13 +33753,13 @@ Index * pwcat program: Passwd Functions. (line 23) * q debugger command (alias for quit): Miscellaneous Debugger Commands. (line 99) -* QSE Awk: Other Versions. (line 131) +* QSE Awk: Other Versions. (line 135) * Quanstrom, Erik: Alarm Program. (line 8) * question mark (?), ?: operator: Precedence. (line 92) * question mark (?), regexp operator <1>: GNU Regexp Operators. (line 59) * question mark (?), regexp operator: Regexp Operators. (line 111) -* QuikTrim Awk: Other Versions. (line 135) +* QuikTrim Awk: Other Versions. (line 139) * quit debugger command: Miscellaneous Debugger Commands. (line 99) * QUIT signal (MS-Windows): Profiling. (line 213) @@ -33748,12 +33771,12 @@ Index * Rakitzis, Byron: History Sorting. (line 25) * Ramey, Chet <1>: General Data Types. (line 6) * Ramey, Chet: Acknowledgments. (line 60) -* rand: Numeric Functions. (line 50) +* rand: Numeric Functions. (line 48) * random numbers, Cliff: Cliff Random Function. (line 6) * random numbers, rand()/srand() functions: Numeric Functions. - (line 50) -* random numbers, seed of: Numeric Functions. (line 80) + (line 48) +* random numbers, seed of: Numeric Functions. (line 78) * range expressions (regexps): Bracket Expressions. (line 6) * range patterns: Ranges. (line 6) * range patterns, line continuation and: Ranges. (line 65) @@ -33838,12 +33861,12 @@ Index * regular expressions, searching for: Egrep Program. (line 6) * relational operators, See comparison operators: Typing and Comparison. (line 9) -* replace in string: String Functions. (line 407) +* replace in string: String Functions. (line 408) * return debugger command: Debugger Execution Control. (line 54) * return statement, user-defined functions: Return Statement. (line 6) * return value, close() function: Close Files And Pipes. - (line 132) + (line 133) * rev() user-defined function: Function Example. (line 54) * revoutput extension: Extension Sample Revout. (line 11) @@ -33862,10 +33885,10 @@ Index * right shift: Bitwise Functions. (line 53) * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 54) -* RLENGTH variable: Auto-set. (line 259) -* RLENGTH variable, match() function and: String Functions. (line 227) +* RLENGTH variable: Auto-set. (line 266) +* RLENGTH variable, match() function and: String Functions. (line 228) * Robbins, Arnold <1>: Future Extensions. (line 6) -* Robbins, Arnold <2>: Bugs. (line 72) +* Robbins, Arnold <2>: Bugs. (line 70) * Robbins, Arnold <3>: Contributors. (line 144) * Robbins, Arnold <4>: General Data Types. (line 6) * Robbins, Arnold <5>: Alarm Program. (line 6) @@ -33888,9 +33911,9 @@ Index * RS variable: awk split records. (line 12) * RS variable, multiline records and: Multiple Line. (line 17) * rshift: Bitwise Functions. (line 53) -* RSTART variable: Auto-set. (line 265) -* RSTART variable, match() function and: String Functions. (line 227) -* RT variable <1>: Auto-set. (line 272) +* RSTART variable: Auto-set. (line 272) +* RSTART variable, match() function and: String Functions. (line 228) +* RT variable <1>: Auto-set. (line 279) * RT variable <2>: Multiple Line. (line 129) * RT variable: awk split records. (line 125) * Rubin, Paul <1>: Contributors. (line 15) @@ -33910,27 +33933,26 @@ Index * scanning arrays: Scanning an Array. (line 6) * scanning multidimensional arrays: Multiscanning. (line 11) * Schorr, Andrew <1>: Contributors. (line 133) -* Schorr, Andrew <2>: Auto-set. (line 304) +* Schorr, Andrew <2>: Auto-set. (line 311) * Schorr, Andrew: Acknowledgments. (line 60) * Schreiber, Bert: Acknowledgments. (line 38) * Schreiber, Rita: Acknowledgments. (line 38) -* search and replace in strings: String Functions. (line 89) -* search in string: String Functions. (line 155) -* search paths <1>: VMS Running. (line 58) +* search and replace in strings: String Functions. (line 90) +* search in string: String Functions. (line 156) +* search paths <1>: VMS Running. (line 57) * search paths <2>: PC Using. (line 10) * search paths: Programs Exercises. (line 70) * search paths, for loadable extensions: AWKLIBPATH Variable. (line 6) -* search paths, for source files <1>: VMS Running. (line 58) +* search paths, for source files <1>: VMS Running. (line 57) * search paths, for source files <2>: PC Using. (line 10) * search paths, for source files <3>: Programs Exercises. (line 70) * search paths, for source files: AWKPATH Variable. (line 6) * searching, files for regular expressions: Egrep Program. (line 6) * searching, for words: Dupword Program. (line 6) -* sed utility <1>: Glossary. (line 11) +* sed utility <1>: Glossary. (line 16) * sed utility <2>: Simple Sed. (line 6) -* sed utility: Field Splitting Summary. - (line 46) -* seeding random number generator: Numeric Functions. (line 80) +* sed utility: Full Line Fields. (line 22) +* seeding random number generator: Numeric Functions. (line 78) * semicolon (;), AWKPATH variable and: PC Using. (line 10) * semicolon (;), separating statements in actions <1>: Statements. (line 10) @@ -33991,26 +34013,26 @@ Index * sidebar, A Constant's Base Does Not Affect Its Value: Nondecimal-numbers. (line 64) * sidebar, Backslash Before Regular Characters: Escape Sequences. - (line 119) -* sidebar, Changing FS Does Not Affect the Fields: Field Splitting Summary. - (line 38) -* sidebar, Changing NR and FNR: Auto-set. (line 319) + (line 106) +* sidebar, Changing FS Does Not Affect the Fields: Full Line Fields. + (line 14) +* sidebar, Changing NR and FNR: Auto-set. (line 326) * sidebar, Controlling Output Buffering with system(): I/O Functions. - (line 137) + (line 138) * sidebar, Escape Sequences for Metacharacters: Escape Sequences. (line 137) * sidebar, FS and IGNORECASE: Field Splitting Summary. - (line 64) + (line 38) * sidebar, Interactive Versus Noninteractive Buffering: I/O Functions. - (line 106) -* sidebar, Matching the Null String: String Functions. (line 533) + (line 73) +* sidebar, Matching the Null String: String Functions. (line 534) * sidebar, Operator Evaluation Order: Increment Ops. (line 58) * sidebar, Piping into sh: Redirection. (line 134) -* sidebar, Pre-POSIX awk Used OFMT For String Conversion: Strings And Numbers. +* sidebar, Pre-POSIX awk Used OFMT for String Conversion: Strings And Numbers. (line 55) -* sidebar, Recipe For A Programming Language: History. (line 6) +* sidebar, Recipe for a Programming Language: History. (line 6) * sidebar, RS = "\0" Is Not Portable: gawk split records. (line 63) -* sidebar, So Why Does gawk have BEGINFILE and ENDFILE?: Filetrans Function. +* sidebar, So Why Does gawk Have BEGINFILE and ENDFILE?: Filetrans Function. (line 82) * sidebar, Syntactic Ambiguities Between /= and Regular Expressions: Assignment Ops. (line 146) @@ -34019,7 +34041,7 @@ Index * sidebar, Using \n in Bracket Expressions of Dynamic Regexps: Computed Regexps. (line 57) * sidebar, Using close()'s Return Value: Close Files And Pipes. - (line 130) + (line 131) * SIGHUP signal, for dynamic profiling: Profiling. (line 210) * SIGINT signal (MS-Windows): Profiling. (line 213) * signals, HUP/SIGHUP, for profiling: Profiling. (line 210) @@ -34031,8 +34053,8 @@ Index * SIGUSR1 signal, for dynamic profiling: Profiling. (line 187) * silent debugger command: Debugger Execution Control. (line 10) -* sin: Numeric Functions. (line 91) -* sine: Numeric Functions. (line 91) +* sin: Numeric Functions. (line 89) +* sine: Numeric Functions. (line 89) * single quote ('): One-shot. (line 15) * single quote (') in gawk command lines: Long. (line 35) * single quote ('), in shell commands: Quoting. (line 48) @@ -34046,46 +34068,46 @@ Index * sleep utility: Alarm Program. (line 110) * sleep() extension function: Extension Sample Time. (line 22) -* Solaris, POSIX-compliant awk: Other Versions. (line 96) -* sort array: String Functions. (line 41) -* sort array indices: String Functions. (line 41) +* Solaris, POSIX-compliant awk: Other Versions. (line 100) +* sort array: String Functions. (line 42) +* sort array indices: String Functions. (line 42) * sort function, arrays, sorting: Array Sorting Functions. (line 6) * sort utility: Word Sorting. (line 50) * sort utility, coprocesses and: Two-way I/O. (line 65) * sorting characters in different languages: Explaining gettext. (line 94) -* source code, awka: Other Versions. (line 64) +* source code, awka: Other Versions. (line 68) * source code, Brian Kernighan's awk: Other Versions. (line 13) -* source code, Busybox Awk: Other Versions. (line 88) +* source code, Busybox Awk: Other Versions. (line 92) * source code, gawk: Gawk Distribution. (line 6) -* source code, Illumos awk: Other Versions. (line 105) -* source code, jawk: Other Versions. (line 113) -* source code, libmawk: Other Versions. (line 121) -* source code, mawk: Other Versions. (line 44) +* source code, Illumos awk: Other Versions. (line 109) +* source code, jawk: Other Versions. (line 117) +* source code, libmawk: Other Versions. (line 125) +* source code, mawk: Other Versions. (line 48) * source code, mixing: Options. (line 117) -* source code, pawk: Other Versions. (line 78) -* source code, pawk (Python version): Other Versions. (line 125) -* source code, QSE Awk: Other Versions. (line 131) -* source code, QuikTrim Awk: Other Versions. (line 135) -* source code, Solaris awk: Other Versions. (line 96) +* source code, pawk: Other Versions. (line 82) +* source code, pawk (Python version): Other Versions. (line 129) +* source code, QSE Awk: Other Versions. (line 135) +* source code, QuikTrim Awk: Other Versions. (line 139) +* source code, Solaris awk: Other Versions. (line 100) * source files, search path for: Programs Exercises. (line 70) * sparse arrays: Array Intro. (line 72) -* Spencer, Henry: Glossary. (line 11) -* split: String Functions. (line 315) -* split string into array: String Functions. (line 296) +* Spencer, Henry: Glossary. (line 16) +* split: String Functions. (line 316) +* split string into array: String Functions. (line 297) * split utility: Split Program. (line 6) * split() function, array elements, deleting: Delete. (line 61) * split.awk program: Split Program. (line 30) -* sprintf <1>: String Functions. (line 382) +* sprintf <1>: String Functions. (line 383) * sprintf: OFMT. (line 15) * sprintf() function, OFMT variable and: User-modified. (line 113) * sprintf() function, print/printf statements and: Round Function. (line 6) -* sqrt: Numeric Functions. (line 94) +* sqrt: Numeric Functions. (line 92) * square brackets ([]), regexp operator: Regexp Operators. (line 56) -* square root: Numeric Functions. (line 94) -* srand: Numeric Functions. (line 98) +* square root: Numeric Functions. (line 92) +* srand: Numeric Functions. (line 96) * stack frame: Debugging Terms. (line 10) * Stallman, Richard <1>: Glossary. (line 296) * Stallman, Richard <2>: Contributors. (line 23) @@ -34108,23 +34130,22 @@ Index * stop automatic display, in debugger: Viewing And Changing Data. (line 80) * stream editors <1>: Simple Sed. (line 6) -* stream editors: Field Splitting Summary. - (line 46) +* stream editors: Full Line Fields. (line 22) * strftime: Time Functions. (line 48) * string constants: Scalar Constants. (line 15) * string constants, vs. regexp constants: Computed Regexps. (line 39) * string extraction (internationalization): String Extraction. (line 6) -* string length: String Functions. (line 170) +* string length: String Functions. (line 171) * string operators: Concatenation. (line 8) -* string, regular expression match: String Functions. (line 210) +* string, regular expression match: String Functions. (line 211) * string-manipulation functions: String Functions. (line 6) * string-matching operators: Regexp Usage. (line 19) * string-translation functions: I18N Functions. (line 6) -* strings splitting, example: String Functions. (line 334) +* strings splitting, example: String Functions. (line 335) * strings, converting <1>: Bitwise Functions. (line 110) * strings, converting: Strings And Numbers. (line 6) -* strings, converting letter case: String Functions. (line 521) +* strings, converting letter case: String Functions. (line 522) * strings, converting, numbers to: User-modified. (line 30) * strings, empty, See null strings: awk split records. (line 115) * strings, extracting: String Extraction. (line 6) @@ -34134,13 +34155,13 @@ Index * strings, null: Regexp Field Splitting. (line 43) * strings, numeric: Variable Typing. (line 6) -* strtonum: String Functions. (line 389) +* strtonum: String Functions. (line 390) * strtonum() function (gawk), --non-decimal-data option and: Nondecimal Data. (line 35) -* sub <1>: String Functions. (line 407) +* sub <1>: String Functions. (line 408) * sub: Using Constant Regexps. (line 43) -* sub() function, arguments of: String Functions. (line 461) +* sub() function, arguments of: String Functions. (line 462) * sub() function, escape processing: Gory Details. (line 6) * subscript separators: User-modified. (line 145) * subscripts in arrays, multidimensional: Multidimensional. (line 10) @@ -34153,16 +34174,16 @@ Index * SUBSEP variable: User-modified. (line 145) * SUBSEP variable, and multidimensional arrays: Multidimensional. (line 16) -* substitute in string: String Functions. (line 89) -* substr: String Functions. (line 480) -* substring: String Functions. (line 480) -* Sumner, Andrew: Other Versions. (line 64) -* supplementary groups of gawk process: Auto-set. (line 244) +* substitute in string: String Functions. (line 90) +* substr: String Functions. (line 481) +* substring: String Functions. (line 481) +* Sumner, Andrew: Other Versions. (line 68) +* supplementary groups of gawk process: Auto-set. (line 251) * switch statement: Switch Statement. (line 6) -* SYMTAB array: Auto-set. (line 276) +* SYMTAB array: Auto-set. (line 283) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 148) -* system: I/O Functions. (line 74) +* system: I/O Functions. (line 106) * systime: Time Functions. (line 66) * t debugger command (alias for tbreak): Breakpoint Control. (line 90) * tbreak debugger command: Breakpoint Control. (line 90) @@ -34176,7 +34197,7 @@ Index * testbits.awk program: Bitwise Functions. (line 71) * testext extension: Extension Sample API Tests. (line 6) -* Texinfo <1>: Adding Code. (line 100) +* Texinfo <1>: Adding Code. (line 99) * Texinfo <2>: Distribution contents. (line 77) * Texinfo <3>: Extract Program. (line 12) @@ -34212,8 +34233,8 @@ Index * timestamps, converting dates to: Time Functions. (line 76) * timestamps, formatted: Getlocaltime Function. (line 6) -* tolower: String Functions. (line 522) -* toupper: String Functions. (line 528) +* tolower: String Functions. (line 523) +* toupper: String Functions. (line 529) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Debugger Commands. (line 108) @@ -34226,10 +34247,10 @@ Index (line 37) * troubleshooting, awk uses FS not IFS: Field Separators. (line 30) * troubleshooting, backslash before nonspecial character: Escape Sequences. - (line 121) + (line 108) * troubleshooting, division: Arithmetic Ops. (line 44) * troubleshooting, fatal errors, field widths, specifying: Constant Size. - (line 23) + (line 22) * troubleshooting, fatal errors, printf format strings: Format Modifiers. (line 158) * troubleshooting, fflush() function: I/O Functions. (line 62) @@ -34239,8 +34260,8 @@ Index * troubleshooting, gawk, fatal errors, function arguments: Calling Built-in. (line 16) * troubleshooting, getline function: File Checking. (line 25) -* troubleshooting, gsub()/sub() functions: String Functions. (line 471) -* troubleshooting, match() function: String Functions. (line 291) +* troubleshooting, gsub()/sub() functions: String Functions. (line 472) +* troubleshooting, match() function: String Functions. (line 292) * troubleshooting, print statement, omitting commas: Print Examples. (line 31) * troubleshooting, printing: Redirection. (line 112) @@ -34249,8 +34270,8 @@ Index * troubleshooting, regexp constants vs. string constants: Computed Regexps. (line 39) * troubleshooting, string concatenation: Concatenation. (line 26) -* troubleshooting, substr() function: String Functions. (line 498) -* troubleshooting, system() function: I/O Functions. (line 96) +* troubleshooting, substr() function: String Functions. (line 499) +* troubleshooting, system() function: I/O Functions. (line 128) * troubleshooting, typographical errors, global variables: Options. (line 98) * true, logical: Truth Values. (line 6) @@ -34265,7 +34286,7 @@ Index * unassigned array elements: Reference to Elements. (line 18) * undefined functions: Pass By Value/Reference. - (line 71) + (line 68) * underscore (_), C macro: Explaining gettext. (line 71) * underscore (_), in names of private variables: Library Names. (line 29) @@ -34282,9 +34303,9 @@ Index * uniq.awk program: Uniq Program. (line 65) * Unix: Glossary. (line 611) * Unix awk, backslashes in escape sequences: Escape Sequences. - (line 133) + (line 120) * Unix awk, close() function and: Close Files And Pipes. - (line 132) + (line 133) * Unix awk, password files, field separators and: Command Line Field Separator. (line 62) * Unix, awk scripts and: Executable Scripts. (line 6) @@ -34336,10 +34357,10 @@ Index * variables, uninitialized, as array subscripts: Uninitialized Subscripts. (line 6) * variables, user-defined: Variables. (line 6) -* version of gawk: Auto-set. (line 214) -* version of gawk extension API: Auto-set. (line 239) -* version of GNU MP library: Auto-set. (line 225) -* version of GNU MPFR library: Auto-set. (line 221) +* version of gawk: Auto-set. (line 221) +* version of gawk extension API: Auto-set. (line 246) +* version of GNU MP library: Auto-set. (line 232) +* version of GNU MPFR library: Auto-set. (line 228) * vertical bar (|): Regexp Operators. (line 70) * vertical bar (|), | operator (I/O) <1>: Precedence. (line 65) * vertical bar (|), | operator (I/O): Getline/Pipe. (line 9) @@ -34351,7 +34372,7 @@ Index * Vinschen, Corinna: Acknowledgments. (line 60) * w debugger command (alias for watch): Viewing And Changing Data. (line 67) -* w utility: Constant Size. (line 23) +* w utility: Constant Size. (line 22) * wait() extension function: Extension Sample Fork. (line 22) * waitpid() extension function: Extension Sample Fork. @@ -34396,7 +34417,7 @@ Index * xor: Bitwise Functions. (line 56) * XOR bitwise operation: Bitwise Functions. (line 6) * Yawitz, Efraim: Contributors. (line 131) -* Zaretskii, Eli <1>: Bugs. (line 72) +* Zaretskii, Eli <1>: Bugs. (line 70) * Zaretskii, Eli <2>: Contributors. (line 55) * Zaretskii, Eli: Acknowledgments. (line 60) * zerofile.awk program: Empty Files. (line 21) @@ -34413,7 +34434,7 @@ Index * | (vertical bar), |& operator (I/O) <3>: Redirection. (line 96) * | (vertical bar), |& operator (I/O): Getline/Coprocess. (line 6) * | (vertical bar), |& operator (I/O), pipes, closing: Close Files And Pipes. - (line 120) + (line 121) * | (vertical bar), || operator <1>: Precedence. (line 89) * | (vertical bar), || operator: Boolean Ops. (line 59) * ~ (tilde), ~ operator <1>: Expression Patterns. (line 24) @@ -34430,558 +34451,559 @@ Index Tag Table: Node: Top1204 Node: Foreword342225 -Node: Foreword446617 -Node: Preface48051 -Ref: Preface-Footnote-150922 -Ref: Preface-Footnote-251029 -Ref: Preface-Footnote-351262 -Node: History51404 -Node: Names53752 -Ref: Names-Footnote-154846 -Node: This Manual54992 -Ref: This Manual-Footnote-160821 -Node: Conventions60921 -Node: Manual History63261 -Ref: Manual History-Footnote-166252 -Ref: Manual History-Footnote-266293 -Node: How To Contribute66367 -Node: Acknowledgments67498 -Node: Getting Started72306 -Node: Running gawk74740 -Node: One-shot75930 -Node: Read Terminal77155 -Node: Long79182 -Node: Executable Scripts80698 -Ref: Executable Scripts-Footnote-183487 -Node: Comments83589 -Node: Quoting86062 -Node: DOS Quoting91568 -Node: Sample Data Files92243 -Node: Very Simple94836 -Node: Two Rules99727 -Node: More Complex101613 -Node: Statements/Lines104475 -Ref: Statements/Lines-Footnote-1108931 -Node: Other Features109196 -Node: When110127 -Ref: When-Footnote-1111883 -Node: Intro Summary111948 -Node: Invoking Gawk112831 -Node: Command Line114346 -Node: Options115137 -Ref: Options-Footnote-1130920 -Node: Other Arguments130945 -Node: Naming Standard Input133906 -Node: Environment Variables134999 -Node: AWKPATH Variable135557 -Ref: AWKPATH Variable-Footnote-1138967 -Ref: AWKPATH Variable-Footnote-2139012 -Node: AWKLIBPATH Variable139272 -Node: Other Environment Variables140528 -Node: Exit Status144019 -Node: Include Files144694 -Node: Loading Shared Libraries148282 -Node: Obsolete149709 -Node: Undocumented150406 -Node: Invoking Summary150673 -Node: Regexp152339 -Node: Regexp Usage153798 -Node: Escape Sequences155831 -Node: Regexp Operators162079 -Ref: Regexp Operators-Footnote-1169513 -Ref: Regexp Operators-Footnote-2169660 -Node: Bracket Expressions169758 -Ref: table-char-classes171775 -Node: Leftmost Longest174715 -Node: Computed Regexps176017 -Node: GNU Regexp Operators179414 -Node: Case-sensitivity183116 -Ref: Case-sensitivity-Footnote-1186006 -Ref: Case-sensitivity-Footnote-2186241 -Node: Regexp Summary186349 -Node: Reading Files187818 -Node: Records189912 -Node: awk split records190644 -Node: gawk split records195558 -Ref: gawk split records-Footnote-1200097 -Node: Fields200134 -Ref: Fields-Footnote-1202932 -Node: Nonconstant Fields203018 -Ref: Nonconstant Fields-Footnote-1205254 -Node: Changing Fields205456 -Node: Field Separators211388 -Node: Default Field Splitting214092 -Node: Regexp Field Splitting215209 -Node: Single Character Fields218559 -Node: Command Line Field Separator219618 -Node: Full Line Fields222830 -Ref: Full Line Fields-Footnote-1223338 -Node: Field Splitting Summary223384 -Ref: Field Splitting Summary-Footnote-1226515 -Node: Constant Size226616 -Node: Splitting By Content231222 -Ref: Splitting By Content-Footnote-1235295 -Node: Multiple Line235335 -Ref: Multiple Line-Footnote-1241224 -Node: Getline241403 -Node: Plain Getline243614 -Node: Getline/Variable246254 -Node: Getline/File247401 -Node: Getline/Variable/File248785 -Ref: Getline/Variable/File-Footnote-1250386 -Node: Getline/Pipe250473 -Node: Getline/Variable/Pipe253156 -Node: Getline/Coprocess254287 -Node: Getline/Variable/Coprocess255539 -Node: Getline Notes256278 -Node: Getline Summary259070 -Ref: table-getline-variants259482 -Node: Read Timeout260311 -Ref: Read Timeout-Footnote-1264125 -Node: Command-line directories264183 -Node: Input Summary265087 -Node: Input Exercises268339 -Node: Printing269067 -Node: Print270844 -Node: Print Examples272301 -Node: Output Separators275080 -Node: OFMT277098 -Node: Printf278452 -Node: Basic Printf279237 -Node: Control Letters280808 -Node: Format Modifiers284792 -Node: Printf Examples290799 -Node: Redirection293281 -Node: Special FD300120 -Ref: Special FD-Footnote-1303277 -Node: Special Files303351 -Node: Other Inherited Files303967 -Node: Special Network304967 -Node: Special Caveats305828 -Node: Close Files And Pipes306779 -Ref: Close Files And Pipes-Footnote-1313958 -Ref: Close Files And Pipes-Footnote-2314106 -Node: Output Summary314256 -Node: Output Exercises315252 -Node: Expressions315932 -Node: Values317117 -Node: Constants317793 -Node: Scalar Constants318473 -Ref: Scalar Constants-Footnote-1319332 -Node: Nondecimal-numbers319582 -Node: Regexp Constants322582 -Node: Using Constant Regexps323107 -Node: Variables326245 -Node: Using Variables326900 -Node: Assignment Options328810 -Node: Conversion330685 -Node: Strings And Numbers331209 -Ref: Strings And Numbers-Footnote-1334273 -Node: Locale influences conversions334382 -Ref: table-locale-affects337127 -Node: All Operators337715 -Node: Arithmetic Ops338345 -Node: Concatenation340850 -Ref: Concatenation-Footnote-1343669 -Node: Assignment Ops343775 -Ref: table-assign-ops348758 -Node: Increment Ops350036 -Node: Truth Values and Conditions353474 -Node: Truth Values354557 -Node: Typing and Comparison355606 -Node: Variable Typing356399 -Node: Comparison Operators360051 -Ref: table-relational-ops360461 -Node: POSIX String Comparison363976 -Ref: POSIX String Comparison-Footnote-1365048 -Node: Boolean Ops365186 -Ref: Boolean Ops-Footnote-1369665 -Node: Conditional Exp369756 -Node: Function Calls371483 -Node: Precedence375363 -Node: Locales379031 -Node: Expressions Summary380662 -Node: Patterns and Actions383236 -Node: Pattern Overview384356 -Node: Regexp Patterns386035 -Node: Expression Patterns386578 -Node: Ranges390358 -Node: BEGIN/END393464 -Node: Using BEGIN/END394226 -Ref: Using BEGIN/END-Footnote-1396963 -Node: I/O And BEGIN/END397069 -Node: BEGINFILE/ENDFILE399383 -Node: Empty402284 -Node: Using Shell Variables402601 -Node: Action Overview404877 -Node: Statements407204 -Node: If Statement409052 -Node: While Statement410550 -Node: Do Statement412578 -Node: For Statement413720 -Node: Switch Statement416875 -Node: Break Statement419263 -Node: Continue Statement421304 -Node: Next Statement423129 -Node: Nextfile Statement425509 -Node: Exit Statement428139 -Node: Built-in Variables430542 -Node: User-modified431675 -Ref: User-modified-Footnote-1439355 -Node: Auto-set439417 -Ref: Auto-set-Footnote-1452784 -Ref: Auto-set-Footnote-2452989 -Node: ARGC and ARGV453045 -Node: Pattern Action Summary457249 -Node: Arrays459676 -Node: Array Basics461005 -Node: Array Intro461849 -Ref: figure-array-elements463813 -Ref: Array Intro-Footnote-1466337 -Node: Reference to Elements466465 -Node: Assigning Elements468915 -Node: Array Example469406 -Node: Scanning an Array471164 -Node: Controlling Scanning474180 -Ref: Controlling Scanning-Footnote-1479369 -Node: Numeric Array Subscripts479685 -Node: Uninitialized Subscripts481870 -Node: Delete483487 -Ref: Delete-Footnote-1486231 -Node: Multidimensional486288 -Node: Multiscanning489383 -Node: Arrays of Arrays490972 -Node: Arrays Summary495733 -Node: Functions497838 -Node: Built-in498711 -Node: Calling Built-in499789 -Node: Numeric Functions501777 -Ref: Numeric Functions-Footnote-1506601 -Ref: Numeric Functions-Footnote-2506958 -Ref: Numeric Functions-Footnote-3507006 -Node: String Functions507275 -Ref: String Functions-Footnote-1530747 -Ref: String Functions-Footnote-2530876 -Ref: String Functions-Footnote-3531124 -Node: Gory Details531211 -Ref: table-sub-escapes532992 -Ref: table-sub-proposed534512 -Ref: table-posix-sub535876 -Ref: table-gensub-escapes537416 -Ref: Gory Details-Footnote-1538248 -Node: I/O Functions538399 -Ref: I/O Functions-Footnote-1545500 -Node: Time Functions545647 -Ref: Time Functions-Footnote-1556116 -Ref: Time Functions-Footnote-2556184 -Ref: Time Functions-Footnote-3556342 -Ref: Time Functions-Footnote-4556453 -Ref: Time Functions-Footnote-5556565 -Ref: Time Functions-Footnote-6556792 -Node: Bitwise Functions557058 -Ref: table-bitwise-ops557620 -Ref: Bitwise Functions-Footnote-1561928 -Node: Type Functions562097 -Node: I18N Functions563246 -Node: User-defined564891 -Node: Definition Syntax565695 -Ref: Definition Syntax-Footnote-1571101 -Node: Function Example571170 -Ref: Function Example-Footnote-1574087 -Node: Function Caveats574109 -Node: Calling A Function574627 -Node: Variable Scope575582 -Node: Pass By Value/Reference578570 -Node: Return Statement582080 -Node: Dynamic Typing585064 -Node: Indirect Calls585993 -Ref: Indirect Calls-Footnote-1597297 -Node: Functions Summary597425 -Node: Library Functions600124 -Ref: Library Functions-Footnote-1603742 -Ref: Library Functions-Footnote-2603885 -Node: Library Names604056 -Ref: Library Names-Footnote-1607516 -Ref: Library Names-Footnote-2607736 -Node: General Functions607822 -Node: Strtonum Function608925 -Node: Assert Function611945 -Node: Round Function615269 -Node: Cliff Random Function616810 -Node: Ordinal Functions617826 -Ref: Ordinal Functions-Footnote-1620891 -Ref: Ordinal Functions-Footnote-2621143 -Node: Join Function621354 -Ref: Join Function-Footnote-1623125 -Node: Getlocaltime Function623325 -Node: Readfile Function627066 -Node: Shell Quoting629036 -Node: Data File Management630437 -Node: Filetrans Function631069 -Node: Rewind Function635128 -Node: File Checking636513 -Ref: File Checking-Footnote-1637841 -Node: Empty Files638042 -Node: Ignoring Assigns640021 -Node: Getopt Function641572 -Ref: Getopt Function-Footnote-1653032 -Node: Passwd Functions653235 -Ref: Passwd Functions-Footnote-1662086 -Node: Group Functions662174 -Ref: Group Functions-Footnote-1670077 -Node: Walking Arrays670290 -Node: Library Functions Summary671893 -Node: Library Exercises673294 -Node: Sample Programs674574 -Node: Running Examples675344 -Node: Clones676072 -Node: Cut Program677296 -Node: Egrep Program687026 -Ref: Egrep Program-Footnote-1694530 -Node: Id Program694640 -Node: Split Program698284 -Ref: Split Program-Footnote-1701730 -Node: Tee Program701858 -Node: Uniq Program704645 -Node: Wc Program712066 -Ref: Wc Program-Footnote-1716314 -Node: Miscellaneous Programs716406 -Node: Dupword Program717619 -Node: Alarm Program719650 -Node: Translate Program724454 -Ref: Translate Program-Footnote-1729018 -Node: Labels Program729288 -Ref: Labels Program-Footnote-1732637 -Node: Word Sorting732721 -Node: History Sorting736791 -Node: Extract Program738627 -Node: Simple Sed746159 -Node: Igawk Program749221 -Ref: Igawk Program-Footnote-1763547 -Ref: Igawk Program-Footnote-2763748 -Ref: Igawk Program-Footnote-3763870 -Node: Anagram Program763985 -Node: Signature Program767047 -Node: Programs Summary768294 -Node: Programs Exercises769487 -Ref: Programs Exercises-Footnote-1773618 -Node: Advanced Features773709 -Node: Nondecimal Data775657 -Node: Array Sorting777247 -Node: Controlling Array Traversal777944 -Ref: Controlling Array Traversal-Footnote-1786275 -Node: Array Sorting Functions786393 -Ref: Array Sorting Functions-Footnote-1790285 -Node: Two-way I/O790479 -Ref: Two-way I/O-Footnote-1795423 -Ref: Two-way I/O-Footnote-2795609 -Node: TCP/IP Networking795691 -Node: Profiling798563 -Node: Advanced Features Summary806837 -Node: Internationalization808770 -Node: I18N and L10N810250 -Node: Explaining gettext810936 -Ref: Explaining gettext-Footnote-1815965 -Ref: Explaining gettext-Footnote-2816149 -Node: Programmer i18n816314 -Ref: Programmer i18n-Footnote-1821180 -Node: Translator i18n821229 -Node: String Extraction822023 -Ref: String Extraction-Footnote-1823154 -Node: Printf Ordering823240 -Ref: Printf Ordering-Footnote-1826026 -Node: I18N Portability826090 -Ref: I18N Portability-Footnote-1828539 -Node: I18N Example828602 -Ref: I18N Example-Footnote-1831402 -Node: Gawk I18N831474 -Node: I18N Summary832112 -Node: Debugger833451 -Node: Debugging834473 -Node: Debugging Concepts834914 -Node: Debugging Terms836771 -Node: Awk Debugging839346 -Node: Sample Debugging Session840238 -Node: Debugger Invocation840758 -Node: Finding The Bug842142 -Node: List of Debugger Commands848617 -Node: Breakpoint Control849949 -Node: Debugger Execution Control853641 -Node: Viewing And Changing Data857005 -Node: Execution Stack860370 -Node: Debugger Info862008 -Node: Miscellaneous Debugger Commands866025 -Node: Readline Support871217 -Node: Limitations872109 -Node: Debugging Summary874206 -Node: Arbitrary Precision Arithmetic875374 -Node: Computer Arithmetic876790 -Ref: table-numeric-ranges880391 -Ref: Computer Arithmetic-Footnote-1881250 -Node: Math Definitions881307 -Ref: table-ieee-formats884594 -Ref: Math Definitions-Footnote-1885198 -Node: MPFR features885303 -Node: FP Math Caution886974 -Ref: FP Math Caution-Footnote-1888024 -Node: Inexactness of computations888393 -Node: Inexact representation889341 -Node: Comparing FP Values890696 -Node: Errors accumulate891769 -Node: Getting Accuracy893202 -Node: Try To Round895861 -Node: Setting precision896760 -Ref: table-predefined-precision-strings897444 -Node: Setting the rounding mode899238 -Ref: table-gawk-rounding-modes899602 -Ref: Setting the rounding mode-Footnote-1903056 -Node: Arbitrary Precision Integers903235 -Ref: Arbitrary Precision Integers-Footnote-1908139 -Node: POSIX Floating Point Problems908288 -Ref: POSIX Floating Point Problems-Footnote-1912164 -Node: Floating point summary912202 -Node: Dynamic Extensions914394 -Node: Extension Intro915946 -Node: Plugin License917212 -Node: Extension Mechanism Outline918009 -Ref: figure-load-extension918437 -Ref: figure-register-new-function919917 -Ref: figure-call-new-function920921 -Node: Extension API Description922907 -Node: Extension API Functions Introduction924357 -Node: General Data Types929193 -Ref: General Data Types-Footnote-1934880 -Node: Memory Allocation Functions935179 -Ref: Memory Allocation Functions-Footnote-1938009 -Node: Constructor Functions938105 -Node: Registration Functions939839 -Node: Extension Functions940524 -Node: Exit Callback Functions942820 -Node: Extension Version String944068 -Node: Input Parsers944718 -Node: Output Wrappers954533 -Node: Two-way processors959049 -Node: Printing Messages961253 -Ref: Printing Messages-Footnote-1962330 -Node: Updating `ERRNO'962482 -Node: Requesting Values963222 -Ref: table-value-types-returned963950 -Node: Accessing Parameters964908 -Node: Symbol Table Access966139 -Node: Symbol table by name966653 -Node: Symbol table by cookie968633 -Ref: Symbol table by cookie-Footnote-1972772 -Node: Cached values972835 -Ref: Cached values-Footnote-1976339 -Node: Array Manipulation976430 -Ref: Array Manipulation-Footnote-1977528 -Node: Array Data Types977567 -Ref: Array Data Types-Footnote-1980224 -Node: Array Functions980316 -Node: Flattening Arrays984170 -Node: Creating Arrays991057 -Node: Extension API Variables995824 -Node: Extension Versioning996460 -Node: Extension API Informational Variables998361 -Node: Extension API Boilerplate999449 -Node: Finding Extensions1003265 -Node: Extension Example1003825 -Node: Internal File Description1004597 -Node: Internal File Ops1008664 -Ref: Internal File Ops-Footnote-11020322 -Node: Using Internal File Ops1020462 -Ref: Using Internal File Ops-Footnote-11022845 -Node: Extension Samples1023118 -Node: Extension Sample File Functions1024642 -Node: Extension Sample Fnmatch1032244 -Node: Extension Sample Fork1033726 -Node: Extension Sample Inplace1034939 -Node: Extension Sample Ord1036614 -Node: Extension Sample Readdir1037450 -Ref: table-readdir-file-types1038326 -Node: Extension Sample Revout1039137 -Node: Extension Sample Rev2way1039728 -Node: Extension Sample Read write array1040469 -Node: Extension Sample Readfile1042408 -Node: Extension Sample Time1043503 -Node: Extension Sample API Tests1044852 -Node: gawkextlib1045343 -Node: Extension summary1047993 -Node: Extension Exercises1051675 -Node: Language History1052397 -Node: V7/SVR3.11054054 -Node: SVR41056235 -Node: POSIX1057680 -Node: BTL1059069 -Node: POSIX/GNU1059803 -Node: Feature History1065432 -Node: Common Extensions1078530 -Node: Ranges and Locales1079854 -Ref: Ranges and Locales-Footnote-11084493 -Ref: Ranges and Locales-Footnote-21084520 -Ref: Ranges and Locales-Footnote-31084754 -Node: Contributors1084975 -Node: History summary1090515 -Node: Installation1091884 -Node: Gawk Distribution1092840 -Node: Getting1093324 -Node: Extracting1094148 -Node: Distribution contents1095790 -Node: Unix Installation1101855 -Node: Quick Installation1102538 -Node: Shell Startup Files1104956 -Node: Additional Configuration Options1106035 -Node: Configuration Philosophy1107776 -Node: Non-Unix Installation1110127 -Node: PC Installation1110585 -Node: PC Binary Installation1111911 -Node: PC Compiling1113759 -Ref: PC Compiling-Footnote-11116780 -Node: PC Testing1116885 -Node: PC Using1118061 -Node: Cygwin1122176 -Node: MSYS1122999 -Node: VMS Installation1123497 -Node: VMS Compilation1124289 -Ref: VMS Compilation-Footnote-11125511 -Node: VMS Dynamic Extensions1125569 -Node: VMS Installation Details1127253 -Node: VMS Running1129505 -Node: VMS GNV1132346 -Node: VMS Old Gawk1133080 -Node: Bugs1133550 -Node: Other Versions1137454 -Node: Installation summary1143667 -Node: Notes1144723 -Node: Compatibility Mode1145588 -Node: Additions1146370 -Node: Accessing The Source1147295 -Node: Adding Code1148731 -Node: New Ports1154903 -Node: Derived Files1159385 -Ref: Derived Files-Footnote-11164860 -Ref: Derived Files-Footnote-21164894 -Ref: Derived Files-Footnote-31165490 -Node: Future Extensions1165604 -Node: Implementation Limitations1166210 -Node: Extension Design1167458 -Node: Old Extension Problems1168612 -Ref: Old Extension Problems-Footnote-11170129 -Node: Extension New Mechanism Goals1170186 -Ref: Extension New Mechanism Goals-Footnote-11173546 -Node: Extension Other Design Decisions1173735 -Node: Extension Future Growth1175843 -Node: Old Extension Mechanism1176679 -Node: Notes summary1178441 -Node: Basic Concepts1179627 -Node: Basic High Level1180308 -Ref: figure-general-flow1180580 -Ref: figure-process-flow1181179 -Ref: Basic High Level-Footnote-11184408 -Node: Basic Data Typing1184593 -Node: Glossary1187921 -Node: Copying1213079 -Node: GNU Free Documentation License1250635 -Node: Index1275771 +Node: Foreword446667 +Node: Preface48100 +Ref: Preface-Footnote-150971 +Ref: Preface-Footnote-251078 +Ref: Preface-Footnote-351311 +Node: History51453 +Node: Names53799 +Ref: Names-Footnote-154893 +Node: This Manual55039 +Ref: This Manual-Footnote-161526 +Node: Conventions61626 +Node: Manual History63964 +Ref: Manual History-Footnote-166946 +Ref: Manual History-Footnote-266987 +Node: How To Contribute67061 +Node: Acknowledgments68190 +Node: Getting Started72995 +Node: Running gawk75428 +Node: One-shot76618 +Node: Read Terminal77866 +Node: Long79893 +Node: Executable Scripts81409 +Ref: Executable Scripts-Footnote-184198 +Node: Comments84301 +Node: Quoting86783 +Node: DOS Quoting92307 +Node: Sample Data Files92982 +Node: Very Simple95577 +Node: Two Rules100475 +Node: More Complex102361 +Node: Statements/Lines105223 +Ref: Statements/Lines-Footnote-1109678 +Node: Other Features109943 +Node: When110874 +Ref: When-Footnote-1112628 +Node: Intro Summary112693 +Node: Invoking Gawk113576 +Node: Command Line115090 +Node: Options115888 +Ref: Options-Footnote-1131692 +Ref: Options-Footnote-2131921 +Node: Other Arguments131946 +Node: Naming Standard Input134894 +Node: Environment Variables135987 +Node: AWKPATH Variable136545 +Ref: AWKPATH Variable-Footnote-1139958 +Ref: AWKPATH Variable-Footnote-2140003 +Node: AWKLIBPATH Variable140263 +Node: Other Environment Variables141519 +Node: Exit Status145007 +Node: Include Files145683 +Node: Loading Shared Libraries149280 +Node: Obsolete150707 +Node: Undocumented151404 +Node: Invoking Summary151671 +Node: Regexp153335 +Node: Regexp Usage154789 +Node: Escape Sequences156826 +Node: Regexp Operators163067 +Ref: Regexp Operators-Footnote-1170493 +Ref: Regexp Operators-Footnote-2170640 +Node: Bracket Expressions170738 +Ref: table-char-classes172753 +Node: Leftmost Longest175677 +Node: Computed Regexps176979 +Node: GNU Regexp Operators180376 +Node: Case-sensitivity184049 +Ref: Case-sensitivity-Footnote-1186934 +Ref: Case-sensitivity-Footnote-2187169 +Node: Regexp Summary187277 +Node: Reading Files188744 +Node: Records190838 +Node: awk split records191571 +Node: gawk split records196486 +Ref: gawk split records-Footnote-1201030 +Node: Fields201067 +Ref: Fields-Footnote-1203843 +Node: Nonconstant Fields203929 +Ref: Nonconstant Fields-Footnote-1206172 +Node: Changing Fields206376 +Node: Field Separators212305 +Node: Default Field Splitting215010 +Node: Regexp Field Splitting216127 +Node: Single Character Fields219477 +Node: Command Line Field Separator220536 +Node: Full Line Fields223748 +Ref: Full Line Fields-Footnote-1225265 +Ref: Full Line Fields-Footnote-2225311 +Node: Field Splitting Summary225412 +Node: Constant Size227486 +Node: Splitting By Content232075 +Ref: Splitting By Content-Footnote-1236069 +Node: Multiple Line236232 +Ref: Multiple Line-Footnote-1242118 +Node: Getline242297 +Node: Plain Getline244509 +Node: Getline/Variable247149 +Node: Getline/File248297 +Node: Getline/Variable/File249681 +Ref: Getline/Variable/File-Footnote-1251284 +Node: Getline/Pipe251371 +Node: Getline/Variable/Pipe254054 +Node: Getline/Coprocess255185 +Node: Getline/Variable/Coprocess256437 +Node: Getline Notes257176 +Node: Getline Summary259968 +Ref: table-getline-variants260380 +Node: Read Timeout261209 +Ref: Read Timeout-Footnote-1265034 +Node: Command-line directories265092 +Node: Input Summary265997 +Node: Input Exercises269298 +Node: Printing270026 +Node: Print271803 +Node: Print Examples273260 +Node: Output Separators276039 +Node: OFMT278057 +Node: Printf279411 +Node: Basic Printf280196 +Node: Control Letters281766 +Node: Format Modifiers285749 +Node: Printf Examples291758 +Node: Redirection294244 +Node: Special FD301085 +Ref: Special FD-Footnote-1304245 +Node: Special Files304319 +Node: Other Inherited Files304936 +Node: Special Network305936 +Node: Special Caveats306798 +Node: Close Files And Pipes307749 +Ref: Close Files And Pipes-Footnote-1314931 +Ref: Close Files And Pipes-Footnote-2315079 +Node: Output Summary315229 +Node: Output Exercises316227 +Node: Expressions316907 +Node: Values318092 +Node: Constants318770 +Node: Scalar Constants319461 +Ref: Scalar Constants-Footnote-1320320 +Node: Nondecimal-numbers320570 +Node: Regexp Constants323588 +Node: Using Constant Regexps324113 +Node: Variables327256 +Node: Using Variables327911 +Node: Assignment Options329822 +Node: Conversion331697 +Node: Strings And Numbers332221 +Ref: Strings And Numbers-Footnote-1335286 +Node: Locale influences conversions335395 +Ref: table-locale-affects338142 +Node: All Operators338730 +Node: Arithmetic Ops339360 +Node: Concatenation341865 +Ref: Concatenation-Footnote-1344684 +Node: Assignment Ops344790 +Ref: table-assign-ops349769 +Node: Increment Ops351041 +Node: Truth Values and Conditions354479 +Node: Truth Values355564 +Node: Typing and Comparison356613 +Node: Variable Typing357423 +Node: Comparison Operators361076 +Ref: table-relational-ops361486 +Node: POSIX String Comparison364981 +Ref: POSIX String Comparison-Footnote-1366053 +Node: Boolean Ops366191 +Ref: Boolean Ops-Footnote-1370670 +Node: Conditional Exp370761 +Node: Function Calls372488 +Node: Precedence376368 +Node: Locales380029 +Node: Expressions Summary381661 +Node: Patterns and Actions384221 +Node: Pattern Overview385341 +Node: Regexp Patterns387020 +Node: Expression Patterns387563 +Node: Ranges391273 +Node: BEGIN/END394379 +Node: Using BEGIN/END395140 +Ref: Using BEGIN/END-Footnote-1397874 +Node: I/O And BEGIN/END397980 +Node: BEGINFILE/ENDFILE400294 +Node: Empty403195 +Node: Using Shell Variables403512 +Node: Action Overview405785 +Node: Statements408111 +Node: If Statement409959 +Node: While Statement411454 +Node: Do Statement413483 +Node: For Statement414627 +Node: Switch Statement417784 +Node: Break Statement420166 +Node: Continue Statement422207 +Node: Next Statement424034 +Node: Nextfile Statement426415 +Node: Exit Statement429045 +Node: Built-in Variables431448 +Node: User-modified432581 +Ref: User-modified-Footnote-1440262 +Node: Auto-set440324 +Ref: Auto-set-Footnote-1454016 +Ref: Auto-set-Footnote-2454221 +Node: ARGC and ARGV454277 +Node: Pattern Action Summary458495 +Node: Arrays460922 +Node: Array Basics462251 +Node: Array Intro463095 +Ref: figure-array-elements465059 +Ref: Array Intro-Footnote-1467585 +Node: Reference to Elements467713 +Node: Assigning Elements470165 +Node: Array Example470656 +Node: Scanning an Array472414 +Node: Controlling Scanning475430 +Ref: Controlling Scanning-Footnote-1480626 +Node: Numeric Array Subscripts480942 +Node: Uninitialized Subscripts483127 +Node: Delete484744 +Ref: Delete-Footnote-1487487 +Node: Multidimensional487544 +Node: Multiscanning490641 +Node: Arrays of Arrays492230 +Node: Arrays Summary496989 +Node: Functions499081 +Node: Built-in499980 +Node: Calling Built-in501058 +Node: Numeric Functions503049 +Ref: Numeric Functions-Footnote-1507868 +Ref: Numeric Functions-Footnote-2508225 +Ref: Numeric Functions-Footnote-3508273 +Node: String Functions508545 +Ref: String Functions-Footnote-1532020 +Ref: String Functions-Footnote-2532149 +Ref: String Functions-Footnote-3532397 +Node: Gory Details532484 +Ref: table-sub-escapes534265 +Ref: table-sub-proposed535785 +Ref: table-posix-sub537149 +Ref: table-gensub-escapes538685 +Ref: Gory Details-Footnote-1539517 +Node: I/O Functions539668 +Ref: I/O Functions-Footnote-1546886 +Node: Time Functions547033 +Ref: Time Functions-Footnote-1557521 +Ref: Time Functions-Footnote-2557589 +Ref: Time Functions-Footnote-3557747 +Ref: Time Functions-Footnote-4557858 +Ref: Time Functions-Footnote-5557970 +Ref: Time Functions-Footnote-6558197 +Node: Bitwise Functions558463 +Ref: table-bitwise-ops559025 +Ref: Bitwise Functions-Footnote-1563334 +Node: Type Functions563503 +Node: I18N Functions564654 +Node: User-defined566299 +Node: Definition Syntax567104 +Ref: Definition Syntax-Footnote-1572511 +Node: Function Example572582 +Ref: Function Example-Footnote-1575501 +Node: Function Caveats575523 +Node: Calling A Function576041 +Node: Variable Scope576999 +Node: Pass By Value/Reference579987 +Node: Return Statement583482 +Node: Dynamic Typing586463 +Node: Indirect Calls587392 +Ref: Indirect Calls-Footnote-1598694 +Node: Functions Summary598822 +Node: Library Functions601524 +Ref: Library Functions-Footnote-1605133 +Ref: Library Functions-Footnote-2605276 +Node: Library Names605447 +Ref: Library Names-Footnote-1608901 +Ref: Library Names-Footnote-2609124 +Node: General Functions609210 +Node: Strtonum Function610313 +Node: Assert Function613335 +Node: Round Function616659 +Node: Cliff Random Function618200 +Node: Ordinal Functions619216 +Ref: Ordinal Functions-Footnote-1622279 +Ref: Ordinal Functions-Footnote-2622531 +Node: Join Function622742 +Ref: Join Function-Footnote-1624511 +Node: Getlocaltime Function624711 +Node: Readfile Function628455 +Node: Shell Quoting630425 +Node: Data File Management631826 +Node: Filetrans Function632458 +Node: Rewind Function636514 +Node: File Checking637901 +Ref: File Checking-Footnote-1639233 +Node: Empty Files639434 +Node: Ignoring Assigns641413 +Node: Getopt Function642964 +Ref: Getopt Function-Footnote-1654426 +Node: Passwd Functions654626 +Ref: Passwd Functions-Footnote-1663463 +Node: Group Functions663551 +Ref: Group Functions-Footnote-1671445 +Node: Walking Arrays671658 +Node: Library Functions Summary673261 +Node: Library Exercises674662 +Node: Sample Programs675942 +Node: Running Examples676712 +Node: Clones677440 +Node: Cut Program678664 +Node: Egrep Program688383 +Ref: Egrep Program-Footnote-1695881 +Node: Id Program695991 +Node: Split Program699636 +Ref: Split Program-Footnote-1703084 +Node: Tee Program703212 +Node: Uniq Program706001 +Node: Wc Program713420 +Ref: Wc Program-Footnote-1717670 +Node: Miscellaneous Programs717764 +Node: Dupword Program718977 +Node: Alarm Program721008 +Node: Translate Program725812 +Ref: Translate Program-Footnote-1730377 +Node: Labels Program730647 +Ref: Labels Program-Footnote-1733998 +Node: Word Sorting734082 +Node: History Sorting738153 +Node: Extract Program739989 +Node: Simple Sed747514 +Node: Igawk Program750582 +Ref: Igawk Program-Footnote-1764906 +Ref: Igawk Program-Footnote-2765107 +Ref: Igawk Program-Footnote-3765229 +Node: Anagram Program765344 +Node: Signature Program768401 +Node: Programs Summary769648 +Node: Programs Exercises770841 +Ref: Programs Exercises-Footnote-1774972 +Node: Advanced Features775063 +Node: Nondecimal Data777011 +Node: Array Sorting778601 +Node: Controlling Array Traversal779298 +Ref: Controlling Array Traversal-Footnote-1787631 +Node: Array Sorting Functions787749 +Ref: Array Sorting Functions-Footnote-1791638 +Node: Two-way I/O791834 +Ref: Two-way I/O-Footnote-1796779 +Ref: Two-way I/O-Footnote-2796965 +Node: TCP/IP Networking797047 +Node: Profiling799920 +Node: Advanced Features Summary808197 +Node: Internationalization810130 +Node: I18N and L10N811610 +Node: Explaining gettext812296 +Ref: Explaining gettext-Footnote-1817321 +Ref: Explaining gettext-Footnote-2817505 +Node: Programmer i18n817670 +Ref: Programmer i18n-Footnote-1822536 +Node: Translator i18n822585 +Node: String Extraction823379 +Ref: String Extraction-Footnote-1824510 +Node: Printf Ordering824596 +Ref: Printf Ordering-Footnote-1827382 +Node: I18N Portability827446 +Ref: I18N Portability-Footnote-1829901 +Node: I18N Example829964 +Ref: I18N Example-Footnote-1832767 +Node: Gawk I18N832839 +Node: I18N Summary833477 +Node: Debugger834816 +Node: Debugging835838 +Node: Debugging Concepts836279 +Node: Debugging Terms838132 +Node: Awk Debugging840704 +Node: Sample Debugging Session841598 +Node: Debugger Invocation842118 +Node: Finding The Bug843502 +Node: List of Debugger Commands849977 +Node: Breakpoint Control851310 +Node: Debugger Execution Control855006 +Node: Viewing And Changing Data858370 +Node: Execution Stack861748 +Node: Debugger Info863385 +Node: Miscellaneous Debugger Commands867402 +Node: Readline Support872431 +Node: Limitations873323 +Node: Debugging Summary875437 +Node: Arbitrary Precision Arithmetic876605 +Node: Computer Arithmetic878021 +Ref: table-numeric-ranges881619 +Ref: Computer Arithmetic-Footnote-1882478 +Node: Math Definitions882535 +Ref: table-ieee-formats885823 +Ref: Math Definitions-Footnote-1886427 +Node: MPFR features886532 +Node: FP Math Caution888203 +Ref: FP Math Caution-Footnote-1889253 +Node: Inexactness of computations889622 +Node: Inexact representation890581 +Node: Comparing FP Values891938 +Node: Errors accumulate893020 +Node: Getting Accuracy894453 +Node: Try To Round897115 +Node: Setting precision898014 +Ref: table-predefined-precision-strings898698 +Node: Setting the rounding mode900487 +Ref: table-gawk-rounding-modes900851 +Ref: Setting the rounding mode-Footnote-1904306 +Node: Arbitrary Precision Integers904485 +Ref: Arbitrary Precision Integers-Footnote-1909384 +Node: POSIX Floating Point Problems909533 +Ref: POSIX Floating Point Problems-Footnote-1913406 +Node: Floating point summary913444 +Node: Dynamic Extensions915638 +Node: Extension Intro917190 +Node: Plugin License918456 +Node: Extension Mechanism Outline919253 +Ref: figure-load-extension919681 +Ref: figure-register-new-function921161 +Ref: figure-call-new-function922165 +Node: Extension API Description924151 +Node: Extension API Functions Introduction925601 +Node: General Data Types930425 +Ref: General Data Types-Footnote-1936164 +Node: Memory Allocation Functions936463 +Ref: Memory Allocation Functions-Footnote-1939302 +Node: Constructor Functions939398 +Node: Registration Functions941132 +Node: Extension Functions941817 +Node: Exit Callback Functions944114 +Node: Extension Version String945362 +Node: Input Parsers946027 +Node: Output Wrappers955906 +Node: Two-way processors960421 +Node: Printing Messages962625 +Ref: Printing Messages-Footnote-1963701 +Node: Updating `ERRNO'963853 +Node: Requesting Values964593 +Ref: table-value-types-returned965321 +Node: Accessing Parameters966278 +Node: Symbol Table Access967509 +Node: Symbol table by name968023 +Node: Symbol table by cookie970004 +Ref: Symbol table by cookie-Footnote-1974148 +Node: Cached values974211 +Ref: Cached values-Footnote-1977710 +Node: Array Manipulation977801 +Ref: Array Manipulation-Footnote-1978899 +Node: Array Data Types978936 +Ref: Array Data Types-Footnote-1981591 +Node: Array Functions981683 +Node: Flattening Arrays985537 +Node: Creating Arrays992429 +Node: Extension API Variables997200 +Node: Extension Versioning997836 +Node: Extension API Informational Variables999737 +Node: Extension API Boilerplate1000802 +Node: Finding Extensions1004611 +Node: Extension Example1005171 +Node: Internal File Description1005943 +Node: Internal File Ops1010010 +Ref: Internal File Ops-Footnote-11021680 +Node: Using Internal File Ops1021820 +Ref: Using Internal File Ops-Footnote-11024203 +Node: Extension Samples1024476 +Node: Extension Sample File Functions1026002 +Node: Extension Sample Fnmatch1033640 +Node: Extension Sample Fork1035131 +Node: Extension Sample Inplace1036346 +Node: Extension Sample Ord1038021 +Node: Extension Sample Readdir1038857 +Ref: table-readdir-file-types1039733 +Node: Extension Sample Revout1040544 +Node: Extension Sample Rev2way1041134 +Node: Extension Sample Read write array1041874 +Node: Extension Sample Readfile1043814 +Node: Extension Sample Time1044909 +Node: Extension Sample API Tests1046258 +Node: gawkextlib1046749 +Node: Extension summary1049407 +Node: Extension Exercises1053096 +Node: Language History1053818 +Node: V7/SVR3.11055474 +Node: SVR41057655 +Node: POSIX1059100 +Node: BTL1060489 +Node: POSIX/GNU1061223 +Node: Feature History1066847 +Node: Common Extensions1079945 +Node: Ranges and Locales1081269 +Ref: Ranges and Locales-Footnote-11085887 +Ref: Ranges and Locales-Footnote-21085914 +Ref: Ranges and Locales-Footnote-31086148 +Node: Contributors1086369 +Node: History summary1091910 +Node: Installation1093280 +Node: Gawk Distribution1094226 +Node: Getting1094710 +Node: Extracting1095533 +Node: Distribution contents1097168 +Node: Unix Installation1103233 +Node: Quick Installation1103916 +Node: Shell Startup Files1106327 +Node: Additional Configuration Options1107406 +Node: Configuration Philosophy1109145 +Node: Non-Unix Installation1111514 +Node: PC Installation1111972 +Node: PC Binary Installation1113291 +Node: PC Compiling1115139 +Ref: PC Compiling-Footnote-11118160 +Node: PC Testing1118269 +Node: PC Using1119445 +Node: Cygwin1123560 +Node: MSYS1124383 +Node: VMS Installation1124883 +Node: VMS Compilation1125675 +Ref: VMS Compilation-Footnote-11126897 +Node: VMS Dynamic Extensions1126955 +Node: VMS Installation Details1128639 +Node: VMS Running1130891 +Node: VMS GNV1133727 +Node: VMS Old Gawk1134461 +Node: Bugs1134931 +Node: Other Versions1138814 +Node: Installation summary1145242 +Node: Notes1146298 +Node: Compatibility Mode1147163 +Node: Additions1147945 +Node: Accessing The Source1148870 +Node: Adding Code1150306 +Node: New Ports1156471 +Node: Derived Files1160953 +Ref: Derived Files-Footnote-11166428 +Ref: Derived Files-Footnote-21166462 +Ref: Derived Files-Footnote-31167058 +Node: Future Extensions1167172 +Node: Implementation Limitations1167778 +Node: Extension Design1169026 +Node: Old Extension Problems1170180 +Ref: Old Extension Problems-Footnote-11171697 +Node: Extension New Mechanism Goals1171754 +Ref: Extension New Mechanism Goals-Footnote-11175114 +Node: Extension Other Design Decisions1175303 +Node: Extension Future Growth1177411 +Node: Old Extension Mechanism1178247 +Node: Notes summary1180009 +Node: Basic Concepts1181195 +Node: Basic High Level1181876 +Ref: figure-general-flow1182148 +Ref: figure-process-flow1182747 +Ref: Basic High Level-Footnote-11185976 +Node: Basic Data Typing1186161 +Node: Glossary1189489 +Node: Copying1214647 +Node: GNU Free Documentation License1252203 +Node: Index1277339 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index e97b88b6..4b6e68c1 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -56,7 +56,7 @@ @set PATCHLEVEL 2 @ifset FOR_PRINT -@set TITLE Effective AWK Programming +@set TITLE Effective Awk Programming @end ifset @ifclear FOR_PRINT @set TITLE GAWK: Effective AWK Programming @@ -175,12 +175,24 @@ @macro DBREF{text} @ref{\text\} @end macro +@macro DBXREF{text} +@xref{\text\} +@end macro +@macro DBPXREF{text} +@pxref{\text\} +@end macro @end ifdocbook @ifnotdocbook @macro DBREF{text} @ref{\text\}, @end macro +@macro DBXREF{text} +@xref{\text\}, +@end macro +@macro DBPXREF{text} +@pxref{\text\}, +@end macro @end ifnotdocbook @ifclear FOR_PRINT @@ -315,7 +327,7 @@ A copy of the license is included in the section entitled A copy of the license may be found on the Internet at @uref{http://www.gnu.org/software/gawk/manual/html_node/GNU-Free-Documentation-License.html, -the GNU Project's web site}. +the GNU Project's website}. @end ifset @enumerate a @@ -383,10 +395,10 @@ ISBN 1-882114-28-0 @* @sp 9 @center @i{To my parents, for their love, and for the wonderful example they set for me.} @sp 1 -@center @i{To my wife Miriam, for making me complete. +@center @i{To my wife, Miriam, for making me complete. Thank you for building your life together with me.} @sp 1 -@center @i{To our children Chana, Rivka, Nachum and Malka, for enrichening our lives in innumerable ways.} +@center @i{To our children, Chana, Rivka, Nachum, and Malka, for enrichening our lives in innumerable ways.} @sp 1 @w{ } @page @@ -1076,7 +1088,7 @@ for enrichening our lives in innumerable ways. <!-- can't put mawk into command tags. sigh. --> <affiliation><jobtitle>Author of mawk</jobtitle></affiliation> </author> - <date>March, 2001</date> + <date>March 2001</date> </prefaceinfo> @end docbook @@ -1088,21 +1100,23 @@ The circumstances started a couple of years earlier. I was working at a new job and noticed an unplugged Unix computer sitting in the corner. No one knew how to use it, and neither did I. However, -a couple of days later it was running, and +a couple of days later, it was running, and I was @code{root} and the one-and-only user. That day, I began the transition from statistician to Unix programmer. On one of many trips to the library or bookstore in search of -books on Unix, I found the gray AWK book, a.k.a.@: Aho, Kernighan and -Weinberger, @cite{The AWK Programming Language}, Addison-Wesley, -1988. AWK's simple programming paradigm---find a pattern in the +books on Unix, I found the gray AWK book, a.k.a.@: +Alfred V.@: Aho, Brian W.@: Kernighan, and +Peter J.@: Weinberger's @cite{The AWK Programming Language} (Addison-Wesley, +1988). @command{awk}'s simple programming paradigm---find a pattern in the input and then perform an action---often reduced complex or tedious data manipulations to a few lines of code. I was excited to try my hand at programming in AWK. Alas, the @command{awk} on my computer was a limited version of the -language described in the AWK book. I discovered that my computer -had ``old @command{awk}'' and the AWK book described ``new @command{awk}.'' +language described in the gray book. I discovered that my computer +had ``old @command{awk}'' and the book described +``new @command{awk}.'' I learned that this was typical; the old version refused to step aside or relinquish its name. If a system had a new @command{awk}, it was invariably called @command{nawk}, and few systems had it. @@ -1120,7 +1134,7 @@ My Unix system started out unplugged from the wall; it certainly was not plugged into a network. So, oblivious to the existence of @command{gawk} and the Unix community in general, and desiring a new @command{awk}, I wrote my own, called @command{mawk}. -Before I was finished I knew about @command{gawk}, +Before I was finished, I knew about @command{gawk}, but it was too late to stop, so I eventually posted to a @code{comp.sources} newsgroup. @@ -1129,7 +1143,7 @@ from Arnold introducing himself. He suggested we share design and algorithms and attached a draft of the POSIX standard so that I could update @command{mawk} to support language extensions added -after publication of the AWK book. +after publication of @cite{The AWK Programming Language}. Frankly, if our roles had been reversed, I would not have been so open and we probably would @@ -1148,7 +1162,7 @@ standard. On the other hand, the novice AWK programmer can study a wealth of practical programs that emphasize the power of AWK's basic idioms: -data driven control-flow, pattern matching with regular expressions, +data-driven control flow, pattern matching with regular expressions, and associative arrays. Those looking for something new can try out @command{gawk}'s interface to network protocols via special @file{/inet} files. @@ -1209,7 +1223,7 @@ AWK or want to learn how, then read this book. @display Michael Brennan Author of @command{mawk} -March, 2001 +March 2001 @end display @end ifnotdocbook @@ -1227,7 +1241,7 @@ March, 2001 <!-- can't put mawk into command tags. sigh. --> <affiliation><jobtitle>Author of mawk</jobtitle></affiliation> </author> - <date>October, 2014</date> + <date>October 2014</date> </prefaceinfo> @end docbook @@ -1261,7 +1275,7 @@ details, and as expected, many examples to help you learn the ins and outs. @display Michael Brennan Author of @command{mawk} -October, 2014 +October 2014 @end display @end ifnotdocbook @@ -1281,9 +1295,9 @@ October, 2014 <firstname>Arnold</firstname> <surname>Robbins</surname> <affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation> - <affiliation><jobtitle>ISRAEL</jobtitle></affiliation> + <affiliation><jobtitle>Israel</jobtitle></affiliation> </author> - <date>December, 2014</date> + <date>December 2014</date> </prefaceinfo> @end docbook @@ -1295,7 +1309,7 @@ The @command{awk} utility interprets a special-purpose programming language that makes it easy to handle simple data-reformatting jobs. The GNU implementation of @command{awk} is called @command{gawk}; if you -invoke it with the proper options or environment variables +invoke it with the proper options or environment variables, it is fully compatible with the POSIX@footnote{The 2008 POSIX standard is accessible online at @w{@url{http://www.opengroup.org/onlinepubs/9699919799/}.}} @@ -1402,10 +1416,10 @@ has been removed.} @unnumberedsec History of @command{awk} and @command{gawk} @cindex recipe for a programming language @cindex programming language, recipe for -@cindex sidebar, Recipe For A Programming Language +@cindex sidebar, Recipe for a Programming Language @ifdocbook @docbook -<sidebar><title>Recipe For A Programming Language</title> +<sidebar><title>Recipe for a Programming Language</title> @end docbook @@ -1427,7 +1441,7 @@ more parts C. Document very well and release. @ifnotdocbook @cartouche -@center @b{Recipe For A Programming Language} +@center @b{Recipe for a Programming Language} @@ -1449,7 +1463,7 @@ more parts C. Document very well and release. @cindex Kernighan, Brian @cindex @command{awk}, history of The name @command{awk} comes from the initials of its designers: Alfred V.@: -Aho, Peter J.@: Weinberger and Brian W.@: Kernighan. The original version of +Aho, Peter J.@: Weinberger, and Brian W.@: Kernighan. The original version of @command{awk} was written in 1977 at AT&T Bell Laboratories. In 1985, a new version made the programming language more powerful, introducing user-defined functions, multiple input @@ -1475,7 +1489,7 @@ Circa 1994, I became the primary maintainer. Current development focuses on bug fixes, performance improvements, standards compliance and, occasionally, new features. -In May of 1997, J@"urgen Kahrs felt the need for network access +In May 1997, J@"urgen Kahrs felt the need for network access from @command{awk}, and with a little help from me, set about adding features to do this for @command{gawk}. At that time, he also wrote the bulk of @@ -1488,7 +1502,7 @@ John Haque rewrote the @command{gawk} internals, in the process providing an @command{awk}-level debugger. This version became available as @command{gawk} @value{PVERSION} 4.0, in 2011. -@xref{Contributors}, +@DBXREF{Contributors} for a full list of those who made important contributions to @command{gawk}. @node Names @@ -1498,7 +1512,7 @@ for a full list of those who made important contributions to @command{gawk}. The @command{awk} language has evolved over the years. Full details are provided in @ref{Language History}. The language described in this @value{DOCUMENT} -is often referred to as ``new @command{awk}''. +is often referred to as ``new @command{awk}.'' By analogy, the original version of @command{awk} is referred to as ``old @command{awk}.'' @@ -1577,12 +1591,15 @@ Most of the time, the examples use complete @command{awk} programs. Some of the more advanced sections show only the part of the @command{awk} program that illustrates the concept being described. -While this @value{DOCUMENT} is aimed principally at people who have not been +Although this @value{DOCUMENT} is aimed principally at people who have not been exposed to @command{awk}, there is a lot of information here that even the @command{awk} expert should find useful. In particular, the description of POSIX @command{awk} and the example programs in -@ref{Library Functions}, and in +@ref{Library Functions}, and +@ifnotdocbook +in +@end ifnotdocbook @ref{Sample Programs}, should be of interest. @@ -1590,22 +1607,30 @@ This @value{DOCUMENT} is split into several parts, as follows: @c FULLXREF ON +@itemize @value{BULLET} +@item Part I describes the @command{awk} language and @command{gawk} program in detail. It starts with the basics, and continues through all of the features of @command{awk}. It contains the following chapters: +@c nested +@itemize @value{MINUS} +@item @ref{Getting Started}, provides the essentials you need to know to begin using @command{awk}. +@item @ref{Invoking Gawk}, describes how to run @command{gawk}, the meaning of its command-line options, and how it finds @command{awk} program source files. +@item @ref{Regexp}, introduces regular expressions in general, and in particular the flavors supported by POSIX @command{awk} and @command{gawk}. +@item @ref{Reading Files}, describes how @command{awk} reads your data. It introduces the concepts of records and fields, as well @@ -1613,46 +1638,62 @@ as the @code{getline} command. I/O redirection is first described here. Network I/O is also briefly introduced here. +@item @ref{Printing}, describes how @command{awk} programs can produce output with @code{print} and @code{printf}. +@item @ref{Expressions}, describes expressions, which are the basic building blocks for getting most things done in a program. +@item @ref{Patterns and Actions}, describes how to write patterns for matching records, actions for doing something when a record is matched, and the predefined variables @command{awk} and @command{gawk} use. +@item @ref{Arrays}, covers @command{awk}'s one-and-only data structure: associative arrays. Deleting array elements and whole arrays is also described, as well as sorting arrays in @command{gawk}. It also describes how @command{gawk} provides arrays of arrays. +@item @ref{Functions}, describes the built-in functions @command{awk} and @command{gawk} provide, as well as how to define your own functions. It also discusses how @command{gawk} lets you call functions indirectly. +@end itemize +@item Part II shows how to use @command{awk} and @command{gawk} for problem solving. There is lots of code here for you to read and learn from. It contains the following chapters: +@c nested +@itemize @value{MINUS} +@item @ref{Library Functions}, which provides a number of functions meant to be used from main @command{awk} programs. +@item @ref{Sample Programs}, which provides many sample @command{awk} programs. +@end itemize Reading these two chapters allows you to see @command{awk} solving real problems. +@item Part III focuses on features specific to @command{gawk}. It contains the following chapters: +@c nested +@itemize @value{MINUS} +@item @ref{Advanced Features}, describes a number of advanced features. Of particular note @@ -1661,18 +1702,24 @@ have two-way communications with another process, perform TCP/IP networking, and profile your @command{awk} programs. +@item @ref{Internationalization}, describes special features for translating program messages into different languages at runtime. +@item @ref{Debugger}, describes the @command{gawk} debugger. +@item @ref{Arbitrary Precision Arithmetic}, describes advanced arithmetic facilities. +@item @ref{Dynamic Extensions}, describes how to add new variables and functions to @command{gawk} by writing extensions in C or C++. +@end itemize +@item @ifclear FOR_PRINT Part IV provides the appendices, the Glossary, and two licenses that cover the @command{gawk} source code and this @value{DOCUMENT}, respectively. @@ -1683,11 +1730,14 @@ Part IV provides the following appendices, including the GNU General Public License: @end ifset +@itemize @value{MINUS} +@item @ref{Language History}, describes how the @command{awk} language has evolved since its first release to present. It also describes how @command{gawk} has acquired features over time. +@item @ref{Installation}, describes how to get @command{gawk}, how to compile it on POSIX-compatible systems, @@ -1695,17 +1745,22 @@ and how to compile and use it on different non-POSIX systems. It also describes how to report bugs in @command{gawk} and where to get other freely available @command{awk} implementations. +@end itemize @ifset FOR_PRINT - +@itemize @value{MINUS} +@item @ref{Copying}, presents the license that covers the @command{gawk} source code. +@end itemize The version of this @value{DOCUMENT} distributed with @command{gawk} contains additional appendices and other end material. To save space, we have omitted them from the printed edition. You may find them online, as follows: +@itemize @value{BULLET} +@item @uref{http://www.gnu.org/software/gawk/manual/html_node/Notes.html, The appendix on implementation notes} describes how to disable @command{gawk}'s extensions, how to contribute @@ -1713,44 +1768,54 @@ new code to @command{gawk}, where to find information on some possible future directions for @command{gawk} development, and the design decisions behind the extension API. +@item @uref{http://www.gnu.org/software/gawk/manual/html_node/Basic-Concepts.html, The appendix on basic concepts} provides some very cursory background material for those who are completely unfamiliar with computer programming. +@item @uref{http://www.gnu.org/software/gawk/manual/html_node/Glossary.html, The Glossary} -defines most, if not all, the significant terms used +defines most, if not all of, the significant terms used throughout the @value{DOCUMENT}. If you find terms that you aren't familiar with, try looking them up here. +@item @uref{http://www.gnu.org/software/gawk/manual/html_node/GNU-Free-Documentation-License.html, The GNU FDL} is the license that covers this @value{DOCUMENT}. +@end itemize Some of the chapters have exercise sections; these have also been omitted from the print edition but are available online. @end ifset @ifclear FOR_PRINT +@itemize @value{MINUS} +@item @ref{Notes}, describes how to disable @command{gawk}'s extensions, as well as how to contribute new code to @command{gawk}, and some possible future directions for @command{gawk} development. +@item @ref{Basic Concepts}, provides some very cursory background material for those who are completely unfamiliar with computer programming. -The @ref{Glossary}, defines most, if not all, the significant terms used +The @ref{Glossary}, defines most, if not all of, the significant terms used throughout the @value{DOCUMENT}. If you find terms that you aren't familiar with, try looking them up here. +@item @ref{Copying}, and @ref{GNU Free Documentation License}, present the licenses that cover the @command{gawk} source code and this @value{DOCUMENT}, respectively. +@end itemize @end ifclear +@end itemize @c FULLXREF OFF @@ -1813,7 +1878,7 @@ pressing the @kbd{d} key and finally releasing both keys. For the sake of brevity, throughout this @value{DOCUMENT}, we refer to Brian Kernighan's version of @command{awk} as ``BWK @command{awk}.'' -(@xref{Other Versions}, for information on his and other versions.) +(@DBXREF{Other Versions} for information on his and other versions.) @ifset FOR_PRINT @quotation NOTE @@ -1829,7 +1894,7 @@ Cautionary or warning notes look like this. @unnumberedsubsec Dark Corners @cindex Kernighan, Brian @quotation -@i{Dark corners are basically fractal --- no matter how much +@i{Dark corners are basically fractal---no matter how much you illuminate, there's always a smaller but darker one.} @author Brian Kernighan @end quotation @@ -1899,7 +1964,7 @@ The GPL applies to the C language source code for @command{gawk}. To find out more about the FSF and the GNU Project online, see @uref{http://www.gnu.org, the GNU Project's home page}. This @value{DOCUMENT} may also be read from -@uref{http://www.gnu.org/software/gawk/manual/, their web site}. +@uref{http://www.gnu.org/software/gawk/manual/, GNU's website}. @ifclear FOR_PRINT A shell, an editor (Emacs), highly portable optimizing C, C++, and @@ -1936,10 +2001,10 @@ License in @ref{GNU Free Documentation License}.) @cindex Close, Diane The @value{DOCUMENT} itself has gone through multiple previous editions. Paul Rubin wrote the very first draft of @cite{The GAWK Manual}; -it was around 40 pages in size. +it was around 40 pages long. Diane Close and Richard Stallman improved it, yielding a version that was -around 90 pages long and barely described the original, ``old'' +around 90 pages and barely described the original, ``old'' version of @command{awk}. I started working with that version in the fall of 1988. @@ -1972,17 +2037,17 @@ and the major new additions are @ref{Arbitrary Precision Arithmetic}, and @ref{Dynamic Extensions}. This @value{DOCUMENT} will undoubtedly continue to evolve. If you -find an error in this @value{DOCUMENT}, please report it! @xref{Bugs}, +find an error in this @value{DOCUMENT}, please report it! @DBXREF{Bugs} for information on submitting problem reports electronically. @ifset FOR_PRINT @c fakenode --- for prepinfo @unnumberedsec How to Stay Current -It may be you have a version of @command{gawk} which is newer than the +You may have a newer version of @command{gawk} than the one described here. To find out what has changed, you should first look at the @file{NEWS} file in the @command{gawk} -distribution, which provides a high level summary of what changed in +distribution, which provides a high-level summary of what changed in each release. You can then look at the @uref{http://www.gnu.org/software/gawk/manual/, @@ -2007,13 +2072,13 @@ contributed code: the archive did not grow and the domain went unused for several years. Late in 2008, a volunteer took on the task of setting up -an @command{awk}-related web site---@uref{http://awk.info}---and did a very +an @command{awk}-related website---@uref{http://awk.info}---and did a very nice job. If you have written an interesting @command{awk} program, or have written a @command{gawk} extension that you would like to share with the rest of the world, please see @uref{http://awk.info/?contribute} for how to -contribute it to the web site. +contribute it to the website. @ignore As of this writing, this website is in search of a maintainer; please @@ -2160,15 +2225,16 @@ portable program it is today. It has been and continues to be a pleasure working with this team of fine people. Notable code and documentation contributions were made by -a number of people. @xref{Contributors}, for the full list. +a number of people. @DBXREF{Contributors} for the full list. @ifset FOR_PRINT @cindex Oram, Andy Thanks to Andy Oram, of O'Reilly Media, for initiating the fourth edition and for his support during the work. +Thanks to Jasmine Kwityn for her copy-editing work. @end ifset -Thanks to Michael Brennan for the Foreword. +Thanks to Michael Brennan for the Forewords. @cindex Duman, Patrice @cindex Berry, Karl @@ -2179,7 +2245,7 @@ the Texinfo markup language sane. @cindex Kernighan, Brian @cindex Brennan, Michael @cindex Day, Robert P.J.@: -Robert P.J.@: Day, Michael Brennan and Brian Kernighan kindly acted as +Robert P.J.@: Day, Michael Brennan, and Brian Kernighan kindly acted as reviewers for the 2015 edition of this @value{DOCUMENT}. Their feedback helped improve the final work. @@ -2191,7 +2257,7 @@ or its documentation without his help. Brian is in a class by himself as a programmer and technical author. I have to thank him (yet again) for his ongoing friendship -and the role model he has been for me for close to 30 years! +and for being a role model to me for close to 30 years! Having him as a reviewer is an exciting privilege. It has also been extremely humbling@enddots{} @@ -2212,8 +2278,8 @@ take advantage of those opportunities. @noindent Arnold Robbins @* Nof Ayalon @* -ISRAEL @* -December, 2014 +Israel @* +December 2014 @end iftex @ifnotinfo @@ -2230,31 +2296,31 @@ following chapters: @itemize @value{BULLET} @item -@ref{Getting Started}. +@ref{Getting Started} @item -@ref{Invoking Gawk}. +@ref{Invoking Gawk} @item -@ref{Regexp}. +@ref{Regexp} @item -@ref{Reading Files}. +@ref{Reading Files} @item -@ref{Printing}. +@ref{Printing} @item -@ref{Expressions}. +@ref{Expressions} @item -@ref{Patterns and Actions}. +@ref{Patterns and Actions} @item -@ref{Arrays}. +@ref{Arrays} @item -@ref{Functions}. +@ref{Functions} @end itemize @end ifdocbook @@ -2269,17 +2335,17 @@ following chapters: The basic function of @command{awk} is to search files for lines (or other units of text) that contain certain patterns. When a line matches one of the patterns, @command{awk} performs specified actions on that line. -@command{awk} keeps processing input lines in this way until it reaches +@command{awk} continues to process input lines in this way until it reaches the end of the input files. @cindex @command{awk}, uses for @cindex programming languages@comma{} data-driven vs.@: procedural @cindex @command{awk} programs Programs in @command{awk} are different from programs in most other languages, -because @command{awk} programs are @dfn{data-driven}; that is, you describe -the data you want to work with and then what to do when you find it. +because @command{awk} programs are @dfn{data driven} (i.e., you describe +the data you want to work with and then what to do when you find it). Most other languages are @dfn{procedural}; you have to describe, in great -detail, every step the program is to take. When working with procedural +detail, every step the program should take. When working with procedural languages, it is usually much harder to clearly describe the data your program will process. For this reason, @command{awk} programs are often refreshingly easy to @@ -2289,9 +2355,9 @@ read and write. @cindex rule, definition of When you run @command{awk}, you specify an @command{awk} @dfn{program} that tells @command{awk} what to do. The program consists of a series of -@dfn{rules}. (It may also contain @dfn{function definitions}, -an advanced feature that we will ignore for now. -@xref{User-defined}.) Each rule specifies one +@dfn{rules} (it may also contain @dfn{function definitions}, +an advanced feature that we will ignore for now; +@pxref{User-defined}). Each rule specifies one pattern to search for and one action to perform upon finding the pattern. @@ -2391,10 +2457,11 @@ programs from shell scripts, because it avoids the need for a separate file for the @command{awk} program. A self-contained shell script is more reliable because there are no other files to misplace. +Later in this chapter, +@ifdocbook +the section +@end ifdocbook @ref{Very Simple}, -@ifnotinfo -later in this @value{CHAPTER}, -@end ifnotinfo presents several short, self-contained programs. @@ -2453,7 +2520,7 @@ startup file. This next simple @command{awk} program emulates the @command{cat} utility; it copies whatever you type on the -keyboard to its standard output (why this works is explained shortly). +keyboard to its standard output (why this works is explained shortly): @example $ @kbd{awk '@{ print @}'} @@ -2538,7 +2605,7 @@ affect the execution of the @command{awk} program but it does make Once you have learned @command{awk}, you may want to write self-contained @command{awk} scripts, using the @samp{#!} script mechanism. You can do this on many systems.@footnote{The @samp{#!} mechanism works on -GNU/Linux systems, BSD-based systems and commercial Unix systems.} +GNU/Linux systems, BSD-based systems, and commercial Unix systems.} For example, you could update the file @file{advice} to look like this: @example @@ -2582,7 +2649,7 @@ according to the instructions in your program. (This is different from a @dfn{compiled} language such as C, where your program is first compiled into machine code that is executed directly by your system's processor.) The @command{awk} utility is thus termed an @dfn{interpreter}. -Many modern languages are interperted. +Many modern languages are interpreted. The line beginning with @samp{#!} lists the full @value{FN} of an interpreter to run and a single optional initial command-line argument @@ -2632,7 +2699,7 @@ according to the instructions in your program. (This is different from a @dfn{compiled} language such as C, where your program is first compiled into machine code that is executed directly by your system's processor.) The @command{awk} utility is thus termed an @dfn{interpreter}. -Many modern languages are interperted. +Many modern languages are interpreted. The line beginning with @samp{#!} lists the full @value{FN} of an interpreter to run and a single optional initial command-line argument @@ -2679,14 +2746,14 @@ can explain what the program does and how it works. Nearly all programming languages have provisions for comments, as programs are typically hard to understand without them. -In the @command{awk} language, a comment starts with the sharp sign +In the @command{awk} language, a comment starts with the number sign character (@samp{#}) and continues to the end of the line. The @samp{#} does not have to be the first character on the line. The -@command{awk} language ignores the rest of a line following a sharp sign. +@command{awk} language ignores the rest of a line following a number sign. For example, we could have put the following into @file{advice}: @example -# This program prints a nice friendly message. It helps +# This program prints a nice, friendly message. It helps # keep novice users from being afraid of the computer. BEGIN @{ print "Don't Panic!" @} @end example @@ -2702,7 +2769,8 @@ when reading it at a later time. @quotation CAUTION As mentioned in @ref{One-shot}, -you can enclose small to medium programs in single quotes, in order to keep +you can enclose short to medium-sized programs in single quotes, +in order to keep your shell scripts self-contained. When doing so, @emph{don't} put an apostrophe (i.e., a single quote) into a comment (or anywhere else in your program). The shell interprets the quote as the closing @@ -2731,7 +2799,7 @@ $ @kbd{awk '@{ print "hello" @} # let's be cute'} @cindex @code{\} (backslash) @cindex backslash (@code{\}) Putting a backslash before the single quote in @samp{let's} wouldn't help, -since backslashes are not special inside single quotes. +because backslashes are not special inside single quotes. The next @value{SUBSECTION} describes the shell's quoting rules. @end quotation @@ -2743,7 +2811,7 @@ The next @value{SUBSECTION} describes the shell's quoting rules. * DOS Quoting:: Quoting in Windows Batch Files. @end menu -For short to medium length @command{awk} programs, it is most convenient +For short to medium-length @command{awk} programs, it is most convenient to enter the program on the @command{awk} command line. This is best done by enclosing the entire program in single quotes. This is true whether you are entering the program interactively at @@ -2767,8 +2835,8 @@ or empty, string. The null string is character data that has no value. In other words, it is empty. It is written in @command{awk} programs like this: @code{""}. In the shell, it can be written using single -or double quotes: @code{""} or @code{''}. While the null string has -no characters in it, it does exist. Consider this command: +or double quotes: @code{""} or @code{''}. Although the null string has +no characters in it, it does exist. For example, consider this command: @example $ @kbd{echo ""} @@ -2778,8 +2846,7 @@ $ @kbd{echo ""} Here, the @command{echo} utility receives a single argument, even though that argument has no characters in it. In the rest of this @value{DOCUMENT}, we use the terms @dfn{null string} and @dfn{empty string} -interchangeably. Now, on to the quoting rules. - +interchangeably. Now, on to the quoting rules: @itemize @value{BULLET} @item @@ -2802,7 +2869,7 @@ The shell does no interpretation of the quoted text, passing it on verbatim to the command. It is @emph{impossible} to embed a single quote inside single-quoted text. Refer back to -@ref{Comments}, +@DBREF{Comments} for an example of what happens if you try. @item @@ -2812,7 +2879,7 @@ Double quotes protect most things between the opening and closing quotes. The shell does at least variable and command substitution on the quoted text. Different shells may do additional kinds of processing on double-quoted text. -Since certain characters within double-quoted text are processed by the shell, +Because certain characters within double-quoted text are processed by the shell, they must be @dfn{escaped} within the text. Of note are the characters @samp{$}, @samp{`}, @samp{\}, and @samp{"}, all of which must be preceded by a backslash within double-quoted text if they are to be passed on literally @@ -2874,7 +2941,7 @@ $ @kbd{awk 'BEGIN @{ print "Here is a single quote <'"'"'>" @}'} @noindent This program consists of three concatenated quoted strings. The first and the -third are single-quoted, the second is double-quoted. +third are single quoted, the second is double quoted. This can be ``simplified'' to: @@ -2919,7 +2986,7 @@ escapes mean. A fourth option is to use command-line variable assignment, like this: @example -$ awk -v sq="'" 'BEGIN @{ print "Here is a single quote <" sq ">" @}' +$ @kbd{awk -v sq="'" 'BEGIN @{ print "Here is a single quote <" sq ">" @}'} @print{} Here is a single quote <'> @end example @@ -2990,7 +3057,7 @@ information about monthly shipments. In both files, each line is considered to be one @dfn{record}. In @file{mail-list}, each record contains the name of a person, -his/her phone number, his/her email-address, and a code for their relationship +his/her phone number, his/her email address, and a code for his/her relationship with the author of the list. The columns are aligned using spaces. An @samp{A} in the last column @@ -3111,8 +3178,8 @@ empty action that does nothing (i.e., no lines are printed). Many practical @command{awk} programs are just a line or two. Following is a collection of useful, short programs to get you started. Some of these programs contain constructs that haven't been covered yet. (The description -of the program will give you a good idea of what is going on, but please -read the rest of the @value{DOCUMENT} to become an @command{awk} expert!) +of the program will give you a good idea of what is going on, but you'll +need to read the rest of the @value{DOCUMENT} to become an @command{awk} expert!) Most of the examples use a @value{DF} named @file{data}. This is just a placeholder; if you use these programs yourself, substitute your own @value{FN}s for @file{data}. @@ -3153,7 +3220,7 @@ expand data | awk '@{ if (x < length($0)) x = length($0) @} @end example This example differs slightly from the previous one: -The input is processed by the @command{expand} utility to change TABs +the input is processed by the @command{expand} utility to change TABs into spaces, so the widths compared are actually the right-margin columns, as opposed to the number of input characters on each line. @@ -3407,7 +3474,7 @@ lines in the middle of a regular expression or a string. with the C shell.} It works for @command{awk} programs in files and for one-shot programs, @emph{provided} you are using a POSIX-compliant shell, such as the Unix Bourne shell or Bash. But the C shell behaves -differently! There, you must use two backslashes in a row, followed by +differently! There you must use two backslashes in a row, followed by a newline. Note also that when using the C shell, @emph{every} newline in your @command{awk} program must be escaped with a backslash. To illustrate: @@ -3448,9 +3515,9 @@ starts a comment, it ignores @emph{everything} on the rest of the line. For example: @example -$ gawk 'BEGIN @{ print "dont panic" # a friendly \ -> BEGIN rule -> @}' +$ @kbd{gawk 'BEGIN @{ print "dont panic" # a friendly \} +> @kbd{ BEGIN rule} +> @kbd{@}'} @error{} gawk: cmd. line:2: BEGIN rule @error{} gawk: cmd. line:2: ^ syntax error @end example @@ -3500,7 +3567,7 @@ and array sorting. As we develop our presentation of the @command{awk} language, we introduce most of the variables and many of the functions. They are described -systematically in @ref{Built-in Variables}, and in +systematically in @DBREF{Built-in Variables} and in @ref{Built-in}. @node When @@ -3534,8 +3601,8 @@ eight-bit microprocessors, @end ifset and a microcode assembler for a special-purpose Prolog computer. -While the original @command{awk}'s capabilities were strained by tasks -of such complexity, modern versions are more capable. +The original @command{awk}'s capabilities were strained by tasks +of such complexity, but modern versions are more capable. @cindex @command{awk} programs, complex If you find yourself writing @command{awk} scripts of more than, say, @@ -3590,7 +3657,7 @@ a comma, open brace, question mark, colon, This @value{CHAPTER} covers how to run @command{awk}, both POSIX-standard and @command{gawk}-specific command-line options, and what @command{awk} and -@command{gawk} do with non-option arguments. +@command{gawk} do with nonoption arguments. It then proceeds to cover how @command{gawk} searches for source files, reading standard input along with other files, @command{gawk}'s environment variables, @command{gawk}'s exit status, using include files, @@ -3634,7 +3701,7 @@ enclosed in [@dots{}] in these templates are optional: @cindex GNU long options @cindex long options @cindex options, long -Besides traditional one-letter POSIX-style options, @command{gawk} also +In addition to traditional one-letter POSIX-style options, @command{gawk} also supports GNU long options. @cindex dark corner, invoking @command{awk} @@ -3697,7 +3764,7 @@ Set the @code{FS} variable to @var{fs} @cindex @option{--file} option @cindex @command{awk} programs, location of Read @command{awk} program source from @var{source-file} -instead of in the first non-option argument. +instead of in the first nonoption argument. This option may be given multiple times; the @command{awk} program consists of the concatenation of the contents of each specified @var{source-file}. @@ -3866,7 +3933,13 @@ Command-line variable assignments of the form This option is particularly necessary for World Wide Web CGI applications that pass arguments through the URL; using this option prevents a malicious (or other) user from passing in options, assignments, or @command{awk} source -code (via @option{-e}) to the CGI application. This option should be used +code (via @option{-e}) to the CGI application.@footnote{For more detail, +please see Section 4.4 of @uref{http://www.ietf.org/rfc/rfc3875, +RFC 3875}. Also see the +@uref{http://lists.gnu.org/archive/html/bug-gawk/2014-11/msg00022.html, +explanatory note sent to the @command{gawk} bug +mailing list}.} +This option should be used with @samp{#!} scripts (@pxref{Executable Scripts}), like so: @example @@ -3957,7 +4030,7 @@ care to search for all occurrences of each inappropriate construct. As @itemx @option{--bignum} @cindex @option{-M} option @cindex @option{--bignum} option -Force arbitrary precision arithmetic on numbers. This option has no effect +Force arbitrary-precision arithmetic on numbers. This option has no effect if @command{gawk} is not compiled to use the GNU MPFR and MP libraries (@pxref{Arbitrary Precision Arithmetic}). @@ -3973,10 +4046,8 @@ values in input data (@pxref{Nondecimal Data}). @quotation CAUTION -This option can severely break old programs. -Use with care. - -This option may disappear in a future version of @command{gawk}. +This option can severely break old programs. Use with care. Also note +that this option may disappear in a future version of @command{gawk}. @end quotation @item @option{-N} @@ -4008,7 +4079,7 @@ This is no longer the case. @cindex @option{--optimize} option @cindex @option{-O} option Enable some optimizations on the internal representation of the program. -At the moment this includes just simple constant folding. +At the moment, this includes just simple constant folding. @item @option{-p}[@var{file}] @itemx @option{--profile}[@code{=}@var{file}] @@ -4085,8 +4156,8 @@ Allow interval expressions (@pxref{Regexp Operators}) in regexps. This is now @command{gawk}'s default behavior. -Nevertheless, this option remains both for backward compatibility, -and for use in combination with @option{--traditional}. +Nevertheless, this option remains (both for backward compatibility +and for use in combination with @option{--traditional}). @item @option{-S} @itemx @option{--sandbox} @@ -4139,7 +4210,7 @@ If it is, @command{awk} reads its program source from all of the named files, as if they had been concatenated together into one big file. This is useful for creating libraries of @command{awk} functions. These functions can be written once and then retrieved from a standard place, instead -of having to be included into each individual program. +of having to be included in each individual program. The @option{-i} option is similar in this regard. (As mentioned in @ref{Definition Syntax}, @@ -4150,7 +4221,7 @@ if the program is entered at the keyboard, by specifying @samp{-f /dev/tty}. After typing your program, type @kbd{Ctrl-d} (the end-of-file character) to terminate it. (You may also use @samp{-f -} to read program source from the standard -input but then you will not be able to also use the standard input as a +input, but then you will not be able to also use the standard input as a source of data.) Because it is clumsy using the standard @command{awk} mechanisms to mix @@ -4163,7 +4234,7 @@ options may also be used multiple times on the command line. @cindex @option{-e} option If no @option{-f} or @option{-e} option is specified, then @command{gawk} -uses the first non-option command-line argument as the text of the +uses the first nonoption command-line argument as the text of the program source code. @cindex @env{POSIXLY_CORRECT} environment variable @@ -4230,7 +4301,7 @@ All the command-line arguments are made available to your @command{awk} program and the program text (if present) are omitted from @code{ARGV}. All other arguments, including variable assignments, are included. As each element of @code{ARGV} is processed, @command{gawk} -sets the variable @code{ARGIND} to the index in @code{ARGV} of the +sets @code{ARGIND} to the index in @code{ARGV} of the current element. @c FIXME: One day, move the ARGC and ARGV node closer to here. @@ -4410,7 +4481,7 @@ manipulate the @env{AWKPATH} variable. @code{ENVIRON["AWKPATH"]}. This provides access to the actual search path value from within an @command{awk} program. -While you can change @code{ENVIRON["AWKPATH"]} within your @command{awk} +Although you can change @code{ENVIRON["AWKPATH"]} within your @command{awk} program, this has no effect on the running program's behavior. This makes sense: the @env{AWKPATH} environment variable is used to find the program source files. Once your program is running, all the files have been @@ -4449,7 +4520,7 @@ path value from within an @command{awk} program. A number of other environment variables affect @command{gawk}'s behavior, but they are more specialized. Those in the following -list are meant to be used by regular users. +list are meant to be used by regular users: @table @env @item GAWK_MSEC_SLEEP @@ -4469,7 +4540,7 @@ retry a two-way TCP/IP (socket) connection before giving up. @xref{TCP/IP Networking}. @item POSIXLY_CORRECT -Causes @command{gawk} to switch to POSIX compatibility +Causes @command{gawk} to switch to POSIX-compatibility mode, disabling all traditional and GNU extensions. @xref{Options}. @end table @@ -4501,11 +4572,11 @@ for debugging problems on filesystems on non-POSIX operating systems where I/O is performed in records, not in blocks. @item GAWK_MSG_SRC -If this variable exists, @command{gawk} includes the file -name and line number within the @command{gawk} source code +If this variable exists, @command{gawk} includes the @value{FN} +and line number within the @command{gawk} source code from which warning and/or fatal messages are generated. Its purpose is to help isolate the source of a -message, since there are multiple places which produce the +message, as there are multiple places which produce the same warning or error message. @item GAWK_NO_DFA @@ -4549,11 +4620,11 @@ If an error occurs, @command{gawk} exits with the value of the C constant @code{EXIT_FAILURE}. This is usually one. If @command{gawk} exits because of a fatal error, the exit -status is 2. On non-POSIX systems, this value may be mapped +status is two. On non-POSIX systems, this value may be mapped to @code{EXIT_FAILURE}. @node Include Files -@section Including Other Files Into Your Program +@section Including Other Files into Your Program @c Panos Papadopoulos <panos1962@gmail.com> contributed the original @c text for this section. @@ -4602,9 +4673,9 @@ $ @kbd{gawk -f test2} @print{} This is script test2. @end example -@code{gawk} runs the @file{test2} script which includes @file{test1} +@code{gawk} runs the @file{test2} script, which includes @file{test1} using the @code{@@include} -keyword. So, to include external @command{awk} source files you just +keyword. So, to include external @command{awk} source files, you just use @code{@@include} followed by the name of the file to be included, enclosed in double quotes. @@ -4641,26 +4712,26 @@ The @value{FN} can, of course, be a pathname. For example: @end example @noindent -or: +and: @example @@include "/usr/awklib/network" @end example @noindent -are valid. The @env{AWKPATH} environment variable can be of great +are both valid. The @env{AWKPATH} environment variable can be of great value when using @code{@@include}. The same rules for the use of the @env{AWKPATH} variable in command-line file searches (@pxref{AWKPATH Variable}) apply to @code{@@include} also. This is very helpful in constructing @command{gawk} function libraries. -If you have a large script with useful, general purpose @command{awk} +If you have a large script with useful, general-purpose @command{awk} functions, you can break it down into library files and put those files in a special directory. You can then include those ``libraries,'' using either the full pathnames of the files, or by setting the @env{AWKPATH} environment variable accordingly and then using @code{@@include} with -just the file part of the full pathname. Of course you can have more +just the file part of the full pathname. Of course, you can have more than one directory to keep library files; the more complex the working environment is, the more directories you may need to organize the files to be included. @@ -4678,7 +4749,7 @@ searched first for source files, before searching in @env{AWKPATH}, and this also applies to files named with @code{@@include}. @node Loading Shared Libraries -@section Loading Dynamic Extensions Into Your Program +@section Loading Dynamic Extensions into Your Program This @value{SECTION} describes a feature that is specific to @command{gawk}. @@ -4688,7 +4759,7 @@ This @value{SECTION} describes a feature that is specific to @command{gawk}. The @code{@@load} keyword can be used to read external @command{awk} extensions (stored as system shared libraries). This allows you to link in compiled code that may offer superior -performance and/or give you access to extended capabilities not supported +performance and/or give you access to extended capabilities not supported by the @command{awk} language. The @env{AWKLIBPATH} variable is used to search for the extension. Using @code{@@load} is completely equivalent to using the @option{-l} command-line option. @@ -4696,7 +4767,7 @@ to using the @option{-l} command-line option. If the extension is not initially found in @env{AWKLIBPATH}, another search is conducted after appending the platform's default shared library suffix to the @value{FN}. For example, on GNU/Linux systems, the suffix -@samp{.so} is used. +@samp{.so} is used: @example $ @kbd{gawk '@@load "ordchr"; BEGIN @{print chr(65)@}'} @@ -4831,13 +4902,13 @@ The three standard options for all versions of @command{awk} are and many others, as well as corresponding GNU-style long options. @item -Non-option command-line arguments are usually treated as @value{FN}s, +Nonoption command-line arguments are usually treated as @value{FN}s, unless they have the form @samp{@var{var}=@var{value}}, in which case they are taken as variable assignments to be performed at that point in processing the input. @item -All non-option command-line arguments, excluding the program text, +All nonoption command-line arguments, excluding the program text, are placed in the @code{ARGV} array. Adjusting @code{ARGC} and @code{ARGV} affects how @command{awk} processes input. @@ -4886,7 +4957,7 @@ belongs to that set. The simplest regular expression is a sequence of letters, numbers, or both. Such a regexp matches any string that contains that sequence. Thus, the regexp @samp{foo} matches any string containing @samp{foo}. -Therefore, the pattern @code{/foo/} matches any input record containing +Thus, the pattern @code{/foo/} matches any input record containing the three adjacent characters @samp{foo} @emph{anywhere} in the record. Other kinds of regexps let you specify more complicated classes of strings. @@ -4949,17 +5020,16 @@ and @samp{!~} perform regular expression comparisons. Expressions using these operators can be used as patterns, or in @code{if}, @code{while}, @code{for}, and @code{do} statements. (@xref{Statements}.) -For example: +For example, the following is true if the expression @var{exp} (taken +as a string) matches @var{regexp}: @example @var{exp} ~ /@var{regexp}/ @end example @noindent -is true if the expression @var{exp} (taken as a string) -matches @var{regexp}. The following example matches, or selects, -all input records with the uppercase letter @samp{J} somewhere in the -first field: +This example matches, or selects, all input records with the uppercase +letter @samp{J} somewhere in the first field: @example $ @kbd{awk '$1 ~ /J/' inventory-shipped} @@ -5029,9 +5099,9 @@ string or regexp. Thus, the string whose contents are the two characters @samp{"} and @samp{\} must be written @code{"\"\\"}. Other escape sequences represent unprintable characters -such as TAB or newline. While there is nothing to stop you from entering most +such as TAB or newline. There is nothing to stop you from entering most unprintable characters directly in a string constant or regexp constant, -they may look ugly. +but they may look ugly. The following list presents all the escape sequences used in @command{awk} and @@ -5121,7 +5191,7 @@ A literal slash (necessary for regexp constants only). This sequence is used when you want to write a regexp constant that contains a slash (such as @code{/.*:\/home\/[[:alnum:]]+:.*/}; the @samp{[[:alnum:]]} -notation is discussed shortly, in @ref{Bracket Expressions}). +notation is discussed in @ref{Bracket Expressions}). Because the regexp is delimited by slashes, you need to escape any slash that is part of the pattern, in order to tell @command{awk} to keep processing the rest of the regexp. @@ -5144,7 +5214,7 @@ with a backslash have special meaning in regexps. In a regexp, a backslash before any character that is not in the previous list and not listed in -@ref{GNU Regexp Operators}, +@DBREF{GNU Regexp Operators} means that the next character should be taken literally, even if it would normally be a regexp operator. For example, @code{/a\+b/} matches the three characters @samp{a+b}. @@ -5155,25 +5225,7 @@ characters @samp{a+b}. For complete portability, do not use a backslash before any character not shown in the previous list and that is not an operator. -To summarize: - -@itemize @value{BULLET} -@item -The escape sequences in the list above are always processed first, -for both string constants and regexp constants. This happens very early, -as soon as @command{awk} reads your program. - -@item -@command{gawk} processes both regexp constants and dynamic regexps -(@pxref{Computed Regexps}), -for the special operators listed in -@ref{GNU Regexp Operators}. - -@item -A backslash before any other character means to treat that character -literally. -@end itemize - +@c 11/2014: Moved so as to not stack sidebars @cindex sidebar, Backslash Before Regular Characters @ifdocbook @docbook @@ -5258,6 +5310,25 @@ In such implementations, typing @code{"a\qc"} is the same as typing @end cartouche @end ifnotdocbook +To summarize: + +@itemize @value{BULLET} +@item +The escape sequences in the preceding list are always processed first, +for both string constants and regexp constants. This happens very early, +as soon as @command{awk} reads your program. + +@item +@command{gawk} processes both regexp constants and dynamic regexps +(@pxref{Computed Regexps}), +for the special operators listed in +@ref{GNU Regexp Operators}. + +@item +A backslash before any other character means to treat that character +literally. +@end itemize + @cindex sidebar, Escape Sequences for Metacharacters @ifdocbook @docbook @@ -5339,7 +5410,7 @@ sequences and that are not listed in the following stand for themselves: @cindex backslash (@code{\}), regexp operator @cindex @code{\} (backslash), regexp operator @item @code{\} -This is used to suppress the special meaning of a character when +This suppresses the special meaning of a character when matching. For example, @samp{\$} matches the character @samp{$}. @@ -5348,8 +5419,9 @@ matches the character @samp{$}. @cindex @code{^} (caret), regexp operator @cindex caret (@code{^}), regexp operator @item @code{^} -This matches the beginning of a string. For example, @samp{^@@chapter} -matches @samp{@@chapter} at the beginning of a string and can be used +This matches the beginning of a string. @samp{^@@chapter} +matches @samp{@@chapter} at the beginning of a string, +for example, and can be used to identify chapter beginnings in Texinfo source files. The @samp{^} is known as an @dfn{anchor}, because it anchors the pattern to match only at the beginning of the string. @@ -5455,7 +5527,7 @@ There are two subtle points to understand about how @samp{*} works. First, the @samp{*} applies only to the single preceding regular expression component (e.g., in @samp{ph*}, it applies just to the @samp{h}). To cause @samp{*} to apply to a larger sub-expression, use parentheses: -@samp{(ph)*} matches @samp{ph}, @samp{phph}, @samp{phphph} and so on. +@samp{(ph)*} matches @samp{ph}, @samp{phph}, @samp{phphph}, and so on. Second, @samp{*} finds as many repetitions as possible. If the text to be matched is @samp{phhhhhhhhhhhhhhooey}, @samp{ph*} matches all of @@ -5555,7 +5627,7 @@ expressions are not available in regular expressions. @cindex range expressions (regexps) @cindex character lists in regular expression -As mentioned earlier, a bracket expression matches any character amongst +As mentioned earlier, a bracket expression matches any character among those listed between the opening and closing square brackets. Within a bracket expression, a @dfn{range expression} consists of two @@ -5613,23 +5685,23 @@ a keyword denoting the class, and @samp{:]}. POSIX standard. @float Table,table-char-classes -@caption{POSIX Character Classes} +@caption{POSIX character classes} @multitable @columnfractions .15 .85 @headitem Class @tab Meaning -@item @code{[:alnum:]} @tab Alphanumeric characters. -@item @code{[:alpha:]} @tab Alphabetic characters. -@item @code{[:blank:]} @tab Space and TAB characters. -@item @code{[:cntrl:]} @tab Control characters. -@item @code{[:digit:]} @tab Numeric characters. -@item @code{[:graph:]} @tab Characters that are both printable and visible. -(A space is printable but not visible, whereas an @samp{a} is both.) -@item @code{[:lower:]} @tab Lowercase alphabetic characters. -@item @code{[:print:]} @tab Printable characters (characters that are not control characters). -@item @code{[:punct:]} @tab Punctuation characters (characters that are not letters, digits, -control characters, or space characters). -@item @code{[:space:]} @tab Space characters (such as space, TAB, and formfeed, to name a few). -@item @code{[:upper:]} @tab Uppercase alphabetic characters. -@item @code{[:xdigit:]} @tab Characters that are hexadecimal digits. +@item @code{[:alnum:]} @tab Alphanumeric characters +@item @code{[:alpha:]} @tab Alphabetic characters +@item @code{[:blank:]} @tab Space and TAB characters +@item @code{[:cntrl:]} @tab Control characters +@item @code{[:digit:]} @tab Numeric characters +@item @code{[:graph:]} @tab Characters that are both printable and visible +(a space is printable but not visible, whereas an @samp{a} is both) +@item @code{[:lower:]} @tab Lowercase alphabetic characters +@item @code{[:print:]} @tab Printable characters (characters that are not control characters) +@item @code{[:punct:]} @tab Punctuation characters (characters that are not letters, digits +control characters, or space characters) +@item @code{[:space:]} @tab Space characters (such as space, TAB, and formfeed, to name a few) +@item @code{[:upper:]} @tab Uppercase alphabetic characters +@item @code{[:xdigit:]} @tab Characters that are hexadecimal digits @end multitable @end float @@ -5644,7 +5716,7 @@ and numeric characters in your character set. @c Thanks to @c Date: Tue, 01 Jul 2014 07:39:51 +0200 @c From: Hermann Peifer <peifer@gmx.eu> -Some utilities that match regular expressions provide a non-standard +Some utilities that match regular expressions provide a nonstandard @code{[:ascii:]} character class; @command{awk} does not. However, you can simulate such a construct using @code{[\x00-\x7F]}. This matches all values numerically between zero and 127, which is the defined @@ -5835,7 +5907,7 @@ $ @kbd{awk '$0 ~ "[ \t\n]"'} @error{} ]... @error{} source line number 1 @error{} context is -@error{} $0 ~ "[ >>> \t\n]" <<< +@error{} $0 ~ "[ >>> \t\n]" <<< @end example @cindex newlines, in regexp constants @@ -5873,7 +5945,7 @@ $ @kbd{awk '$0 ~ "[ \t\n]"'} @error{} ]... @error{} source line number 1 @error{} context is -@error{} $0 ~ "[ >>> \t\n]" <<< +@error{} $0 ~ "[ >>> \t\n]" <<< @end example @cindex newlines, in regexp constants @@ -5984,9 +6056,9 @@ word-constituent characters. For example, @cindex regular expressions, operators, for buffers @cindex operators, string-matching, for buffers There are two other operators that work on buffers. In Emacs, a -@dfn{buffer} is, naturally, an Emacs buffer. For other programs, -@command{gawk}'s regexp library routines consider the entire -string to match as the buffer. +@dfn{buffer} is, naturally, an Emacs buffer. +Other GNU programs, including @command{gawk}, +consider the entire string to match as the buffer. The operators are: @table @code @@ -6047,16 +6119,16 @@ in @ref{Regexp Operators}. @end ifnottex @item @code{--posix} -Only POSIX regexps are supported; the GNU operators are not special +Match only POSIX regexps; the GNU operators are not special (e.g., @samp{\w} matches a literal @samp{w}). Interval expressions are allowed. @cindex Brian Kernighan's @command{awk} @item @code{--traditional} -Traditional Unix @command{awk} regexps are matched. The GNU operators +Match traditional Unix @command{awk} regexps. The GNU operators are not special, and interval expressions are not available. -The POSIX character classes (@samp{[[:alnum:]]}, etc.) are supported, -as BWK @command{awk} supports them. +Because BWK @command{awk} supports them, +the POSIX character classes (@samp{[[:alnum:]]}, etc.) are available. Characters described by octal and hexadecimal escape sequences are treated literally, even if they represent regexp metacharacters. @@ -6116,7 +6188,7 @@ When @code{IGNORECASE} is not zero, @emph{all} regexp and string operations ignore case. Changing the value of @code{IGNORECASE} dynamically controls the -case-sensitivity of the program as it runs. Case is significant by +case sensitivity of the program as it runs. Case is significant by default because @code{IGNORECASE} (like most variables) is initialized to zero: @@ -6129,7 +6201,7 @@ if (x ~ /ab/) @dots{} # now it will succeed @end example In general, you cannot use @code{IGNORECASE} to make certain rules -case-insensitive and other rules case-sensitive, because there is no +case insensitive and other rules case sensitive, as there is no straightforward way to set @code{IGNORECASE} just for the pattern of a particular rule.@footnote{Experienced C and C++ programmers will note @@ -6140,13 +6212,13 @@ and However, this is somewhat obscure and we don't recommend it.} To do this, use either bracket expressions or @code{tolower()}. However, one thing you can do with @code{IGNORECASE} only is dynamically turn -case-sensitivity on or off for all the rules at once. +case sensitivity on or off for all the rules at once. @code{IGNORECASE} can be set on the command line or in a @code{BEGIN} rule (@pxref{Other Arguments}; also @pxref{Using BEGIN/END}). Setting @code{IGNORECASE} from the command line is a way to make -a program case-insensitive without having to edit it. +a program case insensitive without having to edit it. @c @cindex ISO 8859-1 @c @cindex ISO Latin-1 @@ -6183,12 +6255,12 @@ in conditional expressions, or as part of matching expressions using the @samp{~} and @samp{!~} operators. @item -Escape sequences let you represent non-printable characters and +Escape sequences let you represent nonprintable characters and also let you represent regexp metacharacters as literal characters to be matched. @item -Regexp operators provide grouping, alternation and repetition. +Regexp operators provide grouping, alternation, and repetition. @item Bracket expressions give you a shorthand for specifying sets @@ -6203,8 +6275,8 @@ the match, such as for text substitution and when the record separator is a regexp. @item -Matching expressions may use dynamic regexps, that is, string values -treated as regular expressions. +Matching expressions may use dynamic regexps (i.e., string values +treated as regular expressions). @item @command{gawk}'s @code{IGNORECASE} variable lets you control the @@ -6278,7 +6350,7 @@ used with it do not have to be named on the @command{awk} command line @command{awk} divides the input for your program into records and fields. It keeps track of the number of records that have been read so far from the current input file. This value is stored in a predefined variable -called @code{FNR} which is reset to zero every time a new file is started. +called @code{FNR}, which is reset to zero every time a new file is started. Another predefined variable, @code{NR}, records the total number of input records read so far from all @value{DF}s. It starts at zero, but is never automatically reset to zero. @@ -6289,7 +6361,7 @@ never automatically reset to zero. @end menu @node awk split records -@subsection Record Splitting With Standard @command{awk} +@subsection Record Splitting with Standard @command{awk} @cindex separators, for records @cindex record separators @@ -6306,7 +6378,7 @@ the value of @code{RS} can be changed in the @command{awk} program with the assignment operator, @samp{=} (@pxref{Assignment Ops}). The new record-separator character should be enclosed in quotation marks, -which indicate a string constant. Often the right time to do this is +which indicate a string constant. Often, the right time to do this is at the beginning of execution, before any input is processed, so that the very first record is read with the proper separator. To do this, use the special @code{BEGIN} pattern @@ -6320,7 +6392,7 @@ awk 'BEGIN @{ RS = "u" @} @noindent changes the value of @code{RS} to @samp{u}, before reading any input. -This is a string whose first character is the letter ``u;'' as a result, records +This is a string whose first character is the letter ``u''; as a result, records are separated by the letter ``u.'' Then the input file is read, and the second rule in the @command{awk} program (the action with no pattern) prints each record. Because each @code{print} statement adds a newline at the end of @@ -6368,7 +6440,7 @@ $ @kbd{awk 'BEGIN @{ RS = "u" @}} @print{} m@@ny @print{} .ed @print{} R -@print{} +@print{} @end example @noindent @@ -6414,7 +6486,7 @@ being fully POSIX-compliant (@pxref{Options}). Then, the following (extreme) pipeline prints a surprising @samp{1}: @example -$ echo | gawk --posix 'BEGIN @{ RS = "a" @} ; @{ print NF @}' +$ @kbd{echo | gawk --posix 'BEGIN @{ RS = "a" @} ; @{ print NF @}'} @print{} 1 @end example @@ -6436,7 +6508,7 @@ The empty string @code{""} (a string without any characters) has a special meaning as the value of @code{RS}. It means that records are separated by one or more blank lines and nothing else. -@xref{Multiple Line}, for more details. +@DBXREF{Multiple Line} for more details. If you change the value of @code{RS} in the middle of an @command{awk} run, the new value is used to delimit subsequent records, but the record @@ -6456,7 +6528,7 @@ sets the variable @code{RT} to the text in the input that matched @code{RS}. @node gawk split records -@subsection Record Splitting With @command{gawk} +@subsection Record Splitting with @command{gawk} @cindex common extensions, @code{RS} as a regexp @cindex extensions, common@comma{} @code{RS} as a regexp @@ -6500,11 +6572,11 @@ $ @kbd{echo record 1 AAAA record 2 BBBB record 3 |} The square brackets delineate the contents of @code{RT}, letting you see the leading and trailing whitespace. The final value of @code{RT} is a newline. -@xref{Simple Sed}, for a more useful example +@DBXREF{Simple Sed} for a more useful example of @code{RS} as a regexp and @code{RT}. If you set @code{RS} to a regular expression that allows optional -trailing text, such as @samp{RS = "abc(XYZ)?"} it is possible, due +trailing text, such as @samp{RS = "abc(XYZ)?"}, it is possible, due to implementation constraints, that @command{gawk} may match the leading part of the regular expression, but not the trailing part, particularly if the input text that could match the trailing part is fairly long. @@ -6518,7 +6590,7 @@ the beginning and end of a @emph{line}. As a result, something like @samp{RS = "^[[:upper:]]"} can only match at the beginning of a file. This is because @command{gawk} views the input file as one long string that happens to contain newline characters. -It is thus best to avoid anchor characters in the value of @code{RS}. +It is thus best to avoid anchor metacharacters in the value of @code{RS}. @end quotation @cindex differences in @command{awk} and @command{gawk}, @code{RS}/@code{RT} variables @@ -6572,9 +6644,9 @@ character as a record separator. However, this is a special case: @cindex records, treating files as @cindex treating files, as single records -@xref{Readfile Function}, for an interesting way to read -whole files. If you are using @command{gawk}, see @ref{Extension Sample -Readfile}, for another option. +@DBXREF{Readfile Function} for an interesting way to read +whole files. If you are using @command{gawk}, see @DBREF{Extension Sample +Readfile} for another option. @docbook </sidebar> @@ -6623,9 +6695,9 @@ character as a record separator. However, this is a special case: @cindex records, treating files as @cindex treating files, as single records -@xref{Readfile Function}, for an interesting way to read -whole files. If you are using @command{gawk}, see @ref{Extension Sample -Readfile}, for another option. +@DBXREF{Readfile Function} for an interesting way to read +whole files. If you are using @command{gawk}, see @DBREF{Extension Sample +Readfile} for another option. @end cartouche @end ifnotdocbook @c ENDOFRANGE inspl @@ -6648,9 +6720,9 @@ called @dfn{fields}. By default, fields are separated by @dfn{whitespace}, like words in a line. Whitespace in @command{awk} means any string of one or more spaces, TABs, or newlines;@footnote{In POSIX @command{awk}, newlines are not -considered whitespace for separating fields.} other characters, such as -formfeed, vertical tab, etc., that are -considered whitespace by other languages, are @emph{not} considered +considered whitespace for separating fields.} other characters +that are considered whitespace by other languages +(such as formfeed, vertical tab, etc.) are @emph{not} considered whitespace by @command{awk}. The purpose of fields is to make it more convenient for you to refer to @@ -6667,7 +6739,7 @@ to refer to a field in an @command{awk} program, followed by the number of the field you want. Thus, @code{$1} refers to the first field, @code{$2} to the second, and so on. (Unlike the Unix shells, the field numbers are not limited to single digits. -@code{$127} is the one hundred twenty-seventh field in the record.) +@code{$127} is the 127th field in the record.) For example, suppose the following is a line of input: @example @@ -6737,7 +6809,7 @@ awk '@{ print $NR @}' @noindent Recall that @code{NR} is the number of records read so far: one in the -first record, two in the second, etc. So this example prints the first +first record, two in the second, and so on. So this example prints the first field of the first record, the second field of the second record, and so on. For the twentieth record, field number 20 is printed; most likely, the record has fewer than 20 fields, so this prints a blank line. @@ -6754,7 +6826,7 @@ The parentheses are used so that the multiplication is done before the @samp{$} operation; they are necessary whenever there is a binary operator@footnote{A @dfn{binary operator}, such as @samp{*} for multiplication, is one that takes two operands. The distinction -is required, since @command{awk} also has unary (one-operand) +is required, because @command{awk} also has unary (one-operand) and ternary (three-operand) operators.} in the field-number expression. This example, then, prints the type of relationship (the fourth field) for every line of the file @@ -6828,7 +6900,7 @@ $ @kbd{awk '@{ $2 = $2 - 10; print $0 @}' inventory-shipped} @dots{} @end example -It is also possible to also assign contents to fields that are out +It is also possible to assign contents to fields that are out of range. For example: @example @@ -6879,9 +6951,9 @@ else @noindent should print @samp{everything is normal}, because @code{NF+1} is certain -to be out of range. (@xref{If Statement}, +to be out of range. (@DBXREF{If Statement} for more information about @command{awk}'s @code{if-else} statements. -@xref{Typing and Comparison}, +@DBXREF{Typing and Comparison} for more information about the @samp{!=} operator.) It is important to note that making an assignment to an existing field @@ -6921,8 +6993,8 @@ after the new value of @code{NF} and recomputes @code{$0}. Here is an example: @example -$ echo a b c d e f | awk '@{ print "NF =", NF; -> NF = 3; print $0 @}' +$ @kbd{echo a b c d e f | awk '@{ print "NF =", NF;} +> @kbd{ NF = 3; print $0 @}'} @print{} NF = 6 @print{} a b c @end example @@ -6971,7 +7043,7 @@ in a record simply by setting @code{FS} and @code{OFS}, and then expecting a plain @samp{print} or @samp{print $0} to print the modified record. -But this does not work, since nothing was done to change the record +But this does not work, because nothing was done to change the record itself. Instead, you must force the record to be rebuilt, typically with a statement such as @samp{$1 = $1}, as described earlier. @@ -6996,7 +7068,7 @@ in a record simply by setting @code{FS} and @code{OFS}, and then expecting a plain @samp{print} or @samp{print $0} to print the modified record. -But this does not work, since nothing was done to change the record +But this does not work, because nothing was done to change the record itself. Instead, you must force the record to be rebuilt, typically with a statement such as @samp{$1 = $1}, as described earlier. @end cartouche @@ -7049,7 +7121,7 @@ the Unix Bourne shell, @command{sh}, or Bash). @cindex @code{FS} variable, changing value of The value of @code{FS} can be changed in the @command{awk} program with the assignment operator, @samp{=} (@pxref{Assignment Ops}). -Often the right time to do this is at the beginning of execution +Often, the right time to do this is at the beginning of execution before any input has been processed, so that the very first record is read with the proper separator. To do this, use the special @code{BEGIN} pattern @@ -7205,7 +7277,7 @@ statement prints the new @code{$0}. @cindex dark corner, @code{^}, in @code{FS} There is an additional subtlety to be aware of when using regular expressions for field splitting. -It is not well-specified in the POSIX standard, or anywhere else, what @samp{^} +It is not well specified in the POSIX standard, or anywhere else, what @samp{^} means when splitting fields. Does the @samp{^} match only at the beginning of the entire record? Or is each field separator a new string? It turns out that different @command{awk} versions answer this question differently, and you @@ -7371,11 +7443,11 @@ awk -F: '$5 == ""' /etc/passwd @end example @node Full Line Fields -@subsection Making The Full Line Be A Single Field +@subsection Making the Full Line Be a Single Field Occasionally, it's useful to treat the whole input line as a single field. This can be done easily and portably simply by -setting @code{FS} to @code{"\n"} (a newline).@footnote{Thanks to +setting @code{FS} to @code{"\n"} (a newline):@footnote{Thanks to Andrew Schorr for this tip.} @example @@ -7385,42 +7457,6 @@ awk -F'\n' '@var{program}' @var{files @dots{}} @noindent When you do this, @code{$1} is the same as @code{$0}. -@node Field Splitting Summary -@subsection Field-Splitting Summary - -It is important to remember that when you assign a string constant -as the value of @code{FS}, it undergoes normal @command{awk} string -processing. For example, with Unix @command{awk} and @command{gawk}, -the assignment @samp{FS = "\.."} assigns the character string @code{".."} -to @code{FS} (the backslash is stripped). This creates a regexp meaning -``fields are separated by occurrences of any two characters.'' -If instead you want fields to be separated by a literal period followed -by any single character, use @samp{FS = "\\.."}. - -The following list summarizes how fields are split, based on the value -of @code{FS} (@samp{==} means ``is equal to''): - -@table @code -@item FS == " " -Fields are separated by runs of whitespace. Leading and trailing -whitespace are ignored. This is the default. - -@item FS == @var{any other single character} -Fields are separated by each occurrence of the character. Multiple -successive occurrences delimit empty fields, as do leading and -trailing occurrences. -The character can even be a regexp metacharacter; it does not need -to be escaped. - -@item FS == @var{regexp} -Fields are separated by occurrences of characters that match @var{regexp}. -Leading and trailing matches of @var{regexp} delimit empty fields. - -@item FS == "" -Each individual character in the record becomes a separate field. -(This is a common extension; it is not specified by the POSIX standard.) -@end table - @cindex sidebar, Changing @code{FS} Does Not Affect the Fields @ifdocbook @docbook @@ -7467,7 +7503,7 @@ on an incorrect implementation of @command{awk}, while @command{gawk} prints the full first line of the file, something like: @example -root:nSijPlPhZZwgE:0:0:Root:/: +root:x:0:0:Root:/: @end example @docbook @@ -7520,11 +7556,47 @@ on an incorrect implementation of @command{awk}, while @command{gawk} prints the full first line of the file, something like: @example -root:nSijPlPhZZwgE:0:0:Root:/: +root:x:0:0:Root:/: @end example @end cartouche @end ifnotdocbook +@node Field Splitting Summary +@subsection Field-Splitting Summary + +It is important to remember that when you assign a string constant +as the value of @code{FS}, it undergoes normal @command{awk} string +processing. For example, with Unix @command{awk} and @command{gawk}, +the assignment @samp{FS = "\.."} assigns the character string @code{".."} +to @code{FS} (the backslash is stripped). This creates a regexp meaning +``fields are separated by occurrences of any two characters.'' +If instead you want fields to be separated by a literal period followed +by any single character, use @samp{FS = "\\.."}. + +The following list summarizes how fields are split, based on the value +of @code{FS} (@samp{==} means ``is equal to''): + +@table @code +@item FS == " " +Fields are separated by runs of whitespace. Leading and trailing +whitespace are ignored. This is the default. + +@item FS == @var{any other single character} +Fields are separated by each occurrence of the character. Multiple +successive occurrences delimit empty fields, as do leading and +trailing occurrences. +The character can even be a regexp metacharacter; it does not need +to be escaped. + +@item FS == @var{regexp} +Fields are separated by occurrences of characters that match @var{regexp}. +Leading and trailing matches of @var{regexp} delimit empty fields. + +@item FS == "" +Each individual character in the record becomes a separate field. +(This is a common extension; it is not specified by the POSIX standard.) +@end table + @cindex sidebar, @code{FS} and @code{IGNORECASE} @ifdocbook @docbook @@ -7548,7 +7620,7 @@ print $1 @noindent The output is @samp{aCa}. If you really want to split fields on an alphabetic character while ignoring case, use a regexp that will -do it for you. E.g., @samp{FS = "[c]"}. In this case, @code{IGNORECASE} +do it for you (e.g., @samp{FS = "[c]"}). In this case, @code{IGNORECASE} will take effect. @docbook @@ -7578,7 +7650,7 @@ print $1 @noindent The output is @samp{aCa}. If you really want to split fields on an alphabetic character while ignoring case, use a regexp that will -do it for you. E.g., @samp{FS = "[c]"}. In this case, @code{IGNORECASE} +do it for you (e.g., @samp{FS = "[c]"}). In this case, @code{IGNORECASE} will take effect. @end cartouche @end ifnotdocbook @@ -7589,20 +7661,20 @@ will take effect. @node Constant Size @section Reading Fixed-Width Data -@quotation NOTE +@cindex data, fixed-width +@cindex fixed-width data +@cindex advanced features, fixed-width data + +@c O'Reilly doesn't like it as a note the first thing in the section. This @value{SECTION} discusses an advanced feature of @command{gawk}. If you are a novice @command{awk} user, you might want to skip it on the first reading. -@end quotation -@cindex data, fixed-width -@cindex fixed-width data -@cindex advanced features, fixed-width data -@command{gawk} provides a facility for dealing with -fixed-width fields with no distinctive field separator. For example, -data of this nature arises in the input for old Fortran programs where -numbers are run together, or in the output of programs that did not -anticipate the use of their output as input for other programs. +@command{gawk} provides a facility for dealing with fixed-width fields +with no distinctive field separator. For example, data of this nature +arises in the input for old Fortran programs where numbers are run +together, or in the output of programs that did not anticipate the use +of their output as input for other programs. An example of the latter is a table where all the columns are lined up by the use of a variable number of spaces and @emph{empty fields are just @@ -7641,15 +7713,10 @@ dave ttyq4 26Jun9115days 46 46 wnewmail @end group @end example -The following program takes the above input, converts the idle time to +The following program takes this input, converts the idle time to number of seconds, and prints out the first two fields and the calculated idle time: -@quotation NOTE -This program uses a number of @command{awk} features that -haven't been introduced yet. -@end quotation - @example BEGIN @{ FIELDWIDTHS = "9 6 10 6 7 7 35" @} NR > 2 @{ @@ -7668,6 +7735,11 @@ NR > 2 @{ @} @end example +@quotation NOTE +The preceding program uses a number of @command{awk} features that +haven't been introduced yet. +@end quotation + Running the program on the data produces the following results: @example @@ -7713,17 +7785,16 @@ else This information is useful when writing a function that needs to temporarily change @code{FS} or @code{FIELDWIDTHS}, read some records, and then restore the original settings -(@pxref{Passwd Functions}, +(@DBPXREF{Passwd Functions} for an example of such a function). @node Splitting By Content -@section Defining Fields By Content +@section Defining Fields by Content -@quotation NOTE +@c O'Reilly doesn't like it as a note the first thing in the section. This @value{SECTION} discusses an advanced feature of @command{gawk}. If you are a novice @command{awk} user, you might want to skip it on the first reading. -@end quotation @cindex advanced features, specifying field content Normally, when using @code{FS}, @command{gawk} defines the fields as the @@ -7734,14 +7805,16 @@ However, there are times when you really want to define the fields by what they are, and not by what they are not. The most notorious such case -is so-called @dfn{comma separated value} (CSV) data. Many spreadsheet programs, +is so-called @dfn{comma-separated values} (CSV) data. Many spreadsheet programs, for example, can export their data into text files, where each record is terminated with a newline, and fields are separated by commas. If only commas separated the data, there wouldn't be an issue. The problem comes when -one of the fields contains an @emph{embedded} comma. While there is no -formal standard specification for CSV data@footnote{At least, we don't know of one.}, -in such cases, most programs embed the field in double quotes. So we might -have data like this: +one of the fields contains an @emph{embedded} comma. +In such cases, most programs embed the field in double quotes.@footnote{The +CSV format lacked a formal standard definition for many years. +@uref{http://www.ietf.org/rfc/rfc4180.txt, RFC 4180} +standardizes the most common practices.} +So we might have data like this: @example @c file eg/misc/addresses.csv @@ -7755,7 +7828,7 @@ The @code{FPAT} variable offers a solution for cases like this. The value of @code{FPAT} should be a string that provides a regular expression. This regular expression describes the contents of each field. -In the case of CSV data as presented above, each field is either ``anything that +In the case of CSV data as presented here, each field is either ``anything that is not a comma,'' or ``a double quote, anything that is not a double quote, and a closing double quote.'' If written as a regular expression constant (@pxref{Regexp}), @@ -7820,10 +7893,10 @@ will be @code{"FPAT"} if content-based field splitting is being used. @quotation NOTE Some programs export CSV data that contains embedded newlines between the double quotes. @command{gawk} provides no way to deal with this. -Since there is no formal specification for CSV data, there isn't much +Even though a formal specification for CSV data exists, there isn't much more to be done; the @code{FPAT} mechanism provides an elegant solution for the majority -of cases, and the @command{gawk} developers are satisfied with that. +of cases, and the @command{gawk} developers are satisfied with that. @end quotation As written, the regexp used for @code{FPAT} requires that each field @@ -7977,7 +8050,7 @@ $ @kbd{awk -f addrs.awk addresses} @dots{} @end example -@xref{Labels Program}, for a more realistic program that deals with +@DBXREF{Labels Program} for a more realistic program dealing with address lists. The following list summarizes how records are split, based on the value of @ifinfo @@ -8072,7 +8145,7 @@ represents a shell command. @quotation NOTE When @option{--sandbox} is specified (@pxref{Options}), -reading lines from files, pipes and coprocesses is disabled. +reading lines from files, pipes, and coprocesses is disabled. @end quotation @menu @@ -8215,7 +8288,7 @@ free @end example The @code{getline} command used in this way sets only the variables -@code{NR}, @code{FNR} and @code{RT} (and of course, @var{var}). +@code{NR}, @code{FNR}, and @code{RT} (and of course, @var{var}). The record is not split into fields, so the values of the fields (including @code{$0}) and the value of @code{NF} do not change. @@ -8269,7 +8342,7 @@ you want your program to be portable to all @command{awk} implementations. Use @samp{getline @var{var} < @var{file}} to read input from the file -@var{file}, and put it in the variable @var{var}. As above, @var{file} +@var{file}, and put it in the variable @var{var}. As earlier, @var{file} is a string-valued expression that specifies the file from which to read. In this version of @code{getline}, none of the predefined variables are @@ -8305,7 +8378,7 @@ One deficiency of this program is that it does not process nested @code{@@include} statements (i.e., @code{@@include} statements in included files) the way a true macro preprocessor would. -@xref{Igawk Program}, for a program +@DBXREF{Igawk Program} for a program that does handle nested @code{@@include} statements. @node Getline/Pipe @@ -8552,7 +8625,7 @@ Using @code{FILENAME} with @code{getline} is likely to be a source for confusion. @command{awk} opens a separate input stream from the current input file. However, by not using a variable, @code{$0} -and @code{NR} are still updated. If you're doing this, it's +and @code{NF} are still updated. If you're doing this, it's probably by accident, and you should reconsider what it is you're trying to accomplish. @@ -8604,7 +8677,7 @@ and whether the variant is standard or a @command{gawk} extension. Note: for each variant, @command{gawk} sets the @code{RT} predefined variable. @float Table,table-getline-variants -@caption{@code{getline} Variants and What They Set} +@caption{@code{getline} variants and what they set} @multitable @columnfractions .33 .38 .27 @headitem Variant @tab Effect @tab @command{awk} / @command{gawk} @item @code{getline} @tab Sets @code{$0}, @code{NF}, @code{FNR}, @code{NR}, and @code{RT} @tab @command{awk} @@ -8622,7 +8695,7 @@ Note: for each variant, @command{gawk} sets the @code{RT} predefined variable. @c ENDOFRANGE infir @node Read Timeout -@section Reading Input With A Timeout +@section Reading Input with a Timeout @cindex timeout, reading input @cindex differences in @command{awk} and @command{gawk}, read timeouts @@ -8630,7 +8703,7 @@ This @value{SECTION} describes a feature that is specific to @command{gawk}. You may specify a timeout in milliseconds for reading input from the keyboard, a pipe, or two-way communication, including TCP/IP sockets. This can be done -on a per input, command or connection basis, by setting a special element +on a per input, command, or connection basis, by setting a special element in the @code{PROCINFO} array (@pxref{Auto-set}): @example @@ -8695,7 +8768,7 @@ for the input to arrive: PROCINFO[Service, "READ_TIMEOUT"] = 1000 while ((Service |& getline) > 0) @{ print $0 - PROCINFO[S, "READ_TIMEOUT"] -= 100 + PROCINFO[Service, "READ_TIMEOUT"] -= 100 @} @end example @@ -8704,11 +8777,11 @@ You should not assume that the read operation will block exactly after the tenth record has been printed. It is possible that @command{gawk} will read and buffer more than one record's worth of data the first time. Because of this, changing the value -of timeout like in the above example is not very useful. +of timeout like in the preceding example is not very useful. @end quotation -If the @code{PROCINFO} element is not present and the environment -variable @env{GAWK_READ_TIMEOUT} exists, +If the @code{PROCINFO} element is not present and the +@env{GAWK_READ_TIMEOUT} environment variable exists, @command{gawk} uses its value to initialize the timeout value. The exclusive use of the environment variable to specify timeout has the disadvantage of not being able to control it @@ -8729,7 +8802,7 @@ or the attempt to open a FIFO special file for reading can block indefinitely until some other process opens it for writing. @node Command-line directories -@section Directories On The Command Line +@section Directories on the Command Line @cindex differences in @command{awk} and @command{gawk}, command-line directories @cindex directories, command-line @cindex command line, directories on @@ -8744,14 +8817,14 @@ command line, but otherwise ignores it. This makes it easier to use shell wildcards with your @command{awk} program: @example -$ @kbd{gawk -f whizprog.awk *} @ii{Directories could kill this progam} +$ @kbd{gawk -f whizprog.awk *} @ii{Directories could kill this program} @end example If either of the @option{--posix} or @option{--traditional} options is given, then @command{gawk} reverts to treating a directory on the command line as a fatal error. -@xref{Extension Sample Readdir}, for a way to treat directories +@DBXREF{Extension Sample Readdir} for a way to treat directories as usable data from an @command{awk} program. @node Input Summary @@ -8763,7 +8836,7 @@ Input is split into records based on the value of @code{RS}. The possibilities are as follows: @multitable @columnfractions .25 .35 .40 -@headitem Value of @code{RS} @tab Records are split on @tab @command{awk} / @command{gawk} +@headitem Value of @code{RS} @tab Records are split on @dots{} @tab @command{awk} / @command{gawk} @item Any single character @tab That character @tab @command{awk} @item The empty string (@code{""}) @tab Runs of two or more newlines @tab @command{awk} @item A regexp @tab Text that matches the regexp @tab @command{gawk} @@ -8778,7 +8851,7 @@ The possibilities are as follows: @item After splitting the input into records, @command{awk} further splits -the record into individual fields, named @code{$1}, @code{$2} and so +the record into individual fields, named @code{$1}, @code{$2}, and so on. @code{$0} is the whole record, and @code{NF} indicates how many fields there are. The default way to split fields is between whitespace characters. @@ -8792,7 +8865,7 @@ greater than @code{NF} creates the field and rebuilds the record, using thing. Decrementing @code{NF} throws away fields and rebuilds the record. @item -Field splitting is more complicated than record splitting. +Field splitting is more complicated than record splitting: @multitable @columnfractions .40 .45 .15 @headitem Field separator value @tab Fields are split @dots{} @tab @command{awk} / @command{gawk} @@ -8865,7 +8938,7 @@ The @code{print} statement is not limited when computing @emph{which} values to print. However, with two exceptions, you cannot specify @emph{how} to print them---how many columns, whether to use exponential notation or not, and so on. -(For the exceptions, @pxref{Output Separators}, and +(For the exceptions, @DBPXREF{Output Separators} and @ref{OFMT}.) For printing with specifications, you need the @code{printf} statement (@pxref{Printf}). @@ -9062,14 +9135,14 @@ separated by single spaces. However, this doesn't need to be the case; a single space is simply the default. Any string of characters may be used as the @dfn{output field separator} by setting the predefined variable @code{OFS}. The initial value of this variable -is the string @w{@code{" "}}---that is, a single space. +is the string @w{@code{" "}} (i.e., a single space). -The output from an entire @code{print} statement is called an -@dfn{output record}. Each @code{print} statement outputs one output -record, and then outputs a string called the @dfn{output record separator} -(or @code{ORS}). The initial -value of @code{ORS} is the string @code{"\n"}; i.e., a newline -character. Thus, each @code{print} statement normally makes a separate line. +The output from an entire @code{print} statement is called an @dfn{output +record}. Each @code{print} statement outputs one output record, and +then outputs a string called the @dfn{output record separator} (or +@code{ORS}). The initial value of @code{ORS} is the string @code{"\n"} +(i.e., a newline character). Thus, each @code{print} statement normally +makes a separate line. @cindex output, records @cindex output record separator, See @code{ORS} variable @@ -9092,27 +9165,27 @@ newline: $ @kbd{awk 'BEGIN @{ OFS = ";"; ORS = "\n\n" @}} > @kbd{@{ print $1, $2 @}' mail-list} @print{} Amelia;555-5553 -@print{} +@print{} @print{} Anthony;555-3412 -@print{} +@print{} @print{} Becky;555-7685 -@print{} +@print{} @print{} Bill;555-1675 -@print{} +@print{} @print{} Broderick;555-0542 -@print{} +@print{} @print{} Camilla;555-2912 -@print{} +@print{} @print{} Fabius;555-1234 -@print{} +@print{} @print{} Julie;555-6699 -@print{} +@print{} @print{} Martin;555-6480 -@print{} +@print{} @print{} Samuel;555-3430 -@print{} +@print{} @print{} Jean-Paul;555-2127 -@print{} +@print{} @end example If the value of @code{ORS} does not contain a newline, the program's output @@ -9193,7 +9266,7 @@ printf @var{format}, @var{item1}, @var{item2}, @dots{} @end example @noindent -As print @code{print}, the entire list of arguments may optionally be +As for @code{print}, the entire list of arguments may optionally be enclosed in parentheses. Here too, the parentheses are necessary if any of the item expressions use the @samp{>} relational operator; otherwise, it can be confused with an output redirection (@pxref{Redirection}). @@ -9226,7 +9299,7 @@ $ @kbd{awk 'BEGIN @{} @end example @noindent -Here, neither the @samp{+} nor the @samp{OUCH} appear in +Here, neither the @samp{+} nor the @samp{OUCH!} appear in the output message. @node Control Letters @@ -9270,7 +9343,7 @@ a single byte (0--255). @item @code{%d}, @code{%i} Print a decimal integer. The two control letters are equivalent. -(The @code{%i} specification is for compatibility with ISO C.) +(The @samp{%i} specification is for compatibility with ISO C.) @item @code{%e}, @code{%E} Print a number in scientific (exponential) notation; @@ -9285,7 +9358,7 @@ prints @samp{1.950e+03}, with a total of four significant figures, three of which follow the decimal point. (The @samp{4.3} represents two modifiers, discussed in the next @value{SUBSECTION}.) -@code{%E} uses @samp{E} instead of @samp{e} in the output. +@samp{%E} uses @samp{E} instead of @samp{e} in the output. @item @code{%f} Print a number in floating-point notation. @@ -9301,26 +9374,26 @@ which follow the decimal point. (The @samp{4.3} represents two modifiers, discussed in the next @value{SUBSECTION}.) -On systems supporting IEEE 754 floating point format, values +On systems supporting IEEE 754 floating-point format, values representing negative infinity are formatted as @samp{-inf} or @samp{-infinity}, and positive infinity as -@samp{inf} and @samp{infinity}. +@samp{inf} or @samp{infinity}. The special ``not a number'' value formats as @samp{-nan} or @samp{nan} (@pxref{Math Definitions}). @item @code{%F} -Like @code{%f} but the infinity and ``not a number'' values are spelled +Like @samp{%f} but the infinity and ``not a number'' values are spelled using uppercase letters. -The @code{%F} format is a POSIX extension to ISO C; not all systems -support it. On those that don't, @command{gawk} uses @code{%f} instead. +The @samp{%F} format is a POSIX extension to ISO C; not all systems +support it. On those that don't, @command{gawk} uses @samp{%f} instead. @item @code{%g}, @code{%G} Print a number in either scientific notation or in floating-point notation, whichever uses fewer characters; if the result is printed in -scientific notation, @code{%G} uses @samp{E} instead of @samp{e}. +scientific notation, @samp{%G} uses @samp{E} instead of @samp{e}. @item @code{%o} Print an unsigned octal integer @@ -9332,11 +9405,11 @@ Print a string. @item @code{%u} Print an unsigned decimal integer. (This format is of marginal use, because all numbers in @command{awk} -are floating-point; it is provided primarily for compatibility with C.) +are floating point; it is provided primarily for compatibility with C.) @item @code{%x}, @code{%X} Print an unsigned hexadecimal integer; -@code{%X} uses the letters @samp{A} through @samp{F} +@samp{%X} uses the letters @samp{A} through @samp{F} instead of @samp{a} through @samp{f} (@pxref{Nondecimal-numbers}). @@ -9351,7 +9424,7 @@ argument and it ignores any modifiers. @quotation NOTE When using the integer format-control letters for values that are outside the range of the widest C integer type, @command{gawk} switches to -the @code{%g} format specifier. If @option{--lint} is provided on the +the @samp{%g} format specifier. If @option{--lint} is provided on the command line (@pxref{Options}), @command{gawk} warns about this. Other versions of @command{awk} may print invalid values or do something else entirely. @@ -9400,7 +9473,7 @@ messages at runtime. which describes how and why to use positional specifiers. For now, we ignore them. -@item - +@item - (Minus) The minus sign, used before the width modifier (see later on in this list), says to left-justify @@ -9425,13 +9498,13 @@ says to always supply a sign for numeric conversions, even if the data to format is positive. The @samp{+} overrides the space modifier. @item # -Use an ``alternate form'' for certain control letters. -For @code{%o}, supply a leading zero. -For @code{%x} and @code{%X}, supply a leading @code{0x} or @samp{0X} for +Use an ``alternative form'' for certain control letters. +For @samp{%o}, supply a leading zero. +For @samp{%x} and @samp{%X}, supply a leading @samp{0x} or @samp{0X} for a nonzero result. -For @code{%e}, @code{%E}, @code{%f}, and @code{%F}, the result always +For @samp{%e}, @samp{%E}, @samp{%f}, and @samp{%F}, the result always contains a decimal point. -For @code{%g} and @code{%G}, trailing zeros are not removed from the result. +For @samp{%g} and @samp{%G}, trailing zeros are not removed from the result. @item 0 A leading @samp{0} (zero) acts as a flag indicating that output should be @@ -9442,7 +9515,7 @@ value to print. @item ' A single quote or apostrophe character is a POSIX extension to ISO C. -It indicates that the integer part of a floating point value, or the +It indicates that the integer part of a floating-point value, or the entire part of an integer decimal value, should have a thousands-separator character in it. This only works in locales that support such characters. For example: @@ -9523,7 +9596,7 @@ prints @samp{foob}. @end table The C library @code{printf}'s dynamic @var{width} and @var{prec} -capability (for example, @code{"%*.*s"}) is supported. Instead of +capability (e.g., @code{"%*.*s"}) is supported. Instead of supplying explicit @var{width} and/or @var{prec} values in the format string, they are passed in the argument list. For example: @@ -9623,7 +9696,7 @@ awk 'BEGIN @{ print "Name Number" @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example -The above example mixes @code{print} and @code{printf} statements in +The preceding example mixes @code{print} and @code{printf} statements in the same program. Using just @code{printf} statements can produce the same results: @@ -9770,7 +9843,7 @@ close(report) The @code{close()} function is called here because it's a good idea to close the pipe as soon as all the intended output has been sent to it. -@xref{Close Files And Pipes}, +@DBXREF{Close Files And Pipes} for more information. This example also illustrates the use of a variable to represent @@ -9794,9 +9867,9 @@ but subsidiary to, the @command{awk} program. This feature is a @command{gawk} extension, and is not available in POSIX @command{awk}. -@xref{Getline/Coprocess}, +@DBXREF{Getline/Coprocess} for a brief discussion. -@xref{Two-way I/O}, +@DBXREF{Two-way I/O} for a more complete discussion. @end table @@ -9820,7 +9893,7 @@ print "Avoid improbability generators" >> "guide.txt" @noindent This is indeed how redirections must be used from the shell. But in @command{awk}, it isn't necessary. In this kind of case, a program should -use @samp{>} for all the @code{print} statements, since the output file +use @samp{>} for all the @code{print} statements, because the output file is only opened once. (It happens that if you mix @samp{>} and @samp{>>} that output is produced in the expected order. However, mixing the operators for the same file is definitely poor style, and is confusing to readers @@ -9874,7 +9947,7 @@ The program builds up a list of command lines, using the @command{mv} utility to rename the files. It then sends the list to the shell for execution. -@xref{Shell Quoting}, for a function that can help in generating +@DBXREF{Shell Quoting} for a function that can help in generating command lines to be fed to the shell. @docbook @@ -9909,7 +9982,7 @@ The program builds up a list of command lines, using the @command{mv} utility to rename the files. It then sends the list to the shell for execution. -@xref{Shell Quoting}, for a function that can help in generating +@DBXREF{Shell Quoting} for a function that can help in generating command lines to be fed to the shell. @end cartouche @end ifnotdocbook @@ -9975,7 +10048,7 @@ that happens, writing to the screen is not correct. In fact, if terminal at all. Then opening @file{/dev/tty} fails. -@command{gawk}, BWK @command{awk} and @command{mawk} provide +@command{gawk}, BWK @command{awk}, and @command{mawk} provide special @value{FN}s for accessing the three standard streams. If the @value{FN} matches one of these special names when @command{gawk} (or one of the others) redirects input or output, then it directly uses @@ -10018,7 +10091,7 @@ It is a common error to omit the quotes, which leads to confusing results. @command{gawk} does not treat these @value{FN}s as special when -in POSIX compatibility mode. However, since BWK @command{awk} +in POSIX-compatibility mode. However, because BWK @command{awk} supports them, @command{gawk} does support them even when invoked with the @option{--traditional} option (@pxref{Options}). @@ -10027,7 +10100,7 @@ invoked with the @option{--traditional} option (@pxref{Options}). @c STARTOFRANGE gfn @cindex @command{gawk}, file names in -Besides access to standard input, stanard output, and standard error, +Besides access to standard input, standard output, and standard error, @command{gawk} provides access to any open file descriptor. Additionally, there are special @value{FN}s reserved for TCP/IP networking. @@ -10076,7 +10149,7 @@ This is done using a special @value{FN} of the form: @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}} @end example -The @var{net-type} is one of @samp{inet}, @samp{inet4} or @samp{inet6}. +The @var{net-type} is one of @samp{inet}, @samp{inet4}, or @samp{inet6}. The @var{protocol} is one of @samp{tcp} or @samp{udp}, and the other fields represent the other essential pieces of information for making a networking connection. @@ -10265,7 +10338,7 @@ is not closed and released until @code{close()} is called or @command{awk} exits. @code{close()} silently does nothing if given an argument that -does not represent a file, pipe or coprocess that was opened with +does not represent a file, pipe, or coprocess that was opened with a redirection. In such a case, it returns a negative value, indicating an error. In addition, @command{gawk} sets @code{ERRNO} to a string indicating the error. @@ -10304,9 +10377,10 @@ which describes it in more detail and gives an example. @cindex Unix @command{awk}, @code{close()} function and In many older versions of Unix @command{awk}, the @code{close()} function -is actually a statement. It is a syntax error to try and use the return -value from @code{close()}: +is actually a statement. @value{DARKCORNER} +It is a syntax error to try and use the return +value from @code{close()}: @example command = "@dots{}" @@ -10360,9 +10434,10 @@ when closing a pipe. @cindex Unix @command{awk}, @code{close()} function and In many older versions of Unix @command{awk}, the @code{close()} function -is actually a statement. It is a syntax error to try and use the return -value from @code{close()}: +is actually a statement. @value{DARKCORNER} +It is a syntax error to try and use the return +value from @code{close()}: @example command = "@dots{}" @@ -10426,11 +10501,11 @@ Output from both @code{print} and @code{printf} may be redirected to files, pipes, and coprocesses. @item -@command{gawk} provides special file names for access to standard input, -output and error, and for network communications. +@command{gawk} provides special @value{FN}s for access to standard input, +output, and error, and for network communications. @item -Use @code{close()} to close open file, pipe and coprocess redirections. +Use @code{close()} to close open file, pipe, and coprocess redirections. For coprocesses, it is possible to close only one direction of the communications. @@ -10498,7 +10573,7 @@ combinations of these with various operators. @end menu @node Values -@section Constants, Variables and Conversions +@section Constants, Variables, and Conversions Expressions are built up from values and the operations performed upon them. This @value{SECTION} describes the elementary objects @@ -10524,7 +10599,7 @@ string, and regular expression. Each is used in the appropriate context when you need a data value that isn't going to change. Numeric constants can -have different forms, but are stored identically internally. +have different forms, but are internally stored in an identical manner. @menu * Scalar Constants:: Numeric and string constants. @@ -10540,7 +10615,7 @@ have different forms, but are stored identically internally. A @dfn{numeric constant} stands for a number. This number can be an integer, a decimal fraction, or a number in scientific (exponential) notation.@footnote{The internal representation of all numbers, -including integers, uses double precision floating-point numbers. +including integers, uses double-precision floating-point numbers. On most modern systems, these are in IEEE 754 standard format. @xref{Arbitrary Precision Arithmetic}, for much more information.} Here are some examples of numeric constants that all @@ -10554,7 +10629,7 @@ have the same value: @cindex string constants A string constant consists of a sequence of characters enclosed in -double-quotation marks. For example: +double quotation marks. For example: @example "parrot" @@ -10576,13 +10651,13 @@ implementations may have difficulty with some character codes. @cindex numbers, octal @cindex numbers, hexadecimal -In @command{awk}, all numbers are in decimal; i.e., base 10. Many other +In @command{awk}, all numbers are in decimal (i.e., base 10). Many other programming languages allow you to specify numbers in other bases, often octal (base 8) and hexadecimal (base 16). -In octal, the numbers go 0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, etc. +In octal, the numbers go 0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, and so on. Just as @samp{11}, in decimal, is 1 times 10 plus 1, so @samp{11}, in octal, is 1 times 8, plus 1. This equals 9 in decimal. -In hexadecimal, there are 16 digits. Since the everyday decimal +In hexadecimal, there are 16 digits. Because the everyday decimal number system only has ten digits (@samp{0}--@samp{9}), the letters @samp{a} through @samp{f} are used to represent the rest. (Case in the letters is usually irrelevant; hexadecimal @samp{a} and @samp{A} @@ -10634,11 +10709,12 @@ you can use the @code{strtonum()} function to convert the data into a number. Most of the time, you will want to use octal or hexadecimal constants when working with the built-in bit manipulation functions; -see @ref{Bitwise Functions}, +see @DBREF{Bitwise Functions} for more information. -Unlike some early C implementations, @samp{8} and @samp{9} are not valid -in octal constants; e.g., @command{gawk} treats @samp{018} as decimal 18: +Unlike some early C implementations, @samp{8} and @samp{9} are not +valid in octal constants. For example, @command{gawk} treats @samp{018} +as decimal 18: @example $ @kbd{gawk 'BEGIN @{ print "021 is", 021 ; print 018 @}'} @@ -10724,7 +10800,7 @@ matched. However, regexp constants (such as @code{/foo/}) may be used like simple expressions. When a regexp constant appears by itself, it has the same meaning as if it appeared -in a pattern, i.e., @samp{($0 ~ /foo/)} +in a pattern (i.e., @samp{($0 ~ /foo/)}). @value{DARKCORNER} @xref{Expression Patterns}. This means that the following two code segments: @@ -10821,7 +10897,7 @@ either @code{sub()} or @code{gsub()}. However, what really happens is that the @code{pat} parameter is either one or zero, depending upon whether or not @code{$0} matches @code{/hi/}. @command{gawk} issues a warning when it sees a regexp constant used as -a parameter to a user-defined function, since passing a truth value in +a parameter to a user-defined function, because passing a truth value in this way is probably not what was intended. @c ENDOFRANGE rec @@ -10861,7 +10937,7 @@ variable's current value. Variables are given new values with @dfn{decrement operators}. @xref{Assignment Ops}. In addition, the @code{sub()} and @code{gsub()} functions can -change a variable's value, and the @code{match()}, @code{split()} +change a variable's value, and the @code{match()}, @code{split()}, and @code{patsplit()} functions can change the contents of their array parameters. @xref{String Functions}. @@ -10869,7 +10945,7 @@ array parameters. @xref{String Functions}. @cindex variables, initializing A few variables have special built-in meanings, such as @code{FS} (the field separator), and @code{NF} (the number of fields in the current input -record). @xref{Built-in Variables}, for a list of the predefined variables. +record). @DBXREF{Built-in Variables} for a list of the predefined variables. These predefined variables can be used and assigned just like all other variables, but their values are also used or changed automatically by @command{awk}. All predefined variables' names are entirely uppercase. @@ -10910,7 +10986,7 @@ as in the following: the variable is set at the very beginning, even before the @code{BEGIN} rules execute. The @option{-v} option and its assignment must precede all the @value{FN} arguments, as well as the program text. -(@xref{Options}, for more information about +(@DBXREF{Options} for more information about the @option{-v} option.) Otherwise, the variable assignment is performed at a time determined by its position among the input file arguments---after the processing of the @@ -10950,7 +11026,7 @@ sequences @node Conversion @subsection Conversion of Strings and Numbers -Number to string and string to number conversion are generally +Number-to-string and string-to-number conversion are generally straightforward. There can be subtleties to be aware of; this @value{SECTION} discusses this important facet of @command{awk}. @@ -10961,7 +11037,7 @@ this @value{SECTION} discusses this important facet of @command{awk}. @end menu @node Strings And Numbers -@subsubsection How @command{awk} Converts Between Strings And Numbers +@subsubsection How @command{awk} Converts Between Strings and Numbers @cindex converting, strings to numbers @cindex strings, converting @@ -10992,7 +11068,7 @@ string, concatenate that number with the empty string, @code{""}. To force a string to be converted to a number, add zero to that string. A string is converted to a number by interpreting any numeric prefix of the string as numerals: -@code{"2.5"} converts to 2.5, @code{"1e3"} converts to 1000, and @code{"25fix"} +@code{"2.5"} converts to 2.5, @code{"1e3"} converts to 1,000, and @code{"25fix"} has a numeric value of 25. Strings that can't be interpreted as valid numbers convert to zero. @@ -11032,10 +11108,10 @@ b = a "" @code{b} has the value @code{"12"}, not @code{"12.00"}. @value{DARKCORNER} -@cindex sidebar, Pre-POSIX @command{awk} Used @code{OFMT} For String Conversion +@cindex sidebar, Pre-POSIX @command{awk} Used @code{OFMT} for String Conversion @ifdocbook @docbook -<sidebar><title>Pre-POSIX @command{awk} Used @code{OFMT} For String Conversion</title> +<sidebar><title>Pre-POSIX @command{awk} Used @code{OFMT} for String Conversion</title> @end docbook @cindex POSIX @command{awk}, @code{OFMT} variable and @@ -11049,7 +11125,7 @@ specifies the output format to use when printing numbers with @code{print}. conversion from the semantics of printing. Both @code{CONVFMT} and @code{OFMT} have the same default value: @code{"%.6g"}. In the vast majority of cases, old @command{awk} programs do not change their behavior. -@xref{Print}, for more information on the @code{print} statement. +@DBXREF{Print} for more information on the @code{print} statement. @docbook </sidebar> @@ -11058,7 +11134,7 @@ of cases, old @command{awk} programs do not change their behavior. @ifnotdocbook @cartouche -@center @b{Pre-POSIX @command{awk} Used @code{OFMT} For String Conversion} +@center @b{Pre-POSIX @command{awk} Used @code{OFMT} for String Conversion} @cindex POSIX @command{awk}, @code{OFMT} variable and @@ -11072,7 +11148,7 @@ specifies the output format to use when printing numbers with @code{print}. conversion from the semantics of printing. Both @code{CONVFMT} and @code{OFMT} have the same default value: @code{"%.6g"}. In the vast majority of cases, old @command{awk} programs do not change their behavior. -@xref{Print}, for more information on the @code{print} statement. +@DBXREF{Print} for more information on the @code{print} statement. @end cartouche @end ifnotdocbook @@ -11095,7 +11171,7 @@ The POSIX standard says that @command{awk} always uses the period as the decimal point when reading the @command{awk} program source code, and for command-line variable assignments (@pxref{Other Arguments}). However, when interpreting input data, for @code{print} and @code{printf} output, -and for number to string conversion, the local decimal point character +and for number-to-string conversion, the local decimal point character is used. @value{DARKCORNER} In all cases, numbers in source code and in input data cannot have a thousands separator. Here are some examples indicating the difference in behavior, on a GNU/Linux system: @@ -11120,7 +11196,7 @@ as the full number including the fractional part, 4.321. Some earlier versions of @command{gawk} fully complied with this aspect of the standard. However, many users in non-English locales complained -about this behavior, since their data used a period as the decimal +about this behavior, because their data used a period as the decimal point, so the default behavior was restored to use a period as the decimal point character. You can use the @option{--use-lc-numeric} option (@pxref{Options}) to force @command{gawk} to use the locale's @@ -11133,7 +11209,7 @@ point character is used and when a period is used. Some of these features have not been described yet. @float Table,table-locale-affects -@caption{Locale Decimal Point versus A Period} +@caption{Locale decimal point versus a period} @multitable @columnfractions .15 .20 .45 @headitem Feature @tab Default @tab @option{--posix} or @option{--use-lc-numeric} @item @code{%'g} @tab Use locale @tab Use locale @@ -11143,13 +11219,13 @@ features have not been described yet. @end multitable @end float -Finally, modern day formal standards and IEEE standard floating point +Finally, modern day formal standards and IEEE standard floating-point representation can have an unusual but important effect on the way @command{gawk} converts some special string values to numbers. The details are presented in @ref{POSIX Floating Point Problems}. @node All Operators -@section Operators: Doing Something With Values +@section Operators: Doing Something with Values This @value{SECTION} introduces the @dfn{operators} which make use of the values provided by constants and variables. @@ -11228,7 +11304,7 @@ Multiplication. Division; because all numbers in @command{awk} are floating-point numbers, the result is @emph{not} rounded to an integer---@samp{3 / 4} has the value 0.75. (It is a common mistake, especially for C programmers, -to forget that @emph{all} numbers in @command{awk} are floating-point, +to forget that @emph{all} numbers in @command{awk} are floating point, and that division of integer-looking constants produces a real number, not an integer.) @@ -11313,7 +11389,7 @@ $ @kbd{awk '@{ print "Field number one:" $1 @}' mail-list} @cindex troubleshooting, string concatenation Because string concatenation does not have an explicit operator, it is -often necessary to insure that it happens at the right time by using +often necessary to ensure that it happens at the right time by using parentheses to enclose the items to concatenate. For example, you might expect that the following code fragment concatenates @code{file} and @code{name}: @@ -11575,7 +11651,14 @@ The indices of @code{bar} are practically guaranteed to be different, because @code{rand()} returns different values each time it is called. (Arrays and the @code{rand()} function haven't been covered yet. @xref{Arrays}, -and see @ref{Numeric Functions}, for more information). +and +@ifnotdocbook +@DBPXREF{Numeric Functions} +@end ifnotdocbook +@ifdocbook +@DBREF{Numeric Functions} +@end ifdocbook +for more information). This example illustrates an important fact about assignment operators: the lefthand expression is only evaluated @emph{once}. @@ -11608,20 +11691,20 @@ to a number. @cindex @code{*} (asterisk), @code{**=} operator @cindex asterisk (@code{*}), @code{**=} operator @float Table,table-assign-ops -@caption{Arithmetic Assignment Operators} +@caption{Arithmetic assignment operators} @multitable @columnfractions .30 .70 @headitem Operator @tab Effect -@item @var{lvalue} @code{+=} @var{increment} @tab Add @var{increment} to the value of @var{lvalue}. -@item @var{lvalue} @code{-=} @var{decrement} @tab Subtract @var{decrement} from the value of @var{lvalue}. -@item @var{lvalue} @code{*=} @var{coefficient} @tab Multiply the value of @var{lvalue} by @var{coefficient}. -@item @var{lvalue} @code{/=} @var{divisor} @tab Divide the value of @var{lvalue} by @var{divisor}. -@item @var{lvalue} @code{%=} @var{modulus} @tab Set @var{lvalue} to its remainder by @var{modulus}. +@item @var{lvalue} @code{+=} @var{increment} @tab Add @var{increment} to the value of @var{lvalue} +@item @var{lvalue} @code{-=} @var{decrement} @tab Subtract @var{decrement} from the value of @var{lvalue} +@item @var{lvalue} @code{*=} @var{coefficient} @tab Multiply the value of @var{lvalue} by @var{coefficient} +@item @var{lvalue} @code{/=} @var{divisor} @tab Divide the value of @var{lvalue} by @var{divisor} +@item @var{lvalue} @code{%=} @var{modulus} @tab Set @var{lvalue} to its remainder by @var{modulus} @cindex common extensions, @code{**=} operator @cindex extensions, common@comma{} @code{**=} operator @cindex @command{awk} language, POSIX version @cindex POSIX @command{awk} @item @var{lvalue} @code{^=} @var{power} @tab -@item @var{lvalue} @code{**=} @var{power} @tab Raise @var{lvalue} to the power @var{power}. @value{COMMONEXT} +@item @var{lvalue} @code{**=} @var{power} @tab Raise @var{lvalue} to the power @var{power} @value{COMMONEXT} @end multitable @end float @@ -11657,7 +11740,7 @@ This is most notable in some commercial @command{awk} versions. For example: @example -$ awk /==/ /dev/null +$ @kbd{awk /==/ /dev/null} @error{} awk: syntax error at source line 1 @error{} context is @error{} >>> /= <<< @@ -11703,7 +11786,7 @@ This is most notable in some commercial @command{awk} versions. For example: @example -$ awk /==/ /dev/null +$ @kbd{awk /==/ /dev/null} @error{} awk: syntax error at source line 1 @error{} context is @error{} >>> /= <<< @@ -11756,7 +11839,7 @@ but with the side effect of incrementing it. The post-increment @samp{foo++} is nearly the same as writing @samp{(foo += 1) - 1}. It is not perfectly equivalent because all numbers in -@command{awk} are floating-point---in floating-point, @samp{foo + 1 - 1} does +@command{awk} are floating point---in floating point, @samp{foo + 1 - 1} does not necessarily equal @code{foo}. But the difference is minute as long as you stick to numbers that are fairly small (less than @iftex @@ -11919,8 +12002,8 @@ You should avoid such things in your own programs. @node Truth Values and Conditions @section Truth Values and Conditions -In certain contexts, expression values also serve as ``truth values;'' i.e., -they determine what should happen next as the program runs. This +In certain contexts, expression values also serve as ``truth values''; (i.e., +they determine what should happen next as the program runs). This @value{SECTION} describes how @command{awk} defines ``true'' and ``false'' and how values are compared. @@ -11976,7 +12059,7 @@ the string constant @code{"0"} is actually true, because it is non-null. @subsection Variable Typing and Comparison Expressions @quotation @i{The Guide is definitive. Reality is frequently inaccurate.} -@author The Hitchhiker's Guide to the Galaxy +@author Douglas Adams, @cite{The Hitchhiker's Guide to the Galaxy} @end quotation @c STARTOFRANGE comex @@ -12004,7 +12087,7 @@ compares variables. @end menu @node Variable Typing -@subsubsection String Type Versus Numeric Type +@subsubsection String Type versus Numeric Type @cindex numeric, strings @cindex strings, numeric @@ -12030,7 +12113,7 @@ attribute. @item Fields, @code{getline} input, @code{FILENAME}, @code{ARGV} elements, @code{ENVIRON} elements, and the elements of an array created by -@code{match()}, @code{split()} and @code{patsplit()} that are numeric +@code{match()}, @code{split()}, and @code{patsplit()} that are numeric strings have the @var{strnum} attribute. Otherwise, they have the @var{string} attribute. Uninitialized variables also have the @var{strnum} attribute. @@ -12231,18 +12314,18 @@ operators}, which are a superset of those in C. @cindex exclamation point (@code{!}), @code{!~} operator @cindex @code{in} operator @float Table,table-relational-ops -@caption{Relational Operators} +@caption{Relational operators} @multitable @columnfractions .25 .75 @headitem Expression @tab Result -@item @var{x} @code{<} @var{y} @tab True if @var{x} is less than @var{y}. -@item @var{x} @code{<=} @var{y} @tab True if @var{x} is less than or equal to @var{y}. -@item @var{x} @code{>} @var{y} @tab True if @var{x} is greater than @var{y}. -@item @var{x} @code{>=} @var{y} @tab True if @var{x} is greater than or equal to @var{y}. -@item @var{x} @code{==} @var{y} @tab True if @var{x} is equal to @var{y}. -@item @var{x} @code{!=} @var{y} @tab True if @var{x} is not equal to @var{y}. -@item @var{x} @code{~} @var{y} @tab True if the string @var{x} matches the regexp denoted by @var{y}. -@item @var{x} @code{!~} @var{y} @tab True if the string @var{x} does not match the regexp denoted by @var{y}. -@item @var{subscript} @code{in} @var{array} @tab True if the array @var{array} has an element with the subscript @var{subscript}. +@item @var{x} @code{<} @var{y} @tab True if @var{x} is less than @var{y} +@item @var{x} @code{<=} @var{y} @tab True if @var{x} is less than or equal to @var{y} +@item @var{x} @code{>} @var{y} @tab True if @var{x} is greater than @var{y} +@item @var{x} @code{>=} @var{y} @tab True if @var{x} is greater than or equal to @var{y} +@item @var{x} @code{==} @var{y} @tab True if @var{x} is equal to @var{y} +@item @var{x} @code{!=} @var{y} @tab True if @var{x} is not equal to @var{y} +@item @var{x} @code{~} @var{y} @tab True if the string @var{x} matches the regexp denoted by @var{y} +@item @var{x} @code{!~} @var{y} @tab True if the string @var{x} does not match the regexp denoted by @var{y} +@item @var{subscript} @code{in} @var{array} @tab True if the array @var{array} has an element with the subscript @var{subscript} @end multitable @end float @@ -12280,24 +12363,24 @@ The following list of expressions illustrates the kinds of comparisons @table @code @item 1.5 <= 2.0 -numeric comparison (true) +Numeric comparison (true) @item "abc" >= "xyz" -string comparison (false) +String comparison (false) @item 1.5 != " +2" -string comparison (true) +String comparison (true) @item "1e2" < "3" -string comparison (true) +String comparison (true) @item a = 2; b = "2" @itemx a == b -string comparison (true) +String comparison (true) @item a = 2; b = " +2" @itemx a == b -string comparison (false) +String comparison (false) @end table In this example: @@ -12350,7 +12433,7 @@ dynamic regexp (@pxref{Regexp Usage}; also @cindex @command{awk}, regexp constants and @cindex regexp constants A constant regular -expression in slashes by itself is also an expression. The regexp +expression in slashes by itself is also an expression. @code{/@var{regexp}/} is an abbreviation for the following comparison expression: @example @@ -12364,7 +12447,7 @@ One special place where @code{/foo/} is @emph{not} an abbreviation for where this is discussed in more detail. @node POSIX String Comparison -@subsubsection String Comparison With POSIX Rules +@subsubsection String Comparison with POSIX Rules The POSIX standard says that string comparison is performed based on the locale's @dfn{collating order}. This is the order in which @@ -12620,13 +12703,13 @@ example, the function @code{sqrt()} computes the square root of a number. @cindex functions, built-in A fixed set of functions are @dfn{built-in}, which means they are available in every @command{awk} program. The @code{sqrt()} function is one -of these. @xref{Built-in}, for a list of built-in +of these. @DBXREF{Built-in} for a list of built-in functions and their descriptions. In addition, you can define functions for use in your program. -@xref{User-defined}, +@DBXREF{User-defined} for instructions on how to do this. Finally, @command{gawk} lets you write functions in C or C++ -that may be called from your program: see @ref{Dynamic Extensions}. +that may be called from your program (@pxref{Dynamic Extensions}). @cindex arguments, in function calls The way to use a function is with a @dfn{function call} expression, @@ -12645,7 +12728,7 @@ rand() @ii{no arguments} @cindex troubleshooting, function call syntax @quotation CAUTION -Do not put any space between the function name and the open-parenthesis! +Do not put any space between the function name and the opening parenthesis! A user-defined function name looks just like the name of a variable---a space would make the expression look like concatenation of a variable with an expression inside parentheses. @@ -12666,7 +12749,7 @@ Some of the built-in functions have one or more optional arguments. If those arguments are not supplied, the functions use a reasonable default value. -@xref{Built-in}, for full details. If arguments +@DBXREF{Built-in} for full details. If arguments are omitted in calls to user-defined functions, then those arguments are treated as local variables. Such local variables act like the empty string if referenced where a string value is required, @@ -12821,7 +12904,7 @@ Multiplication, division, remainder. @item @code{+ -} Addition, subtraction. -@item String Concatenation +@item String concatenation There is no special symbol for concatenation. The operands are simply written side by side (@pxref{Concatenation}). @@ -12860,7 +12943,7 @@ statements belong to the statement level, not to expressions. The redirection does not produce an expression that could be the operand of another operator. As a result, it does not make sense to use a redirection operator near another operator of lower precedence without -parentheses. Such combinations (for example, @samp{print foo > a ? b : c}), +parentheses. Such combinations (e.g., @samp{print foo > a ? b : c}), result in syntax errors. The correct way to write this statement is @samp{print foo > (a ? b : c)}. @@ -12918,7 +13001,7 @@ For maximum portability, do not use them. @c ENDOFRANGE oppr @node Locales -@section Where You Are Makes A Difference +@section Where You Are Makes a Difference @cindex locale, definition of Modern systems support the notion of @dfn{locales}: a way to tell the @@ -12938,8 +13021,8 @@ character}, to find the record terminator. Locales can affect how dates and times are formatted (@pxref{Time Functions}). For example, a common way to abbreviate the date September -4, 2015 in the United States is ``9/4/15.'' In many countries in -Europe, however, it is abbreviated ``4.9.15.'' Thus, the @code{%x} +4, 2015, in the United States is ``9/4/15.'' In many countries in +Europe, however, it is abbreviated ``4.9.15.'' Thus, the @samp{%x} specification in a @code{"US"} locale might produce @samp{9/4/15}, while in a @code{"EUROPE"} locale, it might produce @samp{4.9.15}. @@ -12957,13 +13040,13 @@ in @ref{Conversion}. @itemize @value{BULLET} @item Expressions are the basic elements of computation in programs. They are -built from constants, variables, function calls and combinations of the +built from constants, variables, function calls, and combinations of the various kinds of values with operators. @item @command{awk} supplies three kinds of constants: numeric, string, and regexp. @command{gawk} lets you specify numeric constants in octal -and hexadecimal (bases 8 and 16) in addition to decimal (base 10). +and hexadecimal (bases 8 and 16) as well as decimal (base 10). In certain contexts, a standalone regexp constant such as @code{/foo/} has the same meaning as @samp{$0 ~ /foo/}. @@ -13005,8 +13088,8 @@ or numeric). Function calls return a value which may be used as part of a larger expression. Expressions used to pass parameter values are fully evaluated before the function is called. @command{awk} provides -built-in and user-defined functions; this is described later on in this -@value{DOCUMENT}. +built-in and user-defined functions; this is described in +@ref{Functions}. @item Operator precedence specifies the order in which operations are performed, @@ -13166,9 +13249,8 @@ $ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @cindex regexp constants, as patterns @cindex patterns, regexp constants as -A regexp constant as a pattern is also a special case of an expression -pattern. The expression @samp{/li/} has the value one if @samp{li} -appears in the current input record. Thus, as a pattern, @samp{/li/} +pattern. The expression @code{/li/} has the value one if @samp{li} +appears in the current input record. Thus, as a pattern, @code{/li/} matches any record containing @samp{li}. @cindex Boolean expressions, as patterns @@ -13219,7 +13301,7 @@ The subexpressions of a Boolean operator in a pattern can be constant regular expressions, comparisons, or any other @command{awk} expressions. Range patterns are not expressions, so they cannot appear inside Boolean patterns. Likewise, the special patterns @code{BEGIN}, @code{END}, -@code{BEGINFILE} and @code{ENDFILE}, +@code{BEGINFILE}, and @code{ENDFILE}, which never match any input record, are not expressions and cannot appear inside Boolean patterns. @@ -13330,7 +13412,7 @@ They supply startup and cleanup actions for @command{awk} programs. @code{BEGIN} and @code{END} rules must have actions; there is no default action for these rules because there is no current record when they run. @code{BEGIN} and @code{END} rules are often referred to as -``@code{BEGIN} and @code{END} blocks'' by long-time @command{awk} +``@code{BEGIN} and @code{END} blocks'' by longtime @command{awk} programmers. @menu @@ -13361,7 +13443,7 @@ $ @kbd{awk '} This program finds the number of records in the input file @file{mail-list} that contain the string @samp{li}. The @code{BEGIN} rule prints a title for the report. There is no need to use the @code{BEGIN} rule to -initialize the counter @code{n} to zero, since @command{awk} does this +initialize the counter @code{n} to zero, as @command{awk} does this automatically (@pxref{Variables}). The second rule increments the variable @code{n} every time a record containing the pattern @samp{li} is read. The @code{END} rule @@ -13389,7 +13471,7 @@ The order in which library functions are named on the command line controls the order in which their @code{BEGIN} and @code{END} rules are executed. Therefore, you have to be careful when writing such rules in library files so that the order in which they are executed doesn't matter. -@xref{Options}, for more information on +@DBXREF{Options} for more information on using library functions. @xref{Library Functions}, for a number of useful library functions. @@ -13438,11 +13520,11 @@ of Unix @command{awk} do not. The third point follows from the first two. The meaning of @samp{print} inside a @code{BEGIN} or @code{END} rule is the same as always: @samp{print $0}. If @code{$0} is the null string, then this prints an -empty record. Many long time @command{awk} programmers use an unadorned +empty record. Many longtime @command{awk} programmers use an unadorned @samp{print} in @code{BEGIN} and @code{END} rules, to mean @samp{@w{print ""}}, relying on @code{$0} being null. Although one might generally get away with this in @code{BEGIN} rules, it is a very bad idea in @code{END} rules, -at least in @command{gawk}. It is also poor style, since if an empty +at least in @command{gawk}. It is also poor style, because if an empty line is needed in the output, the program should print one explicitly. @cindex @code{next} statement, @code{BEGIN}/@code{END} patterns and @@ -13452,9 +13534,14 @@ line is needed in the output, the program should print one explicitly. Finally, the @code{next} and @code{nextfile} statements are not allowed in a @code{BEGIN} rule, because the implicit read-a-record-and-match-against-the-rules loop has not started yet. Similarly, those statements -are not valid in an @code{END} rule, since all the input has been read. -(@xref{Next Statement}, and see -@ref{Nextfile Statement}.) +are not valid in an @code{END} rule, because all the input has been read. +(@DBXREF{Next Statement} and +@ifnotdocbook +@DBPXREF{Nextfile Statement}.) +@end ifnotdocbook +@ifdocbook +@DBREF{Nextfile Statement}.) +@end ifdocbook @c ENDOFRANGE beg @c ENDOFRANGE end @@ -13607,9 +13694,9 @@ awk "/$pattern/ "'@{ nmatches++ @} @noindent The @command{awk} program consists of two pieces of quoted text that are concatenated together to form the program. -The first part is double-quoted, which allows substitution of +The first part is double quoted, which allows substitution of the @code{pattern} shell variable inside the quotes. -The second part is single-quoted. +The second part is single quoted. Variable substitution via quoting works, but can be potentially messy. It requires a good understanding of the shell's quoting rules @@ -13638,7 +13725,7 @@ The assignment @samp{-v pat="$pattern"} still requires double quotes, in case there is whitespace in the value of @code{$pattern}. The @command{awk} variable @code{pat} could be named @code{pattern} too, but that would be more confusing. Using a variable also -provides more flexibility, since the variable can be used anywhere inside +provides more flexibility, as the variable can be used anywhere inside the program---for printing, as an array subscript, or for any other use---without requiring the quoting tricks at every point in the program. @@ -13711,7 +13798,7 @@ is used in order to put several statements together in the body of an Use the @code{getline} command (@pxref{Getline}). Also supplied in @command{awk} are the @code{next} -statement (@pxref{Next Statement}), +statement (@pxref{Next Statement}) and the @code{nextfile} statement (@pxref{Nextfile Statement}). @@ -13799,7 +13886,7 @@ else print "x is odd" @end example -In this example, if the expression @samp{x % 2 == 0} is true (that is, +In this example, if the expression @samp{x % 2 == 0} is true (i.e., if the value of @code{x} is evenly divisible by two), then the first @code{print} statement is executed; otherwise, the second @code{print} statement is executed. @@ -13878,7 +13965,7 @@ field is printed. Then the @samp{i++} increments the value of @code{i} and the loop repeats. The loop terminates when @code{i} reaches four. A newline is not required between the condition and the -body; however using one makes the program clearer unless the body is a +body; however, using one makes the program clearer unless the body is a compound statement or else is very simple. The newline after the open-brace that begins the compound statement is not required either, but the program is harder to read without it. @@ -13925,7 +14012,7 @@ The following is an example of a @code{do} statement: @noindent This program prints each input record 10 times. However, it isn't a very -realistic example, since in this case an ordinary @code{while} would do +realistic example, because in this case an ordinary @code{while} would do just as well. This situation reflects actual experience; only occasionally is there a real use for a @code{do} statement. @@ -14022,7 +14109,7 @@ very common in loops. It can be easier to think of this counting as part of looping rather than as something to do inside the loop. @cindex @code{in} operator -There is an alternate version of the @code{for} loop, for iterating over +There is an alternative version of the @code{for} loop, for iterating over all the indices of an array: @example @@ -14031,7 +14118,7 @@ for (i in array) @end example @noindent -@xref{Scanning an Array}, +@DBXREF{Scanning an Array} for more information on this version of the @code{for} loop. @node Switch Statement @@ -14051,7 +14138,7 @@ are checked for a match in the order they are defined. If no suitable Each @code{case} contains a single constant, be it numeric, string, or regexp. The @code{switch} expression is evaluated, and then each -@code{case}'s constant is compared against the result in turn. The type of constant +@code{case}'s constant is compared against the result in turn. The type of constant determines the comparison: numeric or string do the usual comparisons. A regexp constant does a regular expression match against the string value of the original expression. The general form of the @code{switch} @@ -14098,9 +14185,9 @@ while ((c = getopt(ARGC, ARGV, "aksx")) != -1) @{ @} @end example -Note that if none of the statements specified above halt execution +Note that if none of the statements specified here halt execution of a matched @code{case} statement, execution falls through to the -next @code{case} until execution halts. In the above example, the +next @code{case} until execution halts. In this example, the @code{case} for @code{"?"} falls through to the @code{default} case, which is to call a function named @code{usage()}. (The @code{getopt()} function being called here is @@ -14227,7 +14314,7 @@ BEGIN @{ @end example @noindent -This program loops forever once @code{x} reaches 5, since +This program loops forever once @code{x} reaches 5, because the increment (@samp{x++}) is never reached. @c @cindex @code{continue}, outside of loops @@ -14288,7 +14375,7 @@ Because of the @code{next} statement, the program's subsequent rules won't see the bad record. The error message is redirected to the standard error output stream, as error messages should be. -For more detail see +For more detail, see @ref{Special Files}. If the @code{next} statement causes the end of the input to be reached, @@ -14354,7 +14441,7 @@ rule to skip over a file that would otherwise cause @command{gawk} to exit with a fatal error. In this case, @code{ENDFILE} rules are not executed. @xref{BEGINFILE/ENDFILE}. -While one might think that @samp{close(FILENAME)} would accomplish +Although it might seem that @samp{close(FILENAME)} would accomplish the same as @code{nextfile}, this isn't true. @code{close()} is reserved for closing files, pipes, and coprocesses that are opened with redirections. It is not related to the main processing that @@ -14362,7 +14449,7 @@ opened with redirections. It is not related to the main processing that @quotation NOTE For many years, @code{nextfile} was a -common extension. In September, 2012, it was accepted for +common extension. In September 2012, it was accepted for inclusion into the POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=607, the Austin Group website}. @end quotation @@ -14411,7 +14498,7 @@ In such a case, if you don't want the @code{END} rule to do its job, set a variable to nonzero before the @code{exit} statement and check that variable in the @code{END} rule. -@xref{Assert Function}, +@DBXREF{Assert Function} for an example that does this. @cindex dark corner, @code{exit} statement @@ -14422,7 +14509,7 @@ In the case where an argument is supplied to a first @code{exit} statement, and then @code{exit} is called a second time from an @code{END} rule with no argument, @command{awk} uses the previously supplied exit value. @value{DARKCORNER} -@xref{Exit Status}, for more information. +@DBXREF{Exit Status} for more information. @cindex programming conventions, @code{exit} statement For example, suppose an error condition occurs that is difficult or @@ -14482,7 +14569,7 @@ their areas of activity. @end menu @node User-modified -@subsection Built-in Variables That Control @command{awk} +@subsection Built-In Variables That Control @command{awk} @c STARTOFRANGE bvaru @cindex predefined variables, user-modifiable @c STARTOFRANGE nmbv @@ -14539,7 +14626,7 @@ A space-separated list of columns that tells @command{gawk} how to split input with fixed columnar boundaries. Assigning a value to @code{FIELDWIDTHS} overrides the use of @code{FS} and @code{FPAT} for field splitting. -@xref{Constant Size}, for more information. +@DBXREF{Constant Size} for more information. @cindex @command{gawk}, @code{FPAT} variable in @cindex @code{FPAT} variable @@ -14551,7 +14638,7 @@ A regular expression (as a string) that tells @command{gawk} to create the fields based on text that matches the regular expression. Assigning a value to @code{FPAT} overrides the use of @code{FS} and @code{FIELDWIDTHS} for field splitting. -@xref{Splitting By Content}, for more information. +@DBXREF{Splitting By Content} for more information. @cindex @code{FS} variable @cindex separators, field @@ -14661,12 +14748,12 @@ character. (@xref{Output Separators}.) @cindex @code{PREC} variable @item PREC # -The working precision of arbitrary precision floating-point numbers, +The working precision of arbitrary-precision floating-point numbers, 53 bits by default (@pxref{Setting precision}). @cindex @code{ROUNDMODE} variable @item ROUNDMODE # -The rounding mode to use for arbitrary precision arithmetic on +The rounding mode to use for arbitrary-precision arithmetic on numbers, by default @code{"N"} (@samp{roundTiesToEven} in the IEEE 754 standard; @pxref{Setting the rounding mode}). @@ -14708,7 +14795,7 @@ really accesses @code{foo["A\034B"]} Used for internationalization of programs at the @command{awk} level. It sets the default text domain for specially marked string constants in the source text, as well as for the -@code{dcgettext()}, @code{dcngettext()} and @code{bindtextdomain()} functions +@code{dcgettext()}, @code{dcngettext()}, and @code{bindtextdomain()} functions (@pxref{Internationalization}). The default value of @code{TEXTDOMAIN} is @code{"messages"}. @end table @@ -14718,7 +14805,7 @@ The default value of @code{TEXTDOMAIN} is @code{"messages"}. @c ENDOFRANGE nmbv @node Auto-set -@subsection Built-in Variables That Convey Information +@subsection Built-In Variables That Convey Information @c STARTOFRANGE bvconi @cindex predefined variables, conveying information @@ -14731,7 +14818,7 @@ information to your program. The variables that are specific to @command{gawk} are marked with a pound sign (@samp{#}). These variables are @command{gawk} extensions. In other @command{awk} implementations or if @command{gawk} is in compatibility -mode (@pxref{Options}), they are not special. +mode (@pxref{Options}), they are not special: @c @asis for docbook @table @asis @@ -14772,7 +14859,7 @@ method of accessing command-line arguments. The value of @code{ARGV[0]} can vary from system to system. Also, you should note that the program text is @emph{not} included in @code{ARGV}, nor are any of @command{awk}'s command-line options. -@xref{ARGC and ARGV}, for information +@DBXREF{ARGC and ARGV} for information about how @command{awk} uses these variables. @value{DARKCORNER} @@ -14814,12 +14901,23 @@ that it creates. You should therefore be especially careful if you modify @code{ENVIRON["PATH"]"}, which is the search path for finding executable programs. +This can also affect the running @command{gawk} program, since some of the +built-in functions may pay attention to certain environment variables. +The most notable instance of this is @code{mktime()} (@pxref{Time +Functions}), which pays attention the value of the @env{TZ} environment +variable on many systems. + Some operating systems may not have environment variables. On such systems, the @code{ENVIRON} array is empty (except for @w{@code{ENVIRON["AWKPATH"]}} and @w{@code{ENVIRON["AWKLIBPATH"]}}; -@pxref{AWKPATH Variable}, and +@DBPXREF{AWKPATH Variable} and +@ifdocbook +@DBREF{AWKLIBPATH Variable}). +@end ifdocbook +@ifnotdocbook @pxref{AWKLIBPATH Variable}). +@end ifnotdocbook @cindex @command{gawk}, @code{ERRNO} variable in @cindex @code{ERRNO} variable @@ -14848,7 +14946,7 @@ The name of the current input file. When no @value{DF}s are listed on the command line, @command{awk} reads from the standard input and @code{FILENAME} is set to @code{"-"}. @code{FILENAME} changes each time a new file is read (@pxref{Reading Files}). Inside a @code{BEGIN} -rule, the value of @code{FILENAME} is @code{""}, since there are no input +rule, the value of @code{FILENAME} is @code{""}, because there are no input files being processed yet.@footnote{Some early implementations of Unix @command{awk} initialized @code{FILENAME} to @code{"-"}, even if there were @value{DF}s to be processed. This behavior was incorrect and should @@ -14880,7 +14978,7 @@ current record. @xref{Changing Fields}. @cindex differences in @command{awk} and @command{gawk}, @code{FUNCTAB} variable @item @code{FUNCTAB #} An array whose indices and corresponding values are the names of all -the built-in, user-defined and extension functions in the program. +the built-in, user-defined, and extension functions in the program. @quotation NOTE Attempting to use the @code{delete} statement with the @code{FUNCTAB} @@ -14974,7 +15072,7 @@ The parent process ID of the current process. If this element exists in @code{PROCINFO}, its value controls the order in which array indices will be processed by @samp{for (@var{indx} in @var{array})} loops. -Since this is an advanced feature, we defer the +This is an advanced feature, so we defer the full description until later; see @ref{Scanning an Array}. @@ -14994,10 +15092,10 @@ The version of @command{gawk}. The following additional elements in the array are available to provide information about the MPFR and GMP libraries -if your version of @command{gawk} supports arbitrary precision arithmetic -(@pxref{Arbitrary Precision Arithmetic}): +if your version of @command{gawk} supports arbitrary-precision arithmetic +(@pxref{Arbitrary Precision Arithmetic}): -@table @code +@table @code @cindex version of GNU MPFR library @item PROCINFO["mpfr_version"] The version of the GNU MPFR library. @@ -15045,7 +15143,7 @@ The @code{PROCINFO} array has the following additional uses: @item It may be used to provide a timeout when reading from any open input file, pipe, or coprocess. -@xref{Read Timeout}, for more information. +@DBXREF{Read Timeout} for more information. @item It may be used to cause coprocesses to communicate over pseudo-ttys @@ -15290,8 +15388,14 @@ use the @code{delete} statement to remove elements from All of these actions are typically done in the @code{BEGIN} rule, before actual processing of the input begins. -@xref{Split Program}, and see -@ref{Tee Program}, for examples +@DBXREF{Split Program} and +@ifnotdocbook +@DBPXREF{Tee Program} +@end ifnotdocbook +@ifdocbook +@DBREF{Tee Program} +@end ifdocbook +for examples of each way of removing elements from @code{ARGV}. To actually get options into an @command{awk} program, @@ -15303,7 +15407,7 @@ awk -f myprog.awk -- -v -q file1 file2 @dots{} @end example The following fragment processes @code{ARGV} in order to examine, and -then remove, the above command-line options: +then remove, the previously mentioned command-line options: @example BEGIN @{ @@ -15339,14 +15443,21 @@ gawk -f myprog.awk -q -v file1 file2 @dots{} @noindent Because @option{-q} is not a valid @command{gawk} option, it and the following @option{-v} are passed on to the @command{awk} program. -(@xref{Getopt Function}, for an @command{awk} library function that +(@DBXREF{Getopt Function} for an @command{awk} library function that parses command-line options.) When designing your program, you should choose options that don't -conflict with @command{gawk}'s, since it will process any options +conflict with @command{gawk}'s, because it will process any options that it accepts before passing the rest of the command line on to your program. Using @samp{#!} with the @option{-E} option may help -(@pxref{Executable Scripts}, and @pxref{Options}). +(@DBXREF{Executable Scripts} +and +@ifnotdocbook +@DBPXREF{Options}). +@end ifnotdocbook +@ifdocbook +@DBREF{Options}). +@end ifdocbook @node Pattern Action Summary @section Summary @@ -15512,7 +15623,7 @@ as shown in @inlineraw{docbook, <xref linkend="figure-array-elements"/>}: @ifnotdocbook @float Figure,figure-array-elements -@caption{A Contiguous Array} +@caption{A contiguous array} @ifinfo @center @image{array-elements, , , Basic Program Stages, txt} @end ifinfo @@ -15524,7 +15635,7 @@ as shown in @inlineraw{docbook, <xref linkend="figure-array-elements"/>}: @docbook <figure id="figure-array-elements" float="0"> -<title>A Contiguous Array</title> +<title>A contiguous array</title> <mediaobject> <imageobject role="web"><imagedata fileref="array-elements.png" format="PNG"/></imageobject> </mediaobject> @@ -15543,7 +15654,7 @@ position with zero elements before it. @cindex associative arrays @cindex arrays, associative Arrays in @command{awk} are different---they are @dfn{associative}. This means -that each array is a collection of pairs: an index and its corresponding +that each array is a collection of pairs---an index and its corresponding array element value: @ifnotdocbook @@ -15724,7 +15835,7 @@ numbers and strings as indices. There are some subtleties to how numbers work when used as array subscripts; this is discussed in more detail in @ref{Numeric Array Subscripts}.) -Here, the number @code{1} isn't double-quoted, since @command{awk} +Here, the number @code{1} isn't double quoted, because @command{awk} automatically converts it to a string. @cindex @command{gawk}, @code{IGNORECASE} variable in @@ -15809,7 +15920,7 @@ This expression tests whether the particular index @var{indx} exists, without the side effect of creating that element if it is not present. The expression has the value one (true) if @code{@var{array}[@var{indx}]} exists and zero (false) if it does not exist. -(We use @var{indx} here, since @samp{index} is the name of a built-in +(We use @var{indx} here, because @samp{index} is the name of a built-in function.) For example, this statement tests whether the array @code{frequencies} contains the index @samp{2}: @@ -15952,7 +16063,7 @@ the word as index. The second rule scans the elements of @code{used} to find all the distinct words that appear in the input. It prints each word that is more than 10 characters long and also prints the number of such words. -@xref{String Functions}, +@DBXREF{String Functions} for more information on the built-in function @code{length()}. @example @@ -15975,7 +16086,7 @@ END @{ @end example @noindent -@xref{Word Sorting}, +@DBXREF{Word Sorting} for a more detailed example of this type. @cindex arrays, elements, order of access by @code{in} operator @@ -16030,7 +16141,7 @@ $ @kbd{nawk -f loopcheck.awk} @end example @node Controlling Scanning -@subsection Using Predefined Array Scanning Orders With @command{gawk} +@subsection Using Predefined Array Scanning Orders with @command{gawk} This @value{SUBSECTION} describes a feature that is specific to @command{gawk}. @@ -16055,7 +16166,7 @@ We describe this now. @item Set @code{PROCINFO["sorted_in"]} to the name of a user-defined function to use for comparison of array elements. This advanced feature -is described later, in @ref{Array Sorting}. +is described later in @ref{Array Sorting}. @end itemize @cindex @code{PROCINFO}, values of @code{sorted_in} @@ -16073,7 +16184,7 @@ the index is @code{"10"} rather than numeric 10.) @item "@@ind_num_asc" Order by indices in ascending order but force them to be treated as numbers in the process. -Any index with a non-numeric value will end up positioned as if it were zero. +Any index with a non-numeric value will end up positioned as if it were zero. @item "@@val_type_asc" Order by element values in ascending order (rather than by indices). @@ -16085,11 +16196,11 @@ which in turn come before all subarrays. @pxref{Arrays of Arrays}.) @item "@@val_str_asc" -Order by element values in ascending order (rather than by indices). Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as strings. Subarrays, if present, come out last. @item "@@val_num_asc" -Order by element values in ascending order (rather than by indices). Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as numbers. Subarrays, if present, come out last. When numeric values are equal, the string values are used to provide an ordering: this guarantees consistent results across different @@ -16150,11 +16261,11 @@ $ @kbd{gawk '} When sorting an array by element values, if a value happens to be a subarray then it is considered to be greater than any string or numeric value, regardless of what the subarray itself contains, -and all subarrays are treated as being equal to each other. Their +and all subarrays are treated as being equal to each other. Their order relative to each other is determined by their index strings. Here are some additional things to bear in mind about sorted -array traversal. +array traversal: @itemize @value{BULLET} @item @@ -16174,7 +16285,7 @@ if (save_sorted) @end example @item -As mentioned, the default array traversal order is represented by +As already mentioned, the default array traversal order is represented by @code{"@@unsorted"}. You can also get the default behavior by assigning the null string to @code{PROCINFO["sorted_in"]} or by just deleting the @code{"sorted_in"} element from the @code{PROCINFO} array with @@ -16219,7 +16330,7 @@ The program then changes the value of @code{CONVFMT}. The test @samp{(xyz in data)} generates a new string value from @code{xyz}---this time @code{"12.15"}---because the value of @code{CONVFMT} only allows two significant digits. This test fails, -since @code{"12.15"} is different from @code{"12.153"}. +because @code{"12.15"} is different from @code{"12.153"}. @cindex converting integer array subscripts @cindex integer array indices @@ -16237,19 +16348,19 @@ for (i = 1; i <= maxsub; i++) The ``integer values always convert to strings as integers'' rule has an additional consequence for array indexing. Octal and hexadecimal constants +@ifnotdocbook (@pxref{Nondecimal-numbers}) +@end ifnotdocbook +@ifdocbook +(covered in @ref{Nondecimal-numbers}) +@end ifdocbook are converted internally into numbers, and their original form -is forgotten. -This means, for example, that -@code{array[17]}, -@code{array[021]}, -and -@code{array[0x11]} -all refer to the same element! +is forgotten. This means, for example, that @code{array[17]}, +@code{array[021]}, and @code{array[0x11]} all refer to the same element! As with many things in @command{awk}, the majority of the time things work as you would expect them to. But it is useful to have a precise -knowledge of the actual rules since they can sometimes have a subtle +knowledge of the actual rules, as they can sometimes have a subtle effect on your programs. @node Uninitialized Subscripts @@ -16392,7 +16503,7 @@ by a number of other implementations. @cindex Brian Kernighan's @command{awk} @quotation NOTE For many years, using @code{delete} without a subscript was a common -extension. In September, 2012, it was accepted for inclusion into the +extension. In September 2012, it was accepted for inclusion into the POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=544, the Austin Group website}. @end quotation @@ -16434,7 +16545,7 @@ a = 3 @cindex subscripts in arrays, multidimensional @cindex arrays, multidimensional -A multidimensional array is an array in which an element is identified +A @dfn{multidimensional array} is an array in which an element is identified by a sequence of indices instead of a single index. For example, a two-dimensional array requires two indices. The usual way (in many languages, including @command{awk}) to refer to an element of a @@ -16476,7 +16587,7 @@ stored as @samp{foo["a@@b@@c"]}. @cindex @code{in} operator, index existence in multidimensional arrays To test whether a particular index sequence exists in a multidimensional array, use the same operator (@code{in}) that is -used for single dimensional arrays. Write the whole sequence of indices +used for single-dimensional arrays. Write the whole sequence of indices in parentheses, separated by commas, as the left operand: @example @@ -16600,7 +16711,7 @@ This simulates a true two-dimensional array. Each subarray element can contain another subarray as a value, which in turn can hold other arrays as well. In this way, you can create arrays of three or more dimensions. The indices can be any @command{awk} expression, including scalars -separated by commas (that is, a regular @command{awk} simulated +separated by commas (i.e., a regular @command{awk} simulated multidimensional subscript). So the following is valid in @command{gawk}: @@ -16618,8 +16729,8 @@ is itself an array and not a scalar: @example a[4] = "An element in a jagged array" @end example - -The terms @dfn{dimension}, @dfn{row} and @dfn{column} are + +The terms @dfn{dimension}, @dfn{row}, and @dfn{column} are meaningless when applied to such an array, but we will use ``dimension'' henceforth to imply the maximum number of indices needed to refer to an existing element. The @@ -16675,14 +16786,14 @@ The @samp{for (item in array)} statement (@pxref{Scanning an Array}) can be nested to scan all the elements of an array of arrays if it is rectangular in structure. In order to print the contents (scalar values) of a two-dimensional array of arrays -(i.e., in which each first-level element is itself an -array, not necessarily of the same length) +(i.e., in which each first-level element is itself an +array, not necessarily of the same length) you could use the following code: @example for (i in array) for (j in array[i]) - print array[i][j] + print array[i][j] @end example The @code{isarray()} function (@pxref{Type Functions}) @@ -16692,7 +16803,7 @@ lets you test if an array element is itself an array: for (i in array) @{ if (isarray(array[i]) @{ for (j in array[i]) @{ - print array[i][j] + print array[i][j] @} @} else @@ -16702,7 +16813,7 @@ for (i in array) @{ If the structure of a jagged array of arrays is known in advance, you can often devise workarounds using control statements. For example, -the following code prints the elements of our main array @code{a}: +the following code prints the elements of our main array @code{a}: @example for (i in a) @{ @@ -16712,13 +16823,13 @@ for (i in a) @{ print a[i][j][k] @} else print a[i][j] - @} + @} @} @end example @noindent -@xref{Walking Arrays}, for a user-defined function that ``walks'' an -arbitrarily-dimensioned array of arrays. +@DBXREF{Walking Arrays} for a user-defined function that ``walks'' an +arbitrarily dimensioned array of arrays. Recall that a reference to an uninitialized array element yields a value of @code{""}, the null string. This has one important implication when you @@ -16768,8 +16879,9 @@ special predefined values to @code{PROCINFO["sorted_in"]}. @item Use @samp{delete @var{array}[@var{indx}]} to delete an individual element. -You may also use @samp{delete @var{array}} to delete all of the elements -in the array. This latter feature has been a common extension for many +To delete all of the elements in an array, +use @samp{delete @var{array}}. +This latter feature has been a common extension for many years and is now standard, but may not be supported by all commercial versions of @command{awk}. @@ -16807,7 +16919,8 @@ This @value{CHAPTER} describes @command{awk}'s built-in functions, which fall into three categories: numeric, string, and I/O. @command{gawk} provides additional groups of functions to work with values that represent time, do -bit manipulation, sort arrays, and internationalize and localize programs. +bit manipulation, sort arrays, +provide type information, and internationalize and localize programs. Besides the built-in functions, @command{awk} has provisions for writing new functions that the rest of a program can use. @@ -16822,7 +16935,7 @@ The second half of this @value{CHAPTER} describes these @end menu @node Built-in -@section Built-in Functions +@section Built-In Functions @dfn{Built-in} functions are always available for your @command{awk} program to call. This @value{SECTION} defines all @@ -16845,7 +16958,7 @@ but are summarized here for your convenience. @end menu @node Calling Built-in -@subsection Calling Built-in Functions +@subsection Calling Built-In Functions To call one of @command{awk}'s built-in functions, write the name of the function followed @@ -16855,7 +16968,7 @@ is a call to the function @code{atan2()} and has two arguments. @cindex programming conventions, functions, calling @cindex whitespace, functions@comma{} calling Whitespace is ignored between the built-in function name and the -open parenthesis, but nonetheless it is good practice to avoid using whitespace +opening parenthesis, but nonetheless it is good practice to avoid using whitespace there. User-defined functions do not permit whitespace in this way, and it is easier to avoid mistakes by following a simple convention that always works---no whitespace after a function name. @@ -16892,7 +17005,7 @@ right to left. For example: @example i = 5 -j = atan2(i++, i *= 2) +j = atan2(++i, i *= 2) @end example If the order of evaluation is left to right, then @code{i} first becomes @@ -16952,7 +17065,6 @@ depends on your machine's floating-point representation. @cindex round to nearest integer Return the nearest integer to @var{x}, located between @var{x} and zero and truncated toward zero. - For example, @code{int(3)} is 3, @code{int(3.9)} is 3, @code{int(-3.9)} is @minus{}3, and @code{int(-3)} is @minus{}3 as well. @@ -17042,7 +17154,7 @@ for generating random numbers to the value @var{x}. Each seed value leads to a particular sequence of random numbers.@footnote{Computer-generated random numbers really are not truly random. They are technically known as ``pseudorandom.'' This means -that while the numbers in a sequence appear to be random, you can in +that although the numbers in a sequence appear to be random, you can in fact generate the same sequence of random numbers over and over again.} Thus, if the seed is set to the same value a second time, the same sequence of random numbers is produced again. @@ -17092,7 +17204,7 @@ doing index calculations, particularly if you are used to C. In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).} Several functions perform string substitution; the full discussion is provided in the description of the @code{sub()} function, which comes -towards the end since the list is presented alphabetically. +toward the end, because the list is presented alphabetically. Those functions that are specific to @command{gawk} are marked with a pound sign (@samp{#}). They are not available in compatibility mode @@ -17118,10 +17230,10 @@ These two functions are similar in behavior, so they are described together. @quotation NOTE -The following description ignores the third argument, @var{how}, since it +The following description ignores the third argument, @var{how}, as it requires understanding features that we have not discussed yet. Thus, the discussion here is a deliberate simplification. (We do provide all -the details later on: @xref{Array Sorting Functions}, for the full story.) +the details later on; see @DBREF{Array Sorting Functions} for the full story.) @end quotation Both functions return the number of elements in the array @var{source}. @@ -17368,7 +17480,7 @@ at which that substring begins (one, if it starts at the beginning of The @var{regexp} argument may be either a regexp constant (@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}). In the latter case, the string is treated as a regexp to be matched. -@xref{Computed Regexps}, for a +@DBXREF{Computed Regexps} for a discussion of the difference between the two forms, and the implications for writing your program correctly. @@ -17461,7 +17573,7 @@ $ @kbd{echo foooobazbarrrrr |} @end example There may not be subscripts for the start and index for every parenthesized -subexpression, since they may not all have matched text; thus they +subexpression, because they may not all have matched text; thus they should be tested for with the @code{in} operator (@pxref{Reference to Elements}). @@ -17508,15 +17620,15 @@ a regexp describing where to split @var{string} (much as @code{FS} can be a regexp describing where to split input records). If @var{fieldsep} is omitted, the value of @code{FS} is used. @code{split()} returns the number of elements created. -@var{seps} is a @command{gawk} extension with @code{@var{seps}[@var{i}]} +@var{seps} is a @command{gawk} extension with @code{@var{seps}[@var{i}]} being the separator string -between @code{@var{array}[@var{i}]} and @code{@var{array}[@var{i}+1]}. +between @code{@var{array}[@var{i}]} and @code{@var{array}[@var{i}+1]}. If @var{fieldsep} is a single -space then any leading whitespace goes into @code{@var{seps}[0]} and +space then any leading whitespace goes into @code{@var{seps}[0]} and any trailing -whitespace goes into @code{@var{seps}[@var{n}]} where @var{n} is the -return value of -@code{split()} (that is, the number of elements in @var{array}). +whitespace goes into @code{@var{seps}[@var{n}]} where @var{n} is the +return value of +@code{split()} (i.e., the number of elements in @var{array}). The @code{split()} function splits strings into pieces in a manner similar to the way input lines are split into fields. For example: @@ -17552,7 +17664,7 @@ As with input field-splitting, when the value of @var{fieldsep} is the elements of @var{array} but not in @var{seps}, and the elements are separated by runs of whitespace. -Also as with input field-splitting, if @var{fieldsep} is the null string, each +Also, as with input field-splitting, if @var{fieldsep} is the null string, each individual character in the string is split into its own array element. @value{COMMONEXT} @@ -17566,7 +17678,7 @@ the third argument to be a regexp constant (@code{/abc/}) as well as a string. @value{DARKCORNER} The POSIX standard allows this as well. -@xref{Computed Regexps}, for a +@DBXREF{Computed Regexps} for a discussion of the difference between using a string constant or a regexp constant, and the implications for writing your program correctly. @@ -17617,7 +17729,7 @@ Using the @code{strtonum()} function is @emph{not} the same as adding zero to a string value; the automatic coercion of strings to numbers works only for decimal data, not for octal or hexadecimal.@footnote{Unless you use the @option{--non-decimal-data} option, which isn't recommended. -@xref{Nondecimal Data}, for more information.} +@DBXREF{Nondecimal Data} for more information.} Note also that @code{strtonum()} uses the current locale's decimal point for recognizing numbers (@pxref{Locales}). @@ -17635,7 +17747,7 @@ Return the number of substitutions made (zero or one). The @var{regexp} argument may be either a regexp constant (@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}). In the latter case, the string is treated as a regexp to be matched. -@xref{Computed Regexps}, for a +@DBXREF{Computed Regexps} for a discussion of the difference between the two forms, and the implications for writing your program correctly. @@ -17854,7 +17966,7 @@ Although this makes a certain amount of sense, it can be surprising. @node Gory Details -@subsubsection More About @samp{\} and @samp{&} with @code{sub()}, @code{gsub()}, and @code{gensub()} +@subsubsection More about @samp{\} and @samp{&} with @code{sub()}, @code{gsub()}, and @code{gensub()} @cindex escape processing, @code{gsub()}/@code{gensub()}/@code{sub()} functions @cindex @code{sub()} function, escape processing @@ -17901,7 +18013,7 @@ through unchanged. This is illustrated in @ref{table-sub-escapes}. @c Thank to Karl Berry for help with the TeX stuff. @float Table,table-sub-escapes -@caption{Historical Escape Sequence Processing for @code{sub()} and @code{gsub()}} +@caption{Historical escape sequence processing for @code{sub()} and @code{gsub()}} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -17973,7 +18085,7 @@ This is shown in @ref{table-sub-proposed}. @float Table,table-sub-proposed -@caption{GNU @command{awk} Rules For @code{sub()} And Backslash} +@caption{GNU @command{awk} rules for @code{sub()} and backslash} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -18036,7 +18148,7 @@ by anything else is not special; the @samp{\} is placed straight into the output These rules are presented in @ref{table-posix-sub}. @float Table,table-posix-sub -@caption{POSIX Rules For @code{sub()} And @code{gsub()}} +@caption{POSIX rules for @code{sub()} and @code{gsub()}} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -18085,12 +18197,12 @@ is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, -it continued to follow the proposed rules, since +it continued to follow the proposed rules, as that had been its behavior for many years. When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer made the POSIX rules the default, breaking well over a decade's worth -of backwards compatibility.@footnote{This was rather naive of him, despite +of backward compatibility.@footnote{This was rather naive of him, despite there being a note in this section indicating that the next major version would move to the POSIX rules.} Needless to say, this was a bad idea, and as of @value{PVERSION} 4.0.1, @command{gawk} resumed its historical @@ -18105,7 +18217,7 @@ appears in the generated text and the @samp{\} does not, as shown in @ref{table-gensub-escapes}. @float Table,table-gensub-escapes -@caption{Escape Sequence Processing For @code{gensub()}} +@caption{Escape sequence processing for @code{gensub()}} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -18172,7 +18284,7 @@ Optional parameters are enclosed in square brackets ([ ]): Close the file @var{filename} for input or output. Alternatively, the argument may be a shell command that was used for creating a coprocess, or for redirecting to or from a pipe; then the coprocess or pipe is closed. -@xref{Close Files And Pipes}, +@DBXREF{Close Files And Pipes} for more information. When closing a coprocess, it is occasionally useful to first close @@ -18196,13 +18308,13 @@ a pipe or coprocess. @cindex buffers, flushing @cindex output, buffering -Many utility programs @dfn{buffer} their output; i.e., they save information +Many utility programs @dfn{buffer} their output (i.e., they save information to write to a disk file or the screen in memory until there is enough -for it to be worthwhile to send the data to the output device. +for it to be worthwhile to send the data to the output device). This is often more efficient than writing every little bit of information as soon as it is ready. However, sometimes -it is necessary to force a program to @dfn{flush} its buffers; that is, -write the information to its destination, even if a buffer is not full. +it is necessary to force a program to @dfn{flush} its buffers (i.e., +write the information to its destination, even if a buffer is not full). This is the purpose of the @code{fflush()} function---@command{gawk} also buffers its output and the @code{fflush()} function forces @command{gawk} to flush its buffers. @@ -18210,11 +18322,11 @@ buffers its output and the @code{fflush()} function forces @cindex extensions, common@comma{} @code{fflush()} function @cindex Brian Kernighan's @command{awk} Brian Kernighan added @code{fflush()} to his @command{awk} in April -of 1992. For two decades, it was a common extension. In December, +1992. For two decades, it was a common extension. In December 2012, it was accepted for inclusion into the POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=634, the Austin Group website}. -POSIX standardizes @code{fflush()} as follows: If there +POSIX standardizes @code{fflush()} as follows: if there is no argument, or if the argument is the null string (@w{@code{""}}), then @command{awk} flushes the buffers for @emph{all} open output files and pipes. @@ -18246,53 +18358,6 @@ a file or pipe that was opened for reading (such as with @code{getline}), or if @var{filename} is not an open file, pipe, or coprocess. In such a case, @code{fflush()} returns @minus{}1, as well. -@item @code{system(@var{command})} -@cindexawkfunc{system} -@cindex invoke shell command -@cindex interacting with other programs -Execute the operating-system -command @var{command} and then return to the @command{awk} program. -Return @var{command}'s exit status. - -For example, if the following fragment of code is put in your @command{awk} -program: - -@example -END @{ - system("date | mail -s 'awk run done' root") -@} -@end example - -@noindent -the system administrator is sent mail when the @command{awk} program -finishes processing input and begins its end-of-input processing. - -Note that redirecting @code{print} or @code{printf} into a pipe is often -enough to accomplish your task. If you need to run many commands, it -is more efficient to simply print them down a pipeline to the shell: - -@example -while (@var{more stuff to do}) - print @var{command} | "/bin/sh" -close("/bin/sh") -@end example - -@noindent -@cindex troubleshooting, @code{system()} function -@cindex @option{--sandbox} option, disabling @code{system()} function -However, if your @command{awk} -program is interactive, @code{system()} is useful for running large -self-contained programs, such as a shell or an editor. -Some operating systems cannot implement the @code{system()} function. -@code{system()} causes a fatal error if it is not supported. - -@quotation NOTE -When @option{--sandbox} is specified, the @code{system()} function is disabled -(@pxref{Options}). -@end quotation - -@end table - @cindex sidebar, Interactive Versus Noninteractive Buffering @ifdocbook @docbook @@ -18302,15 +18367,15 @@ When @option{--sandbox} is specified, the @code{system()} function is disabled @cindex buffering, interactive vs.@: noninteractive As a side point, buffering issues can be even more confusing, depending -upon whether your program is @dfn{interactive}, i.e., communicating -with a user sitting at a keyboard.@footnote{A program is interactive +upon whether your program is @dfn{interactive} (i.e., communicating +with a user sitting at a keyboard).@footnote{A program is interactive if the standard output is connected to a terminal device. On modern systems, this means your keyboard and screen.} @c Thanks to Walter.Mecky@dresdnerbank.de for this example, and for @c motivating me to write this section. -Interactive programs generally @dfn{line buffer} their output; i.e., they -write out every line. Noninteractive programs wait until they have +Interactive programs generally @dfn{line buffer} their output (i.e., they +write out every line). Noninteractive programs wait until they have a full buffer, which may be many lines of output. Here is an example of the difference: @@ -18353,15 +18418,15 @@ it is all buffered and sent down the pipe to @command{cat} in one shot. @cindex buffering, interactive vs.@: noninteractive As a side point, buffering issues can be even more confusing, depending -upon whether your program is @dfn{interactive}, i.e., communicating -with a user sitting at a keyboard.@footnote{A program is interactive +upon whether your program is @dfn{interactive} (i.e., communicating +with a user sitting at a keyboard).@footnote{A program is interactive if the standard output is connected to a terminal device. On modern systems, this means your keyboard and screen.} @c Thanks to Walter.Mecky@dresdnerbank.de for this example, and for @c motivating me to write this section. -Interactive programs generally @dfn{line buffer} their output; i.e., they -write out every line. Noninteractive programs wait until they have +Interactive programs generally @dfn{line buffer} their output (i.e., they +write out every line). Noninteractive programs wait until they have a full buffer, which may be many lines of output. Here is an example of the difference: @@ -18393,6 +18458,53 @@ it is all buffered and sent down the pipe to @command{cat} in one shot. @end cartouche @end ifnotdocbook +@item @code{system(@var{command})} +@cindexawkfunc{system} +@cindex invoke shell command +@cindex interacting with other programs +Execute the operating-system +command @var{command} and then return to the @command{awk} program. +Return @var{command}'s exit status. + +For example, if the following fragment of code is put in your @command{awk} +program: + +@example +END @{ + system("date | mail -s 'awk run done' root") +@} +@end example + +@noindent +the system administrator is sent mail when the @command{awk} program +finishes processing input and begins its end-of-input processing. + +Note that redirecting @code{print} or @code{printf} into a pipe is often +enough to accomplish your task. If you need to run many commands, it +is more efficient to simply print them down a pipeline to the shell: + +@example +while (@var{more stuff to do}) + print @var{command} | "/bin/sh" +close("/bin/sh") +@end example + +@noindent +@cindex troubleshooting, @code{system()} function +@cindex @option{--sandbox} option, disabling @code{system()} function +However, if your @command{awk} +program is interactive, @code{system()} is useful for running large +self-contained programs, such as a shell or an editor. +Some operating systems cannot implement the @code{system()} function. +@code{system()} causes a fatal error if it is not supported. + +@quotation NOTE +When @option{--sandbox} is specified, the @code{system()} function is disabled +(@pxref{Options}). +@end quotation + +@end table + @cindex sidebar, Controlling Output Buffering with @code{system()} @ifdocbook @docbook @@ -18416,7 +18528,7 @@ system("") # flush output @command{gawk} treats this use of the @code{system()} function as a special case and is smart enough not to run a shell (or other command interpreter) with the empty command. Therefore, with @command{gawk}, this -idiom is not only useful, it is also efficient. While this method should work +idiom is not only useful, it is also efficient. Although this method should work with other @command{awk} implementations, it does not necessarily avoid starting an unnecessary shell. (Other implementations may only flush the buffer associated with the standard output and not necessarily @@ -18481,7 +18593,7 @@ system("") # flush output @command{gawk} treats this use of the @code{system()} function as a special case and is smart enough not to run a shell (or other command interpreter) with the empty command. Therefore, with @command{gawk}, this -idiom is not only useful, it is also efficient. While this method should work +idiom is not only useful, it is also efficient. Although this method should work with other @command{awk} implementations, it does not necessarily avoid starting an unnecessary shell. (Other implementations may only flush the buffer associated with the standard output and not necessarily @@ -18621,14 +18733,14 @@ Mean Time). Otherwise, the value is formatted for the local time zone. The @var{timestamp} is in the same format as the value returned by the @code{systime()} function. If no @var{timestamp} argument is supplied, @command{gawk} uses the current time of day as the timestamp. -If no @var{format} argument is supplied, @code{strftime()} uses +Without a @var{format} argument, @code{strftime()} uses the value of @code{PROCINFO["strftime"]} as the format string (@pxref{Built-in Variables}). The default string value is @code{@w{"%a %b %e %H:%M:%S %Z %Y"}}. This format string produces output that is equivalent to that of the @command{date} utility. You can assign a new value to @code{PROCINFO["strftime"]} to -change the default format; see below for the various format directives. +change the default format; see the following list for the various format directives. @item @code{systime()} @cindexgawkfunc{systime} @@ -18705,16 +18817,16 @@ This is the ISO 8601 date format. @item %g The year modulo 100 of the ISO 8601 week number, as a decimal number (00--99). -For example, January 1, 2012 is in week 53 of 2011. Thus, the year +For example, January 1, 2012, is in week 53 of 2011. Thus, the year of its ISO 8601 week number is 2011, even though its year is 2012. -Similarly, December 31, 2012 is in week 1 of 2013. Thus, the year +Similarly, December 31, 2012, is in week 1 of 2013. Thus, the year of its ISO week number is 2013, even though its year is 2012. @item %G The full year of the ISO week number, as a decimal number. @item %h -Equivalent to @code{%b}. +Equivalent to @samp{%b}. @item %H The hour (24-hour clock) as a decimal number (00--23). @@ -18783,7 +18895,7 @@ The locale's ``appropriate'' date representation. @item %X The locale's ``appropriate'' time representation. -(This is @code{%T} in the @code{"C"} locale.) +(This is @samp{%T} in the @code{"C"} locale.) @item %y The year modulo 100 as a decimal number (00--99). @@ -18803,8 +18915,8 @@ no time zone is determinable. @item %Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH @itemx %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy -``Alternate representations'' for the specifications -that use only the second letter (@code{%c}, @code{%C}, +``Alternative representations'' for the specifications +that use only the second letter (@samp{%c}, @samp{%C}, and so on).@footnote{If you don't understand any of this, don't worry about it; these facilities are meant to make it easier to ``internationalize'' programs. @@ -18816,7 +18928,7 @@ Other internationalization features are described in A literal @samp{%}. @end table -If a conversion specifier is not one of the above, the behavior is +If a conversion specifier is not one of those just listed, the behavior is undefined.@footnote{This is because ISO C leaves the behavior of the C version of @code{strftime()} undefined and @command{gawk} uses the system's version of @code{strftime()} if it's there. @@ -18843,11 +18955,11 @@ Single-digit numbers are padded with a space. @ignore @item %N The ``Emperor/Era'' name. -Equivalent to @code{%C}. +Equivalent to @samp{%C}. @item %o The ``Emperor/Era'' year. -Equivalent to @code{%y}. +Equivalent to @samp{%y}. @end ignore @item %s @@ -18860,7 +18972,7 @@ The date in VMS format (e.g., @samp{20-JUN-1991}). @end table @c ENDOFRANGE strf -Additionally, the alternate representations are recognized but their +Additionally, the alternative representations are recognized but their normal representations are used. @cindex @code{date} utility, POSIX @@ -18874,7 +18986,7 @@ interprets the current time according to the format specifiers in the string. For example: @example -$ date '+Today is %A, %B %d, %Y.' +$ @kbd{date '+Today is %A, %B %d, %Y.'} @print{} Today is Monday, September 22, 2014. @end example @@ -18938,8 +19050,10 @@ each successive pair of bits in the operands. Three common operations are bitwise AND, OR, and XOR. The operations are described in @ref{table-bitwise-ops}. +@c 11/2014: Postprocessing turns the docbook informaltable +@c into a table. Hurray for scripting! @float Table,table-bitwise-ops -@caption{Bitwise Operations} +@caption{Bitwise operations} @ifnottex @ifnotdocbook @display @@ -19107,7 +19221,7 @@ Return the value of @var{val}, shifted right by @var{count} bits. Return the bitwise XOR of the arguments. There must be at least two. @end table -For all of these functions, first the double precision floating-point value is +For all of these functions, first the double-precision floating-point value is converted to the widest C unsigned integer type, then the bitwise operation is performed. If the result cannot be represented exactly as a C @code{double}, leading nonzero bits are removed one by one until it can be represented @@ -19206,7 +19320,7 @@ Otherwise, a @code{"0"} is added. The value is then shifted right by one bit and the loop continues until there are no more 1 bits. -If the initial value is zero it returns a simple @code{"0"}. +If the initial value is zero, it returns a simple @code{"0"}. Otherwise, at the end, it pads the value with zeros to represent multiples of 8-bit quantities. This is typical in modern computers. @@ -19243,8 +19357,8 @@ an array or not. The second is inside the body of a user-defined function array or not. @quotation NOTE -Using @code{isarray()} at the global level to test -variables makes no sense. Since you are the one writing the program, you +Using @code{isarray()} at the global level to test +variables makes no sense. Because you are the one writing the program, you are supposed to know if your variables are arrays or not. And in fact, due to the way @command{gawk} works, if you pass the name of a variable that has not been previously used to @code{isarray()}, @command{gawk} @@ -19312,7 +19426,7 @@ The default value for @var{category} is @code{"LC_MESSAGES"}. Complicated @command{awk} programs can often be simplified by defining your own functions. User-defined functions can be called just like built-in ones (@pxref{Function Calls}), but it is up to you to define -them, i.e., to tell @command{awk} what they should do. +them (i.e., to tell @command{awk} what they should do). @menu * Definition Syntax:: How to write definitions and what they mean. @@ -19451,13 +19565,13 @@ func foo() @{ a = sqrt($1) ; print a @} @end example @noindent -Instead it defines a rule that, for each record, concatenates the value +Instead, it defines a rule that, for each record, concatenates the value of the variable @samp{func} with the return value of the function @samp{foo}. If the resulting string is non-null, the action is executed. This is probably not what is desired. (@command{awk} accepts this input as syntactically valid, because functions may be used before they are defined in @command{awk} programs.@footnote{This program won't actually run, -since @code{foo()} is undefined.}) +because @code{foo()} is undefined.}) @cindex portability, functions@comma{} defining To ensure that your @command{awk} programs are portable, always use the @@ -19528,7 +19642,7 @@ The following is an example of a recursive function. It takes a string as an input parameter and returns the string in backwards order. Recursive functions must always have a test that stops the recursion. In this case, the recursion terminates when the input string is -already empty. +already empty: @c 8/2014: Thanks to Mike Brennan for the improved formulation @cindex @code{rev()} user-defined function @@ -19576,7 +19690,7 @@ function ctime(ts, format) @end example You might think that @code{ctime()} could use @code{PROCINFO["strftime"]} -for its format string. That would be a mistake, since @code{ctime()} is +for its format string. That would be a mistake, because @code{ctime()} is supposed to return the time formatted in a standard fashion, and user-level code could have changed @code{PROCINFO["strftime"]}. @c ENDOFRANGE fdef @@ -19597,7 +19711,7 @@ the function. @end menu @node Calling A Function -@subsubsection Writing A Function Call +@subsubsection Writing a Function Call A function call consists of the function name followed by the arguments in parentheses. @command{awk} expressions are what you write in the @@ -19612,7 +19726,7 @@ foo(x y, "lose", 4 * z) @quotation CAUTION Whitespace characters (spaces and TABs) are not allowed -between the function name and the open-parenthesis of the argument list. +between the function name and the opening parenthesis of the argument list. If you write whitespace by mistake, @command{awk} might think that you mean to concatenate a variable with an expression in parentheses. However, it notices that you used a function name and not a variable name, and reports @@ -19652,7 +19766,7 @@ function foo(j) print "foo's i=" i @} -BEGIN @{ +BEGIN @{ i = 10 print "top's i=" i foo(0) @@ -19675,13 +19789,13 @@ top's i=3 @end example If you want @code{i} to be local to both @code{foo()} and @code{bar()} do as -follows (the extra-space before @code{i} is a coding convention to +follows (the extra space before @code{i} is a coding convention to indicate that @code{i} is a local variable, not an argument): @example function bar( i) @{ - for (i = 0; i < 3; i++) + for (i = 0; i < 3; i++) print "bar's i=" i @} @@ -19693,10 +19807,10 @@ function foo(j, i) print "foo's i=" i @} -BEGIN @{ +BEGIN @{ i = 10 print "top's i=" i - foo(0) + foo(0) print "top's i=" i @} @end example @@ -19755,21 +19869,16 @@ At level 2, index 2 is found in a @end example @node Pass By Value/Reference -@subsubsection Passing Function Arguments By Value Or By Reference +@subsubsection Passing Function Arguments by Value Or by Reference In @command{awk}, when you declare a function, there is no way to declare explicitly whether the arguments are passed @dfn{by value} or @dfn{by reference}. -Instead the passing convention is determined at runtime when +Instead, the passing convention is determined at runtime when the function is called according to the following rule: - -@itemize -@item -If the argument is an array variable, then it is passed by reference, -@item -Otherwise the argument is passed by value. -@end itemize +if the argument is an array variable, then it is passed by reference. +Otherwise, the argument is passed by value. @cindex call by value Passing an argument by value means that when a function is called, it @@ -19872,7 +19981,13 @@ If @option{--lint} is specified Some @command{awk} implementations generate a runtime error if you use either the @code{next} statement or the @code{nextfile} statement -(@pxref{Next Statement}, also @pxref{Nextfile Statement}) +(@pxref{Next Statement}, and +@ifdocbook +@ref{Nextfile Statement}) +@end ifdocbook +@ifnotdocbook +@pxref{Nextfile Statement}) +@end ifnotdocbook inside a user-defined function. @command{gawk} does not have this limitation. @c ENDOFRANGE fudc @@ -19928,8 +20043,8 @@ function maxelt(vec, i, ret) @noindent You call @code{maxelt()} with one argument, which is an array name. The local variables @code{i} and @code{ret} are not intended to be arguments; -while there is nothing to stop you from passing more than one argument -to @code{maxelt()}, the results would be strange. The extra space before +there is nothing to stop you from passing more than one argument +to @code{maxelt()} but the results would be strange. The extra space before @code{i} in the function parameter list indicates that @code{i} and @code{ret} are local variables. You should follow this convention when defining functions. @@ -20066,8 +20181,8 @@ variable as the @emph{name} of the function to call. @cindex indirect function calls, @code{@@}-notation @cindex function calls, indirect, @code{@@}-notation for The syntax is similar to that of a regular function call: an identifier -immediately followed by a left parenthesis, any arguments, and then -a closing right parenthesis, with the addition of a leading @samp{@@} +immediately followed by an opening parenthesis, any arguments, and then +a closing parenthesis, with the addition of a leading @samp{@@} character: @example @@ -20076,7 +20191,7 @@ result = @@the_func() # calls the sum() function @end example Here is a full program that processes the previously shown data, -using indirect function calls. +using indirect function calls: @example @c file eg/prog/indirectcall.awk @@ -20117,7 +20232,7 @@ function sum(first, last, ret, i) These two functions expect to work on fields; thus the parameters @code{first} and @code{last} indicate where in the fields to start and end. -Otherwise they perform the expected computations and are not unusual. +Otherwise they perform the expected computations and are not unusual: @example @c file eg/prog/indirectcall.awk @@ -20150,7 +20265,7 @@ saving it in @code{start}. The last part of the code loops through each function name (from @code{$2} up to the marker, @samp{data:}), calling the function named by the field. The indirect function call itself occurs as a parameter in the call to @code{printf}. -(The @code{printf} format string uses @code{%s} as the format specifier so that we +(The @code{printf} format string uses @samp{%s} as the format specifier so that we can use functions that return strings, as well as numbers. Note that the result from the indirect call is concatenated with the empty string, in order to force it to be a string value.) @@ -20162,11 +20277,11 @@ $ @kbd{gawk -f indirectcall.awk class_data1} @print{} Biology 101: @print{} sum: <352.8> @print{} average: <88.2> -@print{} +@print{} @print{} Chemistry 305: @print{} sum: <356.4> @print{} average: <89.1> -@print{} +@print{} @print{} English 401: @print{} sum: <376.1> @print{} average: <94.025> @@ -20288,7 +20403,7 @@ function do_sort(first, last, compare, data, i, retval) retval = data[1] for (i = 2; i in data; i++) retval = retval " " data[i] - + return retval @} @c endfile @@ -20334,13 +20449,13 @@ $ @kbd{gawk -f quicksort.awk -f indirectcall.awk class_data2} @print{} average: <88.2> @print{} sort: <78.5 87.0 92.4 94.9> @print{} rsort: <94.9 92.4 87.0 78.5> -@print{} +@print{} @print{} Chemistry 305: @print{} sum: <356.4> @print{} average: <89.1> @print{} sort: <75.2 88.2 94.7 98.3> @print{} rsort: <98.3 94.7 88.2 75.2> -@print{} +@print{} @print{} English 401: @print{} sum: <376.1> @print{} average: <94.025> @@ -20443,7 +20558,7 @@ functions. POSIX @command{awk} provides three kinds of built-in functions: numeric, string, and I/O. @command{gawk} provides functions that sort arrays, work with values representing time, do bit manipulation, determine variable -type (array vs.@: scalar), and internationalize and localize programs. +type (array versus scalar), and internationalize and localize programs. @command{gawk} also provides several extensions to some of standard functions, typically in the form of additional arguments. @@ -20499,7 +20614,7 @@ program. This is equivalent to function pointers in C and C++. @c ENDOFRANGE funcud @ifnotinfo -@part @value{PART2}Problem Solving With @command{awk} +@part @value{PART2}Problem Solving with @command{awk} @end ifnotinfo @ifdocbook @@ -20509,10 +20624,10 @@ It contains the following chapters: @itemize @value{BULLET} @item -@ref{Library Functions}. +@ref{Library Functions} @item -@ref{Sample Programs}. +@ref{Sample Programs} @end itemize @end ifdocbook @@ -20573,9 +20688,9 @@ and would like to contribute them to the @command{awk} user community, see @cindex portability, example programs The programs in this @value{CHAPTER} and in @ref{Sample Programs}, -freely use features that are @command{gawk}-specific. +freely use @command{gawk}-specific features. Rewriting these programs for different implementations of @command{awk} -is pretty straightforward. +is pretty straightforward: @itemize @value{BULLET} @item @@ -20645,7 +20760,7 @@ Library functions often need to have global variables that they can use to preserve state information between calls to the function---for example, @code{getopt()}'s variable @code{_opti} (@pxref{Getopt Function}). -Such variables are called @dfn{private}, since the only functions that need to +Such variables are called @dfn{private}, as the only functions that need to use them are the ones in the library. When writing a library function, you should try to choose names for your @@ -20667,10 +20782,10 @@ In addition, several of the library functions use a prefix that helps indicate what function or set of functions use the variables---for example, @code{_pw_byname()} in the user database routines (@pxref{Passwd Functions}). -This convention is recommended, since it even further decreases the +This convention is recommended, as it even further decreases the chance of inadvertent conflict among variable names. Note that this convention is used equally well for variable names and for private -function names.@footnote{While all the library routines could have +function names.@footnote{Although all the library routines could have been rewritten to use this convention, this was not done, in order to show how our own @command{awk} programming style has evolved and to provide some basis for this discussion.} @@ -20743,7 +20858,7 @@ programming use. @end menu @node Strtonum Function -@subsection Converting Strings To Numbers +@subsection Converting Strings to Numbers The @code{strtonum()} function (@pxref{String Functions}) is a @command{gawk} extension. The following function @@ -20811,7 +20926,7 @@ function mystrtonum(str, ret, n, i, k, c) # a[6] = "1.e3" # a[7] = "1.32" # a[8] = "1.32E2" -# +# # for (i = 1; i in a; i++) # print a[i], strtonum(a[i]), mystrtonum(a[i]) # @} @@ -20825,7 +20940,7 @@ string. It sets @code{k} to the index in @code{"1234567"} of the current octal digit. The return value will either be the same number as the digit, or zero if the character is not there, which will be true for a @samp{0}. -This is safe, since the regexp test in the @code{if} ensures that +This is safe, because the regexp test in the @code{if} ensures that only octal values are converted. Similar logic applies to the code that checks for and converts a @@ -21172,7 +21287,7 @@ is always 1. This means that on those systems, characters have numeric values from 128 to 255. Finally, large mainframe systems use the EBCDIC character set, which uses all 256 values. -While there are other character sets in use on some older systems, +There are other character sets in use on some older systems, but they are not really worth worrying about: @example @@ -21226,7 +21341,7 @@ Good function design is important; this function needs to be general but it should also have a reasonable default behavior. It is called with an array as well as the beginning and ending indices of the elements in the array to be merged. This assumes that the array indices are numeric---a reasonable -assumption since the array was likely created with @code{split()} +assumption, as the array was likely created with @code{split()} (@pxref{String Functions}): @cindex @code{join()} user-defined function @@ -21279,7 +21394,7 @@ more difficult than they really need to be.} The @code{systime()} and @code{strftime()} functions described in @DBREF{Time Functions} provide the minimum functionality necessary for dealing with the time of day -in human readable form. While @code{strftime()} is extensive, the control +in human-readable form. Although @code{strftime()} is extensive, the control formats are not necessarily easy to remember or intuitively obvious when reading a program. @@ -21370,7 +21485,7 @@ allowed the user to supply an optional timestamp value to use instead of the current time. @node Readfile Function -@subsection Reading A Whole File At Once +@subsection Reading a Whole File At Once Often, it is convenient to have the entire contents of a file available in memory as a single string. A straightforward but naive way to @@ -21430,7 +21545,7 @@ will never match if the file has contents. @command{gawk} reads data from the file into @code{tmp} attempting to match @code{RS}. The match fails after each read, but fails quickly, such that @command{gawk} fills @code{tmp} with the entire contents of the file. -(@xref{Records}, for information on @code{RT} and @code{RS}.) +(@DBXREF{Records} for information on @code{RT} and @code{RS}.) In the case that @code{file} is empty, the return value is the null string. Thus calling code may use something like: @@ -21448,7 +21563,7 @@ test would be @samp{contents == ""}. also reads an entire file into memory. @node Shell Quoting -@subsection Quoting Strings to Pass to The Shell +@subsection Quoting Strings to Pass to the Shell @c included by permission @ignore @@ -21490,7 +21605,7 @@ chmod -w file.flac Note the need for shell quoting. The function @code{shell_quote()} does it. @code{SINGLE} is the one-character string @code{"'"} and -@code{QSINGLE} is the three-character string @code{"\"'\""}. +@code{QSINGLE} is the three-character string @code{"\"'\""}: @example @c file eg/lib/shellquote.awk @@ -21550,7 +21665,7 @@ command-line @value{DF}s. @cindex files, managing, data file boundaries @cindex files, initialization and cleanup -The @code{BEGIN} and @code{END} rules are each executed exactly once at +The @code{BEGIN} and @code{END} rules are each executed exactly once, at the beginning and end of your @command{awk} program, respectively (@pxref{BEGIN/END}). We (the @command{gawk} authors) once had a user who mistakenly thought that the @@ -21622,7 +21737,7 @@ The following version solves the problem: @example @c file eg/lib/ftrans.awk -# ftrans.awk --- handle data file transitions +# ftrans.awk --- handle datafile transitions # # user supplies beginfile() and endfile() functions @c endfile @@ -21650,10 +21765,10 @@ END @{ endfile(_filename_) @} shows how this library function can be used and how it simplifies writing the main program. -@cindex sidebar, So Why Does @command{gawk} have @code{BEGINFILE} and @code{ENDFILE}? +@cindex sidebar, So Why Does @command{gawk} Have @code{BEGINFILE} and @code{ENDFILE}? @ifdocbook @docbook -<sidebar><title>So Why Does @command{gawk} have @code{BEGINFILE} and @code{ENDFILE}?</title> +<sidebar><title>So Why Does @command{gawk} Have @code{BEGINFILE} and @code{ENDFILE}?</title> @end docbook @@ -21663,7 +21778,7 @@ functions can do the job, why does @command{gawk} have Good question. Normally, if @command{awk} cannot open a file, this causes an immediate fatal error. In this case, there is no way for a -user-defined function to deal with the problem, since the mechanism for +user-defined function to deal with the problem, as the mechanism for calling it relies on the file being open and at the first record. Thus, the main reason for @code{BEGINFILE} is to give you a ``hook'' to catch files that cannot be processed. @code{ENDFILE} exists for symmetry, @@ -21676,7 +21791,7 @@ and because it provides an easy way to do per-file cleanup processing. @ifnotdocbook @cartouche -@center @b{So Why Does @command{gawk} have @code{BEGINFILE} and @code{ENDFILE}?} +@center @b{So Why Does @command{gawk} Have @code{BEGINFILE} and @code{ENDFILE}?} @@ -21686,7 +21801,7 @@ functions can do the job, why does @command{gawk} have Good question. Normally, if @command{awk} cannot open a file, this causes an immediate fatal error. In this case, there is no way for a -user-defined function to deal with the problem, since the mechanism for +user-defined function to deal with the problem, as the mechanism for calling it relies on the file being open and at the first record. Thus, the main reason for @code{BEGINFILE} is to give you a ``hook'' to catch files that cannot be processed. @code{ENDFILE} exists for symmetry, @@ -21745,8 +21860,8 @@ The @code{rewind()} function relies on the @code{ARGIND} variable (@pxref{Auto-set}), which is specific to @command{gawk}. It also relies on the @code{nextfile} keyword (@pxref{Nextfile Statement}). Because of this, you should not call it from an @code{ENDFILE} rule. -(This isn't necessary anyway, since as soon as an @code{ENDFILE} rule -finishes @command{gawk} goes to the next file!) +(This isn't necessary anyway, because @command{gawk} goes to the next +file as soon as an @code{ENDFILE} rule finishes!) @node File Checking @subsection Checking for Readable @value{DDF}s @@ -21794,19 +21909,19 @@ BEGIN @{ @cindex troubleshooting, @code{getline} function This works, because the @code{getline} won't be fatal. Removing the element from @code{ARGV} with @code{delete} -skips the file (since it's no longer in the list). +skips the file (because it's no longer in the list). See also @ref{ARGC and ARGV}. -The regular expression check purposely does not use character classes +Because @command{awk} variable names only allow the English letters, +the regular expression check purposely does not use character classes such as @samp{[:alpha:]} and @samp{[:alnum:]} (@pxref{Bracket Expressions}) -since @command{awk} variable names only allow the English letters. @node Empty Files @subsection Checking for Zero-length Files All known @command{awk} implementations silently skip over zero-length files. -This is a by-product of @command{awk}'s implicit +This is a by-product of @command{awk}'s implicit read-a-record-and-match-against-the-rules loop: when @command{awk} tries to read a record from an empty file, it immediately receives an end of file indication, closes the file, and proceeds on to the next @@ -21942,12 +22057,12 @@ are left alone. @c STARTOFRANGE clibf @cindex functions, library, C library @cindex arguments, processing -Most utilities on POSIX compatible systems take options on +Most utilities on POSIX-compatible systems take options on the command line that can be used to change the way a program behaves. @command{awk} is an example of such a program (@pxref{Options}). -Often, options take @dfn{arguments}; i.e., data that the program needs to -correctly obey the command-line option. For example, @command{awk}'s +Often, options take @dfn{arguments} (i.e., data that the program needs to +correctly obey the command-line option). For example, @command{awk}'s @option{-F} option requires a string to use as the field separator. The first occurrence on the command line of either @option{--} or a string that does not begin with @samp{-} ends the options. @@ -22051,7 +22166,7 @@ necessary for accessing individual characters (@pxref{String Functions}).@footnote{This function was written before @command{gawk} acquired the ability to split strings into single characters using @code{""} as the separator. -We have left it alone, since using @code{substr()} is more portable.} +We have left it alone, as using @code{substr()} is more portable.} The discussion that follows walks through the code a bit at a time: @@ -22219,9 +22334,9 @@ next element in @code{argv}. If neither condition is true, then only on the next call to @code{getopt()}. The @code{BEGIN} rule initializes both @code{Opterr} and @code{Optind} to one. -@code{Opterr} is set to one, since the default behavior is for @code{getopt()} +@code{Opterr} is set to one, because the default behavior is for @code{getopt()} to print a diagnostic message upon seeing an invalid option. @code{Optind} -is set to one, since there's no reason to look at the program name, which is +is set to one, because there's no reason to look at the program name, which is in @code{ARGV[0]}: @example @@ -22271,16 +22386,22 @@ etc., as its own options. @quotation NOTE After @code{getopt()} is through, -user level code must clear out all the elements of @code{ARGV} from 1 +user-level code must clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the command-line options as @value{FN}s. @end quotation Using @samp{#!} with the @option{-E} option may help avoid conflicts between your program's options and @command{gawk}'s options, -since @option{-E} causes @command{gawk} to abandon processing of +as @option{-E} causes @command{gawk} to abandon processing of further options -(@pxref{Executable Scripts}, and @pxref{Options}). +(@DBPXREF{Executable Scripts} and +@ifnotdocbook +@pxref{Options}). +@end ifnotdocbook +@ifdocbook +@ref{Options}). +@end ifdocbook Several of the sample programs presented in @ref{Sample Programs}, @@ -22310,7 +22431,7 @@ However, because these are numbers, they do not provide very useful information to the average user. There needs to be some way to find the user information associated with the user and group ID numbers. This @value{SECTION} presents a suite of functions for retrieving information from the -user database. @xref{Group Functions}, +user database. @DBXREF{Group Functions} for a similar suite that retrieves information from the group database. @cindex @code{getpwent()} function (C library) @@ -22329,7 +22450,7 @@ The ``password'' comes from the original user database file, encrypted passwords (hence the name). @cindex @command{pwcat} program -While an @command{awk} program could simply read @file{/etc/passwd} +Although an @command{awk} program could simply read @file{/etc/passwd} directly, this file may not contain complete information about the system's set of users.@footnote{It is often the case that password information is stored in a network database.} To be sure you are able to @@ -22424,12 +22545,12 @@ The user's encrypted password. This may not be available on some systems. @item User-ID The user's numeric user ID number. -(On some systems it's a C @code{long}, and not an @code{int}. Thus +(On some systems, it's a C @code{long}, and not an @code{int}. Thus we cast it to @code{long} for all cases.) @item Group-ID The user's numeric group ID number. -(Similar comments about @code{long} vs.@: @code{int} apply here.) +(Similar comments about @code{long} versus @code{int} apply here.) @item Full name The user's full name, and perhaps other information associated with the @@ -22451,7 +22572,7 @@ A few lines representative of @command{pwcat}'s output are as follows: @cindex Robbins, Miriam @example $ @kbd{pwcat} -@print{} root:3Ov02d5VaUPB6:0:1:Operator:/:/bin/sh +@print{} root:x:0:1:Operator:/:/bin/sh @print{} nobody:*:65534:65534::/: @print{} daemon:*:1:1::/: @print{} sys:*:2:2::/:/bin/csh @@ -22530,7 +22651,7 @@ The function @code{_pw_init()} fills three copies of the user information into three associative arrays. The arrays are indexed by username (@code{_pw_byname}), by user ID number (@code{_pw_byuid}), and by order of occurrence (@code{_pw_bycount}). -The variable @code{_pw_inited} is used for efficiency, since @code{_pw_init()} +The variable @code{_pw_inited} is used for efficiency, as @code{_pw_init()} needs to be called only once. @cindex @code{PROCINFO} array, testing the field splitting @@ -22539,7 +22660,7 @@ Because this function uses @code{getline} to read information from @command{pwcat}, it first saves the values of @code{FS}, @code{RS}, and @code{$0}. It notes in the variable @code{using_fw} whether field splitting with @code{FIELDWIDTHS} is in effect or not. -Doing so is necessary, since these functions could be called +Doing so is necessary, as these functions could be called from anywhere within a user's program, and the user may have his or her own way of splitting records and fields. This makes it possible to restore the correct @@ -22641,7 +22762,7 @@ In turn, calling @code{_pw_init()} is not too expensive, because the once. If you are worried about squeezing every last cycle out of your @command{awk} program, the check of @code{_pw_inited} could be moved out of @code{_pw_init()} and duplicated in all the other functions. In practice, -this is not necessary, since most @command{awk} programs are I/O-bound, +this is not necessary, as most @command{awk} programs are I/O-bound, and such a change would clutter up the code. The @command{id} program in @DBREF{Id Program} @@ -22780,7 +22901,7 @@ the association of name to number must be unique within the file. we cast it to @code{long} for all cases.) @item Group Member List -A comma-separated list of user names. These users are members of the group. +A comma-separated list of usernames. These users are members of the group. Modern Unix systems allow users to be members of several groups simultaneously. If your system does, then there are elements @code{"group1"} through @code{"group@var{N}"} in @code{PROCINFO} @@ -22895,7 +23016,7 @@ is being used, and to restore the appropriate field splitting mechanism. The group information is stored is several associative arrays. The arrays are indexed by group name (@code{@w{_gr_byname}}), by group ID number (@code{@w{_gr_bygid}}), and by position in the database (@code{@w{_gr_bycount}}). -There is an additional array indexed by user name (@code{@w{_gr_groupsbyuser}}), +There is an additional array indexed by username (@code{@w{_gr_groupsbyuser}}), which is a space-separated list of groups to which each user belongs. Unlike the user database, it is possible to have multiple records in the @@ -22908,7 +23029,7 @@ tvpeople:*:101:david,conan,tom,joan @end example For this reason, @code{_gr_init()} looks to see if a group name or -group ID number is already seen. If it is, then the user names are +group ID number is already seen. If it is, the usernames are simply concatenated onto the previous list of users.@footnote{There is actually a subtle problem with the code just presented. Suppose that the first time there were no names. This code adds the names with @@ -22954,7 +23075,7 @@ function getgrgid(gid) @cindex @code{getgruser()} function (C library) The @code{getgruser()} function does not have a C counterpart. It takes a -user name and returns the list of groups that have the user as a member: +username and returns the list of groups that have the user as a member: @cindex @code{getgruser()} function, user-defined @example @@ -23097,7 +23218,7 @@ The functions presented here fit into the following categories: @c nested list @table @asis @item General problems -Number to string conversion, assertions, rounding, random number +Number-to-string conversion, assertions, rounding, random number generation, converting characters to numbers, joining strings, getting easily usable time-of-day information, and reading a whole file in one shot. @@ -23157,7 +23278,7 @@ ARGIND != Argind @{ @} END @{ if (ARGIND < ARGC - 1) - ARGIND = ARGC - 1 + ARGIND = ARGC - 1 if (ARGIND > Argind) for (Argind++; Argind <= ARGIND; Argind++) zerofile(ARGV[Argind], Argind) @@ -23293,7 +23414,7 @@ The programs are presented in alphabetical order. @end menu @node Cut Program -@subsection Cutting out Fields and Columns +@subsection Cutting Out Fields and Columns @cindex @command{cut} utility @c STARTOFRANGE cut @@ -23570,7 +23691,7 @@ function set_charlist( field, i, j, f, g, n, m, t, @c endfile @end example -Next is the rule that actually processes the data. If the @option{-s} option +Next is the rule that processes the data. If the @option{-s} option is given, then @code{suppress} is true. The first @code{if} statement makes sure that the input record does have the field separator. If @command{cut} is processing fields, @code{suppress} is true, and the field @@ -23602,9 +23723,9 @@ written out between the fields: @end example This version of @command{cut} relies on @command{gawk}'s @code{FIELDWIDTHS} -variable to do the character-based cutting. While it is possible in +variable to do the character-based cutting. It is possible in other @command{awk} implementations to use @code{substr()} -(@pxref{String Functions}), +(@pxref{String Functions}), but it is also extremely painful. The @code{FIELDWIDTHS} variable supplies an elegant solution to the problem of picking the input line apart by characters. @@ -23749,7 +23870,7 @@ matched lines in the output: @c endfile @end example -The last two lines are commented out, since they are not needed in +The last two lines are commented out, as they are not needed in @command{gawk}. They should be uncommented if you have to use another version of @command{awk}. @@ -23759,7 +23880,7 @@ into lowercase if the @option{-i} option is specified.@footnote{It also introduces a subtle bug; if a match happens, we output the translated line, not the original.} The rule is -commented out since it is not necessary with @command{gawk}: +commented out as it is not necessary with @command{gawk}: @example @c file eg/prog/egrep.awk @@ -23896,7 +24017,7 @@ function usage() @c ENDOFRANGE egrep @node Id Program -@subsection Printing out User Information +@subsection Printing Out User Information @cindex printing, user information @cindex users, information about, printing @@ -24011,7 +24132,7 @@ function pr_first_field(str, a) The test in the @code{for} loop is worth noting. Any supplementary groups in the @code{PROCINFO} array have the indices @code{"group1"} through @code{"group@var{N}"} for some -@var{N}, i.e., the total number of supplementary groups. +@var{N} (i.e., the total number of supplementary groups). However, we don't know in advance how many of these groups there are. @@ -24051,10 +24172,10 @@ aims to demonstrate.} By default, the output files are named @file{xaa}, @file{xab}, and so on. Each file has -1000 lines in it, with the likely exception of the last file. To change the +1,000 lines in it, with the likely exception of the last file. To change the number of lines in each file, supply a number on the command line -preceded with a minus; e.g., @samp{-500} for files with 500 lines in them -instead of 1000. To change the name of the output files to something like +preceded with a minus (e.g., @samp{-500} for files with 500 lines in them +instead of 1,000). To change the name of the output files to something like @file{myfileaa}, @file{myfileab}, and so on, supply an additional argument that specifies the @value{FN} prefix. @@ -24102,7 +24223,7 @@ BEGIN @{ @} # test argv in case reading from stdin instead of file if (i in ARGV) - i++ # skip data file name + i++ # skip datafile name if (i in ARGV) @{ outfile = ARGV[i] ARGV[i] = "" @@ -24196,8 +24317,8 @@ truncating them and starting over. The @code{BEGIN} rule first makes a copy of all the command-line arguments into an array named @code{copy}. -@code{ARGV[0]} is not copied, since it is not needed. -@code{tee} cannot use @code{ARGV} directly, since @command{awk} attempts to +@code{ARGV[0]} is not needed, so it is not copied. +@code{tee} cannot use @code{ARGV} directly, because @command{awk} attempts to process each @value{FN} in @code{ARGV} as input data. @cindex flag variables @@ -24246,7 +24367,7 @@ BEGIN @{ @c endfile @end example -The following single rule does all the work. Since there is no pattern, it is +The following single rule does all the work. Because there is no pattern, it is executed for each line of input. The body of the rule simply prints the line into each file on the command line, and then to the standard output: @@ -24277,7 +24398,7 @@ for (i in copy) @end example @noindent -This is more concise but it is also less efficient. The @samp{if} is +This is more concise, but it is also less efficient. The @samp{if} is tested for each record and for each output file. By duplicating the loop body, the @samp{if} is only tested once for each input record. If there are @var{N} input records and @var{M} output files, the first method only @@ -24497,10 +24618,10 @@ The second rule does the work. The variable @code{equal} is one or zero, depending upon the results of @code{are_equal()}'s comparison. If @command{uniq} is counting repeated lines, and the lines are equal, then it increments the @code{count} variable. Otherwise, it prints the line and resets @code{count}, -since the two lines are not equal. +because the two lines are not equal. If @command{uniq} is not counting, and if the lines are equal, @code{count} is incremented. -Nothing is printed, since the point is to remove duplicates. +Nothing is printed, as the point is to remove duplicates. Otherwise, if @command{uniq} is counting repeated lines and more than one line is seen, or if @command{uniq} is counting nonrepeated lines and only one line is seen, then the line is printed, and @code{count} @@ -24569,7 +24690,7 @@ Brian Kernighan suggests that ``an alternative approach to state machines is to just read the input into an array, then use indexing. It's almost always easier code, and for most inputs where you would use this, just -as fast.'' Consider how to rewrite the logic to follow this +as fast.'' Consider how to rewrite the logic to follow this suggestion. @end ifset @@ -24621,7 +24742,7 @@ Count only characters. @end table Implementing @command{wc} in @command{awk} is particularly elegant, -since @command{awk} does a lot of the work for us; it splits lines into +because @command{awk} does a lot of the work for us; it splits lines into words (i.e., fields) and counts them, it counts lines (i.e., records), and it can easily tell us how long a line is. @@ -24726,7 +24847,7 @@ function endfile(file) @end example There is one rule that is executed for each line. It adds the length of -the record, plus one, to @code{chars}.@footnote{Since @command{gawk} +the record, plus one, to @code{chars}.@footnote{Because @command{gawk} understands multibyte locales, this code counts characters, not bytes.} Adding one plus the record length is needed because the newline character separating records (the value @@ -25074,8 +25195,8 @@ often used to map uppercase letters into lowercase for further processing: @command{tr} requires two lists of characters.@footnote{On some older systems, including Solaris, the system version of @command{tr} may require that the lists be written as range expressions enclosed in square brackets -(@samp{[a-z]}) and quoted, to prevent the shell from attempting a file -name expansion. This is not a feature.} When processing the input, the +(@samp{[a-z]}) and quoted, to prevent the shell from attempting a +@value{FN} expansion. This is not a feature.} When processing the input, the first character in the first list is replaced with the first character in the second list, the second character in the first list is replaced with the second character in the second list, and so on. If there are @@ -25190,9 +25311,9 @@ BEGIN @{ @c endfile @end example -While it is possible to do character transliteration in a user-level -function, it is not necessarily efficient, and we (the @command{gawk} -authors) started to consider adding a built-in function. However, +It is possible to do character transliteration in a user-level +function, but it is not necessarily efficient, and we (the @command{gawk} +developers) started to consider adding a built-in function. However, shortly after writing this program, we learned that Brian Kernighan had added the @code{toupper()} and @code{tolower()} functions to his @command{awk} (@pxref{String Functions}). These functions handle the @@ -25236,7 +25357,7 @@ the @code{line} array and printing the page when 20 labels have been read. The @code{BEGIN} rule simply sets @code{RS} to the empty string, so that @command{awk} splits records at blank lines (@pxref{Records}). -It sets @code{MAXLINES} to 100, since 100 is the maximum number +It sets @code{MAXLINES} to 100, because 100 is the maximum number of lines on the page @iftex (@math{20 @cdot 5 = 100}). @@ -25393,9 +25514,9 @@ useful on real text files: @item The @command{awk} language considers upper- and lowercase characters to be distinct. Therefore, ``bartender'' and ``Bartender'' are not treated -as the same word. This is undesirable, since in normal text, words -are capitalized if they begin sentences, and a frequency analyzer should not -be sensitive to capitalization. +as the same word. This is undesirable, because words are capitalized +if they begin sentences in normal text, and a frequency analyzer should +not be sensitive to capitalization. @item Words are detected using the @command{awk} convention that fields are @@ -25437,8 +25558,8 @@ END @{ @} @end example -The regexp @samp{/[^[:alnum:]_[:blank:]]/} might have been written -@samp{/[[:punct:]]/}, but then underscores would also be removed, +The regexp @code{/[^[:alnum:]_[:blank:]]/} might have been written +@code{/[[:punct:]]/}, but then underscores would also be removed, and we want to keep them. Assuming we have saved this program in a file named @file{wordfreq.awk}, @@ -25576,7 +25697,7 @@ The nodes and @ref{Sample Programs}, are the top level nodes for a large number of @command{awk} programs. @end ifinfo -If you want to experiment with these programs, it is tedious to have to type +If you want to experiment with these programs, it is tedious to type them in by hand. Here we present a program that can extract parts of a Texinfo input file into separate files. @@ -25654,7 +25775,7 @@ It also prints some final advice: @@example @@c file examples/messages.awk -END @@@{ print "Always avoid bored archeologists!" @@@} +END @@@{ print "Always avoid bored archaeologists!" @@@} @@c end file @@end example @dots{} @@ -25826,7 +25947,7 @@ The @command{sed} utility is a stream editor, a program that reads a stream of data, makes changes to it, and passes it on. It is often used to make global changes to a large file or to a stream of data generated by a pipeline of commands. -While @command{sed} is a complicated program in its own right, its most common +Although @command{sed} is a complicated program in its own right, its most common use is to perform global substitutions in the middle of a pipeline: @example @@ -25835,7 +25956,7 @@ use is to perform global substitutions in the middle of a pipeline: Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp @samp{old} on each input line and globally replace it with the text -@samp{new}, i.e., all the occurrences on a line. This is similar to +@samp{new} (i.e., all the occurrences on a line). This is similar to @command{awk}'s @code{gsub()} function (@pxref{String Functions}). @@ -25919,7 +26040,7 @@ not treated as @value{FN}s (@pxref{ARGC and ARGV}). The @code{usage()} function prints an error message and exits. -Finally, the single rule handles the printing scheme outlined above, +Finally, the single rule handles the printing scheme outlined earlier, using @code{print} or @code{printf} as appropriate, depending upon the value of @code{RT}. @c ENDOFRANGE awksed @@ -25963,8 +26084,8 @@ BEGIN @{ The following program, @file{igawk.sh}, provides this service. It simulates @command{gawk}'s searching of the @env{AWKPATH} variable -and also allows @dfn{nested} includes; i.e., a file that is included -with @code{@@include} can contain further @code{@@include} statements. +and also allows @dfn{nested} includes (i.e., a file that is included +with @code{@@include} can contain further @code{@@include} statements). @command{igawk} makes an effort to only include files once, so that nested includes don't accidentally include a library function twice. @@ -25994,10 +26115,10 @@ Literal text, provided with @option{-e} or @option{--source}. This text is just appended directly. @item -Source @value{FN}s, provided with @option{-f}. We use a neat trick and append -@samp{@@include @var{filename}} to the shell variable's contents. Since the file-inclusion -program works the way @command{gawk} does, this gets the text -of the file included into the program at the correct point. +Source @value{FN}s, provided with @option{-f}. We use a neat trick and +append @samp{@@include @var{filename}} to the shell variable's contents. +Because the file-inclusion program works the way @command{gawk} does, this +gets the text of the file included in the program at the correct point. @end enumerate @item @@ -26296,9 +26417,10 @@ EOF @c endfile @end example -The shell construct @samp{@var{command} << @var{marker}} is called a @dfn{here document}. -Everything in the shell script up to the @var{marker} is fed to @var{command} as input. -The shell processes the contents of the here document for variable and command substitution +The shell construct @samp{@var{command} << @var{marker}} is called +a @dfn{here document}. Everything in the shell script up to the +@var{marker} is fed to @var{command} as input. The shell processes +the contents of the here document for variable and command substitution (and possibly other things as well, depending upon the shell). The shell construct @samp{$(@dots{})} is called @dfn{command substitution}. @@ -26313,14 +26435,16 @@ It's done in these steps: @enumerate @item Run @command{gawk} with the @code{@@include}-processing program (the -value of the @code{expand_prog} shell variable) on standard input. +value of the @code{expand_prog} shell variable) reading standard input. @item -Standard input is the contents of the user's program, from the shell variable @code{program}. -Its contents are fed to @command{gawk} via a here document. +Standard input is the contents of the user's program, +from the shell variable @code{program}. +Feed its contents to @command{gawk} via a here document. @item -The results of this processing are saved in the shell variable @code{processed_program} by using command substitution. +Save the results of this processing in the shell variable +@code{processed_program} by using command substitution. @end enumerate The last step is to call @command{gawk} with the expanded program, @@ -26396,7 +26520,7 @@ of @command{awk} programs as Web CGI scripts.} @c ENDOFRANGE igawk @node Anagram Program -@subsection Finding Anagrams From A Dictionary +@subsection Finding Anagrams from a Dictionary @cindex anagrams, finding An interesting programming challenge is to @@ -26405,17 +26529,17 @@ word list (such as @file{/usr/share/dict/words} on many GNU/Linux systems). One word is an anagram of another if both words contain the same letters -(for example, ``babbling'' and ``blabbing''). +(e.g., ``babbling'' and ``blabbing''). -Column 2, Problem C of Jon Bentley's @cite{Programming Pearls}, second -edition, presents an elegant algorithm. The idea is to give words that +Column 2, Problem C, of Jon Bentley's @cite{Programming Pearls}, Second +Edition, presents an elegant algorithm. The idea is to give words that are anagrams a common signature, sort all the words together by their signature, and then print them. Dr.@: Bentley observes that taking the letters in each word and sorting them produces that common signature. The following program uses arrays of arrays to bring together words with the same signature and array sorting to print the words -in sorted order. +in sorted order: @c STARTOFRANGE anagram @cindex @code{anagram.awk} program @@ -26487,7 +26611,7 @@ function word2key(word, a, i, n, result) Finally, the @code{END} rule traverses the array and prints out the anagram lists. It sends the output -to the system @command{sort} command, since otherwise +to the system @command{sort} command because otherwise the anagrams would appear in arbitrary order: @example @@ -26515,21 +26639,21 @@ Here is some partial output when the program is run: @example $ @kbd{gawk -f anagram.awk /usr/share/dict/words | grep '^b'} @dots{} -babbled blabbed -babbler blabber brabble -babblers blabbers brabbles -babbling blabbing -babbly blabby -babel bable -babels beslab -babery yabber +babbled blabbed +babbler blabber brabble +babblers blabbers brabbles +babbling blabbing +babbly blabby +babel bable +babels beslab +babery yabber @dots{} @end example @c ENDOFRANGE anagram @node Signature Program -@subsection And Now For Something Completely Different +@subsection And Now for Something Completely Different @cindex signature program @cindex Brini, Davide @@ -26569,28 +26693,28 @@ Subject: The GNU Awk User's Guide, Section 13.3.11 From: "Chris Johansen" <johansen@main.nc.us> Message-ID: <op.v0iw6wlv7finx3@asusodin.thrudvang.lan> -Arnold, you don't know me, but we have a tenuous connection. My wife is +Arnold, you don't know me, but we have a tenuous connection. My wife is Barbara A. Field, FAIA, GIT '65 (B. Arch.). -I have had a couple of paper copies of "Effective Awk Programming" for -years, and now I'm going through a Kindle version of "The GNU Awk User's -Guide" again. When I got to section 13.3.11, I reformatted and lightly +I have had a couple of paper copies of "Effective Awk Programming" for +years, and now I'm going through a Kindle version of "The GNU Awk User's +Guide" again. When I got to section 13.3.11, I reformatted and lightly commented Davide Brin's signature script to understand its workings. -It occurs to me that this might have pedagogical value as an example -(although imperfect) of the value of whitespace and comments, and a -starting point for that discussion. It certainly helped _me_ understand -what's going on. You are welcome to it, as-is or modified (subject to +It occurs to me that this might have pedagogical value as an example +(although imperfect) of the value of whitespace and comments, and a +starting point for that discussion. It certainly helped _me_ understand +what's going on. You are welcome to it, as-is or modified (subject to Davide's constraints, of course, which I think I have met). -If I were to include it in a future edition, I would put it at some -distance from section 13.3.11, say, as a note or an appendix, so as not to +If I were to include it in a future edition, I would put it at some +distance from section 13.3.11, say, as a note or an appendix, so as not to be a "spoiler" to the puzzle. Best regards, --- +-- Chris Johansen {johansen at main dot nc dot us} - . . . collapsing the probability wave function, sending ripples of + . . . collapsing the probability wave function, sending ripples of certainty through the space-time continuum. @@ -26599,7 +26723,7 @@ certainty through the space-time continuum. # From "13.3.11 And Now For Something Completely Different" # http://www.gnu.org/software/gawk/manual/html_node/Signature-Program.html#Signature-Program -# Copyright © 2008 Davide Brini +# Copyright © 2008 Davide Brini # Copying and distribution of the code published in this page, with # or without modification, are permitted in any medium without @@ -26718,7 +26842,7 @@ Brian Kernighan suggests that ``an alternative approach to state machines is to just read the input into an array, then use indexing. It's almost always easier code, and for most inputs where you would use this, just -as fast.'' Rewrite the logic to follow this +as fast.'' Rewrite the logic to follow this suggestion. @@ -26819,7 +26943,7 @@ the use of the external @command{sort} utility. @c EXCLUDE END @ifnotinfo -@part @value{PART3}Moving Beyond Standard @command{awk} With @command{gawk} +@part @value{PART3}Moving Beyond Standard @command{awk} with @command{gawk} @end ifnotinfo @ifdocbook @@ -26828,19 +26952,19 @@ It contains the following chapters: @itemize @value{BULLET} @item -@ref{Advanced Features}. +@ref{Advanced Features} @item -@ref{Internationalization}. +@ref{Internationalization} @item -@ref{Debugger}. +@ref{Debugger} @item -@ref{Arbitrary Precision Arithmetic}. +@ref{Arbitrary Precision Arithmetic} @item -@ref{Dynamic Extensions}. +@ref{Dynamic Extensions} @end itemize @end ifdocbook @@ -26999,7 +27123,7 @@ in a particular order that you, the programmer, choose. @command{gawk} lets you do this. @DBREF{Controlling Scanning} describes how you can assign special, -pre-defined values to @code{PROCINFO["sorted_in"]} in order to +predefined values to @code{PROCINFO["sorted_in"]} in order to control the order in which @command{gawk} traverses an array during a @code{for} loop. @@ -27023,7 +27147,7 @@ Here, @var{i1} and @var{i2} are the indices, and @var{v1} and @var{v2} are the corresponding values of the two elements being compared. Either @var{v1} or @var{v2}, or both, can be arrays if the array being traversed contains subarrays as values. -(@xref{Arrays of Arrays}, for more information about subarrays.) +(@DBXREF{Arrays of Arrays} for more information about subarrays.) The three possible return values are interpreted as follows: @table @code @@ -27066,7 +27190,7 @@ function cmp_str_val(i1, v1, i2, v2) The third comparison function makes all numbers, and numeric strings without -any leading or trailing spaces, come out first during loop traversal: +any leading or trailing spaces, come out first during loop traversal: @example function cmp_num_str_val(i1, v1, i2, v2, n1, n2) @@ -27074,10 +27198,10 @@ function cmp_num_str_val(i1, v1, i2, v2, n1, n2) # numbers before string value comparison, ascending order n1 = v1 + 0 n2 = v2 + 0 - if (n1 == v1) + if (n1 == v1) return (n2 == v2) ? (n1 - n2) : -1 else if (n2 == v2) - return 1 + return 1 return (v1 < v2) ? -1 : (v1 != v2) @} @end example @@ -27092,7 +27216,7 @@ BEGIN @{ data[10] = "one" data[100] = 100 data[20] = "two" - + f[1] = "cmp_num_idx" f[2] = "cmp_str_val" f[3] = "cmp_num_str_val" @@ -27116,14 +27240,14 @@ $ @kbd{gawk -f compdemo.awk} @print{} data[10] = one @print{} data[20] = two @print{} data[100] = 100 -@print{} +@print{} @print{} Sort function: cmp_str_val @ii{Sort by element values as strings} @print{} data[one] = 10 @print{} data[100] = 100 @ii{String 100 is less than string 20} @print{} data[two] = 20 @print{} data[10] = one @print{} data[20] = two -@print{} +@print{} @print{} Sort function: cmp_num_str_val @ii{Sort all numeric values before all strings} @print{} data[one] = 10 @print{} data[two] = 20 @@ -27134,7 +27258,7 @@ $ @kbd{gawk -f compdemo.awk} Consider sorting the entries of a GNU/Linux system password file according to login name. The following program sorts records -by a specific field position and can be used for this purpose: +by a specific field position and can be used for this purpose: @example # passwd-sort.awk --- simple program to sort by field position @@ -27180,7 +27304,7 @@ $ @kbd{gawk -v POS=1 -F: -f sort.awk /etc/passwd} The comparison should normally always return the same value when given a specific pair of array elements as its arguments. If inconsistent -results are returned then the order is undefined. This behavior can be +results are returned, then the order is undefined. This behavior can be exploited to introduce random order into otherwise seemingly ordered data: @@ -27192,7 +27316,7 @@ function cmp_randomize(i1, v1, i2, v2) @} @end example -As mentioned above, the order of the indices is arbitrary if two +As already mentioned, the order of the indices is arbitrary if two elements compare equal. This is usually not a problem, but letting the tied elements come out in arbitrary order can be an issue, especially when comparing item values. The partial ordering of the equal elements @@ -27233,10 +27357,10 @@ When string comparisons are made during a sort, either for element values where one or both aren't numbers, or for element indices handled as strings, the value of @code{IGNORECASE} (@pxref{Built-in Variables}) controls whether -the comparisons treat corresponding uppercase and lowercase letters as +the comparisons treat corresponding upper- and lowercase letters as equivalent or distinct. -Another point to keep in mind is that in the case of subarrays +Another point to keep in mind is that in the case of subarrays, the element values can themselves be arrays; a production comparison function should use the @code{isarray()} function (@pxref{Type Functions}), @@ -27244,7 +27368,7 @@ to check for this, and choose a defined sorting order for subarrays. All sorting based on @code{PROCINFO["sorted_in"]} is disabled in POSIX mode, -since the @code{PROCINFO} array is not special in that case. +because the @code{PROCINFO} array is not special in that case. As a side note, sorting the array indices before traversing the array has been reported to add 15% to 20% overhead to the @@ -27265,8 +27389,8 @@ sorted array traversal is not the default. @cindex @code{asorti()} function (@command{gawk}), arrays@comma{} sorting @cindex sort function, arrays, sorting In most @command{awk} implementations, sorting an array requires writing -a @code{sort()} function. While this can be educational for exploring -different sorting algorithms, usually that's not the point of the program. +a @code{sort()} function. This can be educational for exploring +different sorting algorithms, but usually that's not the point of the program. @command{gawk} provides the built-in @code{asort()} and @code{asorti()} functions (@pxref{String Functions}) for sorting arrays. For example: @@ -27362,8 +27486,8 @@ Because @code{IGNORECASE} affects string comparisons, the value of @code{IGNORECASE} also affects sorting for both @code{asort()} and @code{asorti()}. Note also that the locale's sorting order does @emph{not} come into play; comparisons are based on character values only.@footnote{This -is true because locale-based comparison occurs only when in POSIX -compatibility mode, and since @code{asort()} and @code{asorti()} are +is true because locale-based comparison occurs only when in +POSIX-compatibility mode, and because @code{asort()} and @code{asorti()} are @command{gawk} extensions, they are not available in that case.} @node Two-way I/O @@ -27439,7 +27563,7 @@ remain more difficult to use than two-way pipes.} @c 8/2014 @cindex @command{csh} utility, @code{|&} operator, comparison with However, with @command{gawk}, it is possible to open a @emph{two-way} pipe to another process. The second process is -termed a @dfn{coprocess}, since it runs in parallel with @command{gawk}. +termed a @dfn{coprocess}, as it runs in parallel with @command{gawk}. The two-way connection is created using the @samp{|&} operator (borrowed from the Korn shell, @command{ksh}):@footnote{This is very different from the same operator in the C shell and in Bash.} @@ -27544,7 +27668,7 @@ like so: @example command = "sort -nr" # command, save in convenience variable PROCINFO[command, "pty"] = 1 # update PROCINFO -print @dots{} |& command # start two-way pipe +print @dots{} |& command # start two-way pipe @dots{} @end example @@ -27599,7 +27723,7 @@ You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is by recognizing special @value{FN}s that begin with one of @samp{/inet/}, -@samp{/inet4/} or @samp{/inet6/}. +@samp{/inet4/}, or @samp{/inet6/}. The full syntax of the special @value{FN} is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. @@ -27628,7 +27752,7 @@ or @samp{http}, in which case @command{gawk} attempts to determine the predefined port number using the C @code{getaddrinfo()} function. @item remote-host -The IP address or fully-qualified domain name of the Internet +The IP address or fully qualified domain name of the Internet host to which you want to connect. @item remote-port @@ -27702,12 +27826,12 @@ gawk --profile=myprog.prof -f myprog.awk data1 data2 @end example @noindent -In the above example, @command{gawk} places the profile in +In the preceding example, @command{gawk} places the profile in @file{myprog.prof} instead of in @file{awkprof.out}. -Here is a sample session showing a simple @command{awk} program, its input data, and the -results from running @command{gawk} with the @option{--profile} option. -First, the @command{awk} program: +Here is a sample session showing a simple @command{awk} program, +its input data, and the results from running @command{gawk} with the +@option{--profile} option. First, the @command{awk} program: @example BEGIN @{ print "First BEGIN rule" @} @@ -27865,7 +27989,7 @@ the body of an @code{if}, @code{else}, or loop is only a single statement. @item Parentheses are used only where needed, as indicated by the structure of the program and the precedence rules. -For example, @samp{(3 + 5) * 4} means add three plus five, then multiply +For example, @samp{(3 + 5) * 4} means add three and five, then multiply the total by four. However, @samp{3 + 5 * 4} has no parentheses, and means @samp{3 + (5 * 4)}. @@ -28140,8 +28264,7 @@ following steps, in this order: @enumerate @item -The programmer goes -through the source for all of @command{guide}'s components +The programmer reviews the source for all of @command{guide}'s components and marks each string that is a candidate for translation. For example, @code{"`-F': option required"} is a good candidate for translation. A table with strings of option names is not (e.g., @command{gawk}'s @@ -28261,8 +28384,8 @@ if necessary. (It is almost never necessary to supply a different category.) @cindex sorting characters in different languages @cindex @code{LC_COLLATE} locale category @item LC_COLLATE -Text-collation information; i.e., how different characters -and/or groups of characters sort in a given language. +Text-collation information (i.e., how different characters +and/or groups of characters sort in a given language). @cindex @code{LC_CTYPE} locale category @item LC_CTYPE @@ -28481,7 +28604,7 @@ BEGIN @{ @end enumerate -@xref{I18N Example}, +@DBXREF{I18N Example} for an example program showing the steps to create and use translations from @command{awk}. @@ -28542,7 +28665,7 @@ second argument to @code{dcngettext()}.@footnote{The You should distribute the generated @file{.pot} file with your @command{awk} program; translators will eventually use it to provide you translations that you can also then distribute. -@xref{I18N Example}, +@DBXREF{I18N Example} for the full list of steps to go through to create and test translations for @command{guide}. @c ENDOFRANGE portobfi @@ -28670,7 +28793,7 @@ change: @cindex @code{TEXTDOMAIN} variable, portability and @item Assignments to @code{TEXTDOMAIN} won't have any effect, -since @code{TEXTDOMAIN} is not special in other @command{awk} implementations. +because @code{TEXTDOMAIN} is not special in other @command{awk} implementations. @item Non-GNU versions of @command{awk} treat marked strings @@ -28718,8 +28841,8 @@ enough arguments are supplied in the function call. Many versions of underlying C library version of @code{sprintf()}, but only one format and argument at a time. What happens if a positional specification is used is anybody's guess. -However, since the positional specifications are primarily for use in -@emph{translated} format strings, and since non-GNU @command{awk}s never +However, because the positional specifications are primarily for use in +@emph{translated} format strings, and because non-GNU @command{awk}s never retrieve the translated string, this should not be a problem in practice. @end itemize @c ENDOFRANGE inap @@ -28782,7 +28905,7 @@ called ``Hippy.'' Ah, well.} @example @group -$ cp guide.pot guide-mellow.po +$ @kbd{cp guide.pot guide-mellow.po} @var{Add translations to} guide-mellow.po @dots{} @end group @end example @@ -28808,7 +28931,7 @@ msgstr "Like, the scoop is" The next step is to make the directory to hold the binary message object file and then to create the @file{guide.mo} file. We pretend that our file is to be used in the @code{en_US.UTF-8} locale, -since we have to use a locale name known to the C @command{gettext} routines. +because we have to use a locale name known to the C @command{gettext} routines. The directory layout shown here is standard for GNU @command{gettext} on GNU/Linux systems. Other versions of @command{gettext} may use a different layout: @@ -28845,7 +28968,7 @@ $ @kbd{gawk -f guide.awk} @print{} Pardon me, Zaphod who? @end example -If the three replacement functions for @code{dcgettext()}, @code{dcngettext()} +If the three replacement functions for @code{dcgettext()}, @code{dcngettext()}, and @code{bindtextdomain()} (@pxref{I18N Portability}) are in a file named @file{libintl.awk}, @@ -28947,7 +29070,7 @@ how to use @command{gawk} for debugging your program is easy. @end menu @node Debugging -@section Introduction to The @command{gawk} Debugger +@section Introduction to the @command{gawk} Debugger This @value{SECTION} introduces debugging in general and begins the discussion of debugging in @command{gawk}. @@ -28965,8 +29088,8 @@ the discussion of debugging in @command{gawk}. ahead to the next section on the specific features of the @command{gawk} debugger.) -Of course, a debugging program cannot remove bugs for you, since it has -no way of knowing what you or your users consider a ``bug'' and what is a +Of course, a debugging program cannot remove bugs for you, because it has +no way of knowing what you or your users consider a ``bug'' versus a ``feature.'' (Sometimes, we humans have a hard time with this ourselves.) In that case, what can you expect from such a tool? The answer to that depends on the language being debugged, but in general, you can expect at @@ -28987,7 +29110,7 @@ having to change your source files. @item The chance to see the values of data in the program at any point in execution, and also to change that data on the fly, to see how that -affects what happens afterwards. (This often includes the ability +affects what happens afterward. (This often includes the ability to look at internal data structures besides the variables you actually defined in your code.) @@ -29007,11 +29130,11 @@ functional program that you or someone else wrote). Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. The following list defines terms used throughout the rest of -this @value{CHAPTER}. +this @value{CHAPTER}: @table @dfn @cindex stack frame -@item Stack Frame +@item Stack frame Programs generally call functions during the course of their execution. One function can call another, or a function can call itself (recursion). You can view the chain of called functions (main program calls A, which @@ -29046,7 +29169,7 @@ as many breakpoints as you like. A watchpoint is similar to a breakpoint. The difference is that breakpoints are oriented around the code: stop when a certain point in the code is reached. A watchpoint, however, specifies that program execution -should stop when a @emph{data value} is changed. This is useful, since +should stop when a @emph{data value} is changed. This is useful, as sometimes it happens that a variable receives an erroneous value, and it's hard to track down where this happens just by looking at the code. By using a watchpoint, you can stop whenever a variable is assigned to, @@ -29060,13 +29183,13 @@ Debugging an @command{awk} program has some specific aspects that are not shared with other programming languages. First of all, the fact that @command{awk} programs usually take input -line-by-line from a file or files and operate on those lines using specific +line by line from a file or files and operate on those lines using specific rules makes it especially useful to organize viewing the execution of the program in terms of these rules. As we will see, each @command{awk} rule is treated almost like a function call, with its own specific block of instructions. -In addition, since @command{awk} is by design a very concise language, +In addition, because @command{awk} is by design a very concise language, it is easy to lose sight of everything that is going on ``inside'' each line of @command{awk} code. The debugger provides the opportunity to look at the individual primitive instructions carried out @@ -29193,7 +29316,7 @@ gawk> @kbd{bt} @end example This tells us that @code{are_equal()} was called by the main program at -line 88 of @file{uniq.awk}. (This is not a big surprise, since this +line 88 of @file{uniq.awk}. (This is not a big surprise, because this is the only call to @code{are_equal()} in the program, but in more complex programs, knowing who called a function and with what parameters can be the key to finding the source of the problem.) @@ -29210,7 +29333,7 @@ gawk> @kbd{p n} @end example @noindent -In this case, @code{n} is an uninitialized local variable, since the +In this case, @code{n} is an uninitialized local variable, because the function was called without arguments (@pxref{Function Calls}). A more useful variable to display might be the current record: @@ -29221,8 +29344,8 @@ gawk> @kbd{p $0} @end example @noindent -This might be a bit puzzling at first since this is the second line of -our test input above. Let's look at @code{NR}: +This might be a bit puzzling at first, as this is the second line of +our test input. Let's look at @code{NR}: @example gawk> @kbd{p NR} @@ -29262,7 +29385,7 @@ gawk> @kbd{n} This tells us that @command{gawk} is now ready to execute line 66, which decides whether to give the lines the special ``field skipping'' treatment indicated by the @option{-1} command-line option. (Notice that we skipped -from where we were before at line 63 to here, since the condition in line 63 +from where we were before at line 63 to here, because the condition in line 63 @samp{if (fcount == 0 && charcount == 0)} was false.) Continuing to step, we now get to the splitting of the current and @@ -29292,7 +29415,7 @@ gawk> @kbd{p n m alast aline} This is kind of disappointing, though. All we found out is that there are five elements in @code{alast}; @code{m} and @code{aline} don't have -values since we are at line 68 but haven't executed it yet. +values because we are at line 68 but haven't executed it yet. This information is useful enough (we now know that none of the words were accidentally left out), but what if we want to see inside the array? @@ -29401,8 +29524,9 @@ show the abbreviation on a second description line. A debugger command name may also be truncated if that partial name is unambiguous. The debugger has the built-in capability to automatically repeat the previous command just by hitting @key{Enter}. -This works for the commands @code{list}, @code{next}, @code{nexti}, @code{step}, @code{stepi} -and @code{continue} executed without any argument. +This works for the commands @code{list}, @code{next}, @code{nexti}, +@code{step}, @code{stepi}, and @code{continue} executed without any +argument. @menu * Breakpoint Control:: Control of Breakpoints. @@ -29417,9 +29541,9 @@ and @code{continue} executed without any argument. @node Breakpoint Control @subsection Control of Breakpoints -As we saw above, the first thing you probably want to do in a debugging -session is to get your breakpoints set up, since otherwise your program -will just run as if it was not under the debugger. The commands for +As we saw earlier, the first thing you probably want to do in a debugging +session is to get your breakpoints set up, because your program +will otherwise just run as if it was not under the debugger. The commands for controlling breakpoints are: @table @asis @@ -29490,8 +29614,8 @@ that the debugger evaluates whenever the breakpoint or watchpoint is reached. If the condition is true, then the debugger stops execution and prompts for a command. Otherwise, the debugger continues executing the program. If the condition expression is -not specified, any existing condition is removed; i.e., the breakpoint or -watchpoint is made unconditional. +not specified, any existing condition is removed (i.e., the breakpoint or +watchpoint is made unconditional). @cindex debugger commands, @code{d} (@code{delete}) @cindex debugger commands, @code{delete} @@ -29632,7 +29756,7 @@ Execute one (or @var{count}) instruction(s), stepping over function calls. @item @code{return} [@var{value}] Cancel execution of a function call. If @var{value} (either a string or a number) is specified, it is used as the function's return value. If used in a -frame other than the innermost one (the currently executing function, i.e., +frame other than the innermost one (the currently executing function; i.e., frame number 0), discard all inner frames in addition to the selected one, and the caller of that frame becomes the innermost frame. @@ -29698,7 +29822,7 @@ gawk> @kbd{display x} @end example @noindent -displays the assigned item number, the variable name and its current value. +This displays the assigned item number, the variable name, and its current value. If the display variable refers to a function parameter, it is silently deleted from the list as soon as the execution reaches a context where no such variable of the given name exists. @@ -29766,7 +29890,7 @@ or field. String values must be enclosed between double quotes (@code{"}@dots{}@code{"}). You can also set special @command{awk} variables, such as @code{FS}, -@code{NF}, @code{NR}, etc. +@code{NF}, @code{NR}, and son on. @cindex debugger commands, @code{w} (@code{watch}) @cindex debugger commands, @code{watch} @@ -29829,7 +29953,7 @@ Print a backtrace of all function calls (stack frames), or innermost @var{count} frames if @var{count} > 0. Print the outermost @var{count} frames if @var{count} < 0. The backtrace displays the name and arguments to each function, the source @value{FN}, and the line number. -The alias @code{where} for @code{backtrace} is provided for long-time +The alias @code{where} for @code{backtrace} is provided for longtime GDB users who may be used to that command. @cindex debugger commands, @code{down} @@ -29858,7 +29982,7 @@ Then select and print the frame. @end table @node Debugger Info -@subsection Obtaining Information about the Program and the Debugger State +@subsection Obtaining Information About the Program and the Debugger State Besides looking at the values of variables, there is often a need to get other sorts of information about the state of your program and of the @@ -30026,51 +30150,51 @@ partial dump of Davide Brini's obfuscated code @smallexample gawk> @kbd{dump} @print{} # BEGIN -@print{} -@print{} [ 1:0xfcd340] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] -@print{} [ 1:0xfcc240] Op_push_i : "~" [MALLOC|STRING|STRCUR] -@print{} [ 1:0xfcc2a0] Op_push_i : "~" [MALLOC|STRING|STRCUR] -@print{} [ 1:0xfcc280] Op_match : -@print{} [ 1:0xfcc1e0] Op_store_var : O -@print{} [ 1:0xfcc2e0] Op_push_i : "==" [MALLOC|STRING|STRCUR] -@print{} [ 1:0xfcc340] Op_push_i : "==" [MALLOC|STRING|STRCUR] -@print{} [ 1:0xfcc320] Op_equal : -@print{} [ 1:0xfcc200] Op_store_var : o -@print{} [ 1:0xfcc380] Op_push : o -@print{} [ 1:0xfcc360] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER] -@print{} [ 1:0xfcc220] Op_push_lhs : o [do_reference = true] -@print{} [ 1:0xfcc300] Op_assign_plus : -@print{} [ :0xfcc2c0] Op_pop : -@print{} [ 1:0xfcc400] Op_push : O -@print{} [ 1:0xfcc420] Op_push_i : "" [MALLOC|STRING|STRCUR] -@print{} [ :0xfcc4a0] Op_no_op : -@print{} [ 1:0xfcc480] Op_push : O -@print{} [ :0xfcc4c0] Op_concat : [expr_count = 3] [concat_flag = 0] -@print{} [ 1:0xfcc3c0] Op_store_var : x -@print{} [ 1:0xfcc440] Op_push_lhs : X [do_reference = true] -@print{} [ 1:0xfcc3a0] Op_postincrement : -@print{} [ 1:0xfcc4e0] Op_push : x -@print{} [ 1:0xfcc540] Op_push : o -@print{} [ 1:0xfcc500] Op_plus : -@print{} [ 1:0xfcc580] Op_push : o -@print{} [ 1:0xfcc560] Op_plus : -@print{} [ 1:0xfcc460] Op_leq : -@print{} [ :0xfcc5c0] Op_jmp_false : [target_jmp = 0xfcc5e0] -@print{} [ 1:0xfcc600] Op_push_i : "%c" [MALLOC|STRING|STRCUR] -@print{} [ :0xfcc660] Op_no_op : -@print{} [ 1:0xfcc520] Op_assign_concat : c -@print{} [ :0xfcc620] Op_jmp : [target_jmp = 0xfcc440] -@print{} -@dots{} -@print{} +@print{} +@print{} [ 1:0xfcd340] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] +@print{} [ 1:0xfcc240] Op_push_i : "~" [MALLOC|STRING|STRCUR] +@print{} [ 1:0xfcc2a0] Op_push_i : "~" [MALLOC|STRING|STRCUR] +@print{} [ 1:0xfcc280] Op_match : +@print{} [ 1:0xfcc1e0] Op_store_var : O +@print{} [ 1:0xfcc2e0] Op_push_i : "==" [MALLOC|STRING|STRCUR] +@print{} [ 1:0xfcc340] Op_push_i : "==" [MALLOC|STRING|STRCUR] +@print{} [ 1:0xfcc320] Op_equal : +@print{} [ 1:0xfcc200] Op_store_var : o +@print{} [ 1:0xfcc380] Op_push : o +@print{} [ 1:0xfcc360] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER] +@print{} [ 1:0xfcc220] Op_push_lhs : o [do_reference = true] +@print{} [ 1:0xfcc300] Op_assign_plus : +@print{} [ :0xfcc2c0] Op_pop : +@print{} [ 1:0xfcc400] Op_push : O +@print{} [ 1:0xfcc420] Op_push_i : "" [MALLOC|STRING|STRCUR] +@print{} [ :0xfcc4a0] Op_no_op : +@print{} [ 1:0xfcc480] Op_push : O +@print{} [ :0xfcc4c0] Op_concat : [expr_count = 3] [concat_flag = 0] +@print{} [ 1:0xfcc3c0] Op_store_var : x +@print{} [ 1:0xfcc440] Op_push_lhs : X [do_reference = true] +@print{} [ 1:0xfcc3a0] Op_postincrement : +@print{} [ 1:0xfcc4e0] Op_push : x +@print{} [ 1:0xfcc540] Op_push : o +@print{} [ 1:0xfcc500] Op_plus : +@print{} [ 1:0xfcc580] Op_push : o +@print{} [ 1:0xfcc560] Op_plus : +@print{} [ 1:0xfcc460] Op_leq : +@print{} [ :0xfcc5c0] Op_jmp_false : [target_jmp = 0xfcc5e0] +@print{} [ 1:0xfcc600] Op_push_i : "%c" [MALLOC|STRING|STRCUR] +@print{} [ :0xfcc660] Op_no_op : +@print{} [ 1:0xfcc520] Op_assign_concat : c +@print{} [ :0xfcc620] Op_jmp : [target_jmp = 0xfcc440] +@print{} +@dots{} +@print{} @print{} [ 2:0xfcc5a0] Op_K_printf : [expr_count = 17] [redir_type = ""] -@print{} [ :0xfcc140] Op_no_op : -@print{} [ :0xfcc1c0] Op_atexit : -@print{} [ :0xfcc640] Op_stop : -@print{} [ :0xfcc180] Op_no_op : -@print{} [ :0xfcd150] Op_after_beginfile : -@print{} [ :0xfcc160] Op_no_op : -@print{} [ :0xfcc1a0] Op_after_endfile : +@print{} [ :0xfcc140] Op_no_op : +@print{} [ :0xfcc1c0] Op_atexit : +@print{} [ :0xfcc640] Op_stop : +@print{} [ :0xfcc180] Op_no_op : +@print{} [ :0xfcd150] Op_after_beginfile : +@print{} [ :0xfcc160] Op_no_op : +@print{} [ :0xfcc1a0] Op_after_endfile : gawk> @end smallexample @@ -30127,7 +30251,7 @@ function @var{function}. This command may change the current source file. @itemx @code{q} Exit the debugger. Debugging is great fun, but sometimes we all have to tend to other obligations in life, and sometimes we find the bug, -and are free to go on to the next one! As we saw above, if you are +and are free to go on to the next one! As we saw earlier, if you are running a program, the debugger warns you if you accidentally type @samp{q} or @samp{quit}, to make sure you really want to quit. @@ -30204,7 +30328,7 @@ If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands} (or if you are already familiar with @command{gawk} internals), you will realize that much of the internal manipulation of data in @command{gawk}, as in many interpreters, is done on a stack. -@code{Op_push}, @code{Op_pop}, etc., are the ``bread and butter'' of +@code{Op_push}, @code{Op_pop}, and the like, are the ``bread and butter'' of most @command{gawk} code. Unfortunately, as of now, the @command{gawk} @@ -30218,8 +30342,8 @@ change back to obscure, perhaps more optimal code later. @item There is no way to look ``inside'' the process of compiling regular expressions to see if you got it right. As an @command{awk} -programmer, you are expected to know what @code{/[^[:alnum:][:blank:]]/} -means. +programmer, you are expected to know the meaning of +@code{/[^[:alnum:][:blank:]]/}. @item The @command{gawk} debugger is designed to be used by running a program (with all its @@ -30271,7 +30395,7 @@ and editing. @end itemize @node Arbitrary Precision Arithmetic -@chapter Arithmetic and Arbitrary Precision Arithmetic with @command{gawk} +@chapter Arithmetic and Arbitrary-Precision Arithmetic with @command{gawk} @cindex arbitrary precision @cindex multiple precision @cindex infinite precision @@ -30281,9 +30405,9 @@ This @value{CHAPTER} introduces some basic concepts relating to how computers do arithmetic and defines some important terms. It then proceeds to describe floating-point arithmetic, which is what @command{awk} uses for all its computations, including a -discussion of arbitrary precision floating point arithmetic, which is +discussion of arbitrary-precision floating-point arithmetic, which is a feature available only in @command{gawk}. It continues on to present -arbitrary precision integers, and concludes with a description of some +arbitrary-precision integers, and concludes with a description of some points where @command{gawk} and the POSIX standard are not quite in agreement. @@ -30346,51 +30470,51 @@ The disadvantage is that their range is limited. @cindex integers, unsigned In computers, integer values come in two flavors: @dfn{signed} and @dfn{unsigned}. Signed values may be negative or positive, whereas -unsigned values are always positive (that is, greater than or equal +unsigned values are always positive (i.e., greater than or equal to zero). In computer systems, integer arithmetic is exact, but the possible range of values is limited. Integer arithmetic is generally faster than -floating point arithmetic. +floating-point arithmetic. -@item Floating point arithmetic +@item Floating-point arithmetic Floating-point numbers represent what were called in school ``real'' -numbers; i.e., those that have a fractional part, such as 3.1415927. +numbers (i.e., those that have a fractional part, such as 3.1415927). The advantage to floating-point numbers is that they can represent a much larger range of values than can integers. The disadvantage is that there are numbers that they cannot represent exactly. -Modern systems support floating point arithmetic in hardware, with a +Modern systems support floating-point arithmetic in hardware, with a limited range of values. There are software libraries that allow -the use of arbitrary precision floating point calculations. +the use of arbitrary-precision floating-point calculations. -POSIX @command{awk} uses @dfn{double precision} floating-point numbers, which -can hold more digits than @dfn{single precision} floating-point numbers. -@command{gawk} has facilities for performing arbitrary precision floating -point arithmetic, which we describe in more detail shortly. +POSIX @command{awk} uses @dfn{double-precision} floating-point numbers, which +can hold more digits than @dfn{single-precision} floating-point numbers. +@command{gawk} has facilities for performing arbitrary-precision +floating-point arithmetic, which we describe in more detail shortly. @end table -Computers work with integer and floating point values of different -ranges. Integer values are usually either 32 or 64 bits in size. Single -precision floating point values occupy 32 bits, whereas double precision -floating point values occupy 64 bits. Floating point values are always +Computers work with integer and floating-point values of different +ranges. Integer values are usually either 32 or 64 bits in size. +Single-precision floating-point values occupy 32 bits, whereas double-precision +floating-point values occupy 64 bits. Floating-point values are always signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. @float Table,table-numeric-ranges -@caption{Value Ranges for Different Numeric Representations} +@caption{Value ranges for different numeric representations} @multitable @columnfractions .34 .33 .33 @headitem Numeric representation @tab Minimum value @tab Maximum value @item 32-bit signed integer @tab @minus{}2,147,483,648 @tab 2,147,483,647 @item 32-bit unsigned integer @tab 0 @tab 4,294,967,295 @item 64-bit signed integer @tab @minus{}9,223,372,036,854,775,808 @tab 9,223,372,036,854,775,807 @item 64-bit unsigned integer @tab 0 @tab 18,446,744,073,709,551,615 -@item Single precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38} -@item Double precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308} +@item Single-precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38} +@item Double-precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308} @end multitable @end float @node Math Definitions -@section Other Stuff To Know +@section Other Stuff to Know The rest of this @value{CHAPTER} uses a number of terms. Here are some informal definitions that should help you work your way through the material @@ -30467,7 +30591,7 @@ How numbers are rounded up or down when necessary. More details are provided later. @item Significand -A floating point value consists the significand multiplied by 10 +A floating-point value consists the significand multiplied by 10 to the power of the exponent. For example, in @code{1.2345e67}, the significand is @code{1.2345}. @@ -30485,19 +30609,19 @@ on some of those terms. On modern systems, floating-point hardware uses the representation and operations defined by the IEEE 754 standard. Three of the standard IEEE 754 types are 32-bit single precision, -64-bit double precision and 128-bit quadruple precision. +64-bit double precision, and 128-bit quadruple precision. The standard also specifies extended precision formats to allow greater precisions and larger exponent ranges. -(@command{awk} uses only the 64-bit double precision format.) +(@command{awk} uses only the 64-bit double-precision format.) @ref{table-ieee-formats} lists the precision and exponent field values for the basic IEEE 754 binary formats: @float Table,table-ieee-formats -@caption{Basic IEEE Format Values} +@caption{Basic IEEE format values} @multitable @columnfractions .20 .20 .20 .20 .20 @headitem Name @tab Total bits @tab Precision @tab Minimum exponent @tab Maximum exponent -@item Single @tab 32 @tab 24 @tab @minus{}126 @tab +127 +@item Single @tab 32 @tab 24 @tab @minus{}126 @tab +127 @item Double @tab 64 @tab 53 @tab @minus{}1022 @tab +1023 @item Quadruple @tab 128 @tab 113 @tab @minus{}16382 @tab +16383 @end multitable @@ -30509,14 +30633,14 @@ one extra bit of significand. @end quotation @node MPFR features -@section Arbitrary Precision Arithmetic Features In @command{gawk} +@section Arbitrary-Precision Arithmetic Features in @command{gawk} -By default, @command{gawk} uses the double precision floating-point values +By default, @command{gawk} uses the double-precision floating-point values supplied by the hardware of the system it runs on. However, if it was -compiled to do so, @command{gawk} uses the @uref{http://www.mpfr.org -GNU MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for arbitrary -precision arithmetic on numbers. You can see if MPFR support is available -like so: +compiled to do so, @command{gawk} uses the @uref{http://www.mpfr.org, +GNU MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for +arbitrary-precision arithmetic on numbers. You can see if MPFR support +is available like so: @example $ @kbd{gawk --version} @@ -30544,11 +30668,11 @@ Two predefined variables, @code{PREC} and @code{ROUNDMODE}, provide control over the working precision and the rounding mode. The precision and the rounding mode are set globally for every operation to follow. -@xref{Setting precision}, and @ref{Setting the rounding mode}, +@DBXREF{Setting precision} and @DBREF{Setting the rounding mode} for more information. @node FP Math Caution -@section Floating Point Arithmetic: Caveat Emptor! +@section Floating-Point Arithmetic: Caveat Emptor! @quotation @i{Math class is tough!} @@ -30581,17 +30705,17 @@ rely just on what we tell you. @end menu @node Inexactness of computations -@subsection Floating Point Arithmetic Is Not Exact +@subsection Floating-Point Arithmetic Is Not Exact Binary floating-point representations and arithmetic are inexact. Simple values like 0.1 cannot be precisely represented using binary floating-point numbers, and the limited precision of floating-point numbers means that slight changes in the order of operations or the precision of intermediate storage -can change the result. To make matters worse, with arbitrary precision -floating-point, you can set the precision before starting a computation, -but then you cannot be sure of the number of significant decimal places -in the final result. +can change the result. To make matters worse, with arbitrary-precision +floating-point arithmetic, you can set the precision before starting a +computation, but then you cannot be sure of the number of significant +decimal places in the final result. @menu * Inexact representation:: Numbers are not exactly represented. @@ -30613,7 +30737,7 @@ y = 0.425 Unlike the number in @code{y}, the number stored in @code{x} is exactly representable -in binary since it can be written as a finite sum of one or +in binary because it can be written as a finite sum of one or more fractions whose denominators are all powers of two. When @command{gawk} reads a floating-point number from program source, it automatically rounds that number to whatever @@ -30639,7 +30763,7 @@ Because the underlying representation can be a little bit off from the exact val comparing floating-point values to see if they are exactly equal is generally a bad idea. Here is an example where it does not work like you would expect: -@example +@example $ @kbd{gawk 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'} @print{} 0 @end example @@ -30648,7 +30772,7 @@ The general wisdom when comparing floating-point values is to see if they are within some small range of each other (called a @dfn{delta}, or @dfn{tolerance}). You have to decide how small a delta is important to you. Code to do -this looks something like this: +this looks something like the following: @example delta = 0.00001 # for example @@ -30668,7 +30792,7 @@ else The loss of accuracy during a single computation with floating-point numbers usually isn't enough to worry about. However, if you compute a -value which is the result of a sequence of floating point operations, +value which is the result of a sequence of floating-point operations, the error can accumulate and greatly affect the computation itself. Here is an attempt to compute the value of @value{PI} using one of its many series representations: @@ -30714,9 +30838,9 @@ $ @kbd{gawk 'BEGIN @{} @end example @node Getting Accuracy -@subsection Getting The Accuracy You Need +@subsection Getting the Accuracy You Need -Can arbitrary precision arithmetic give exact results? There are +Can arbitrary-precision arithmetic give exact results? There are no easy answers. The standard rules of algebra often do not apply when using floating-point arithmetic. Among other things, the distributive and associative laws @@ -30725,12 +30849,12 @@ for your computation. Rounding error, cumulative precision loss and underflow are often troublesome. When @command{gawk} tests the expressions @samp{0.1 + 12.2} and -@samp{12.3} for equality using the machine double precision arithmetic, +@samp{12.3} for equality using the machine double-precision arithmetic, it decides that they are not equal! (@xref{Comparing FP Values}.) You can get the result you want by increasing the precision; 56 bits in this case does the job: -@example +@example $ @kbd{gawk -M -v PREC=56 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'} @print{} 1 @end example @@ -30739,7 +30863,7 @@ If adding more bits is good, perhaps adding even more bits of precision is better? Here is what happens if we use an even larger value of @code{PREC}: -@example +@example $ @kbd{gawk -M -v PREC=201 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'} @print{} 0 @end example @@ -30748,15 +30872,15 @@ This is not a bug in @command{gawk} or in the MPFR library. It is easy to forget that the finite number of bits used to store the value is often just an approximation after proper rounding. The test for equality succeeds if and only if @emph{all} bits in the two operands -are exactly the same. Since this is not necessarily true after floating-point +are exactly the same. Because this is not necessarily true after floating-point computations with a particular precision and effective rounding mode, a straight test for equality may not work. Instead, compare the two numbers to see if they are within the desirable delta of each other. In applications where 15 or fewer decimal places suffice, -hardware double precision arithmetic can be adequate, and is usually much faster. +hardware double-precision arithmetic can be adequate, and is usually much faster. But you need to keep in mind that every floating-point operation -can suffer a new rounding error with catastrophic consequences as illustrated +can suffer a new rounding error with catastrophic consequences, as illustrated by our earlier attempt to compute the value of @value{PI}. Extra precision can greatly enhance the stability and the accuracy of your computation in such cases. @@ -30780,9 +30904,9 @@ an arbitrarily large value for @code{PREC}. Reformulation of the problem at hand is often the correct approach in such situations. @node Try To Round -@subsection Try A Few Extra Bits of Precision and Rounding +@subsection Try a Few Extra Bits of Precision and Rounding -Instead of arbitrary precision floating-point arithmetic, +Instead of arbitrary-precision floating-point arithmetic, often all you need is an adjustment of your logic or a different order for the operations in your calculation. The stability and the accuracy of the computation of @value{PI} @@ -30794,7 +30918,7 @@ simple algebraic transformation: @end example @noindent -After making this, change the program converges to +After making this change, the program converges to @value{PI} in under 30 iterations: @example @@ -30810,7 +30934,7 @@ $ @kbd{gawk -f pi2.awk} @end example @node Setting precision -@subsection Setting The Precision +@subsection Setting the Precision @command{gawk} uses a global working precision; it does not keep track of the precision or accuracy of individual numbers. Performing an arithmetic @@ -30822,14 +30946,14 @@ shown in @ref{table-predefined-precision-strings}, to emulate an IEEE 754 binary format. @float Table,table-predefined-precision-strings -@caption{Predefined Precision Strings For @code{PREC}} +@caption{Predefined precision strings for @code{PREC}} @multitable {@code{"double"}} {12345678901234567890123456789012345} @headitem @code{PREC} @tab IEEE 754 Binary Format -@item @code{"half"} @tab 16-bit half-precision. -@item @code{"single"} @tab Basic 32-bit single precision. -@item @code{"double"} @tab Basic 64-bit double precision. -@item @code{"quad"} @tab Basic 128-bit quadruple precision. -@item @code{"oct"} @tab 256-bit octuple precision. +@item @code{"half"} @tab 16-bit half-precision +@item @code{"single"} @tab Basic 32-bit single precision +@item @code{"double"} @tab Basic 64-bit double precision +@item @code{"quad"} @tab Basic 128-bit quadruple precision +@item @code{"oct"} @tab 256-bit octuple precision @end multitable @end float @@ -30860,7 +30984,7 @@ differences among various ways to print a floating-point constant: @example $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 0.1) @}'} -@print{} 0.1000000000000000055511151 +@print{} 0.1000000000000000055511151 $ @kbd{gawk -M -v PREC=113 'BEGIN @{ printf("%0.25f\n", 0.1) @}'} @print{} 0.1000000000000000000000000 $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", "0.1") @}'} @@ -30870,7 +30994,7 @@ $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 1/10) @}'} @end example @node Setting the rounding mode -@subsection Setting The Rounding Mode +@subsection Setting the Rounding Mode The @code{ROUNDMODE} variable provides program level control over the rounding mode. @@ -30878,7 +31002,7 @@ The correspondence between @code{ROUNDMODE} and the IEEE rounding modes is shown in @ref{table-gawk-rounding-modes}. @float Table,table-gawk-rounding-modes -@caption{@command{gawk} Rounding Modes} +@caption{@command{gawk} rounding modes} @multitable @columnfractions .45 .30 .25 @headitem Rounding Mode @tab IEEE Name @tab @code{ROUNDMODE} @item Round to nearest, ties to even @tab @code{roundTiesToEven} @tab @code{"N"} or @code{"n"} @@ -30893,7 +31017,7 @@ rounding modes is shown in @ref{table-gawk-rounding-modes}. selects the IEEE 754 rounding mode @code{roundTiesToEven}. In @ref{table-gawk-rounding-modes}, the value @code{"A"} selects @code{roundTiesToAway}. This is only available if your version of the -MPFR library supports it; otherwise setting @code{ROUNDMODE} to @code{"A"} +MPFR library supports it; otherwise, setting @code{ROUNDMODE} to @code{"A"} has no effect. The default mode @code{roundTiesToEven} is the most preferred, @@ -30964,14 +31088,14 @@ accumulation of round-off error, look for a significant difference in output when you change the rounding mode to be sure. @node Arbitrary Precision Integers -@section Arbitrary Precision Integer Arithmetic with @command{gawk} +@section Arbitrary-Precision Integer Arithmetic with @command{gawk} @cindex integers, arbitrary precision @cindex arbitrary precision integers When given the @option{-M} option, -@command{gawk} performs all integer arithmetic using GMP arbitrary -precision integers. Any number that looks like an integer in a source -or @value{DF} is stored as an arbitrary precision integer. The size +@command{gawk} performs all integer arithmetic using GMP arbitrary-precision +integers. Any number that looks like an integer in a source +or @value{DF} is stored as an arbitrary-precision integer. The size of the integer is limited only by the available memory. For example, the following computes @iftex @@ -30986,7 +31110,7 @@ the following computes 5<superscript>4<superscript>3<superscript>2</superscript></superscript></superscript>, @c @end docbook the result of which is beyond the -limits of ordinary hardware double precision floating point values: +limits of ordinary hardware double-precision floating-point values: @example $ @kbd{gawk -M 'BEGIN @{} @@ -30998,7 +31122,7 @@ $ @kbd{gawk -M 'BEGIN @{} @print{} 62060698786608744707 ... 92256259918212890625 @end example -If instead you were to compute the same value using arbitrary precision +If instead you were to compute the same value using arbitrary-precision floating-point values, the precision needed for correct output (using the formula @iftex @@ -31043,10 +31167,10 @@ floating-point results exactly. You can either increase the precision @samp{2.0} with an integer, to perform all computations using integer arithmetic to get the correct output. -Sometimes @command{gawk} must implicitly convert an arbitrary precision -integer into an arbitrary precision floating-point value. This is +Sometimes @command{gawk} must implicitly convert an arbitrary-precision +integer into an arbitrary-precision floating-point value. This is primarily because the MPFR library does not always provide the relevant -interface to process arbitrary precision integers or mixed-mode numbers +interface to process arbitrary-precision integers or mixed-mode numbers as needed by an operation or function. In such a case, the precision is set to the minimum value necessary for exact conversion, and the working precision is not used for this purpose. If this is not what you need or @@ -31064,7 +31188,7 @@ to begin with: gawk -M 'BEGIN @{ n = 13.0; print n % 2.0 @}' @end example -Note that for the particular example above, it is likely best +Note that for this particular example, it is likely best to just use the following: @example @@ -31199,13 +31323,13 @@ should support additional features. These features are: @itemize @value{BULLET} @item -Interpretation of floating point data values specified in hexadecimal +Interpretation of floating-point data values specified in hexadecimal notation (e.g., @code{0xDEADBEEF}). (Note: data values, @emph{not} source code constants.) @item -Support for the special IEEE 754 floating point values ``Not A Number'' -(NaN), positive Infinity (``inf'') and negative Infinity (``@minus{}inf''). +Support for the special IEEE 754 floating-point values ``Not A Number'' +(NaN), positive Infinity (``inf''), and negative Infinity (``@minus{}inf''). In particular, the format for these values is as specified by the ISO 1999 C standard, which ignores case and can allow implementation-dependent additional characters after the @samp{nan} and allow either @samp{inf} or @samp{infinity}. @@ -31216,8 +31340,8 @@ practice: @itemize @value{BULLET} @item -The @command{gawk} maintainer feels that supporting hexadecimal floating -point values, in particular, is ugly, and was never intended by the +The @command{gawk} maintainer feels that supporting hexadecimal +floating-point values, in particular, is ugly, and was never intended by the original designers to be part of the language. @item @@ -31231,10 +31355,10 @@ interpretation of the standard, which requires a certain amount of intended by the standard developers. In other words, ``we see how you got where you are, but we don't think that that's where you want to be.'' -Recognizing the above issues, but attempting to provide compatibility +Recognizing these issues, but attempting to provide compatibility with the earlier versions of the standard, the 2008 POSIX standard added explicit wording to allow, but not require, -that @command{awk} support hexadecimal floating point values and +that @command{awk} support hexadecimal floating-point values and special values for ``Not A Number'' and infinity. Although the @command{gawk} maintainer continues to feel that @@ -31291,12 +31415,12 @@ Thus @samp{+nan} and @samp{+NaN} are the same. @itemize @value{BULLET} @item Most computer arithmetic is done using either integers or floating-point -values. Standard @command{awk} uses double precision +values. Standard @command{awk} uses double-precision floating-point values. @item -In the early 1990's, Barbie mistakenly said ``Math class is tough!'' -While math isn't tough, floating-point arithmetic isn't the same +In the early 1990s, Barbie mistakenly said ``Math class is tough!'' +Although math isn't tough, floating-point arithmetic isn't the same as pencil and paper math, and care must be taken: @c nested list @@ -31329,7 +31453,7 @@ arithmetic. Use @code{PREC} to set the precision in bits, and @item With @option{-M}, @command{gawk} performs -arbitrary precision integer arithmetic using the GMP library. +arbitrary-precision integer arithmetic using the GMP library. This is faster and more space efficient than using MPFR for the same calculations. @@ -31342,7 +31466,7 @@ It pays to be aware of them. Overall, there is no need to be unduly suspicious about the results from floating-point arithmetic. The lesson to remember is that floating-point arithmetic is always more complex than arithmetic using pencil and -paper. In order to take advantage of the power of computer floating-point, +paper. In order to take advantage of the power of computer floating point, you need to know its limitations and work within them. For most casual use of floating-point arithmetic, you will often get the expected result if you simply round the display of your final results to the correct number @@ -31406,8 +31530,8 @@ C library routines that could be of use. As with most software, ``the sky is the limit;'' if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! -Extensions are written in C or C++, using the @dfn{Application Programming -Interface} (API) defined for this purpose by the @command{gawk} +Extensions are written in C or C++, using the @dfn{application programming +interface} (API) defined for this purpose by the @command{gawk} developers. The rest of this @value{CHAPTER} explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents @@ -31444,7 +31568,7 @@ int plugin_is_GPL_compatible; @end example @node Extension Mechanism Outline -@section At A High Level How It Works +@section How It Works at a High Level Communication between @command{gawk} and an extension is two-way. First, when an extension @@ -31459,22 +31583,22 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-load-extension"/>}. @ifnotdocbook @float Figure,figure-load-extension -@caption{Loading The Extension} +@caption{Loading the extension} @c FIXME: One day, it should not be necessary to have two cases, @c but rather just the one without the "txt" final argument. @c This applies to the other figures as well. @ifinfo -@center @image{api-figure1, , , Loading The Extension, txt} +@center @image{api-figure1, , , Loading the extension, txt} @end ifinfo @ifnotinfo -@center @image{api-figure1, , , Loading The Extension} +@center @image{api-figure1, , , Loading the extension} @end ifnotinfo @end float @end ifnotdocbook @docbook <figure id="figure-load-extension" float="0"> -<title>Loading The Extension</title> +<title>Loading the extension</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure1.png" format="PNG"/></imageobject> </mediaobject> @@ -31494,19 +31618,19 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-register-new-function @ifnotdocbook @float Figure,figure-register-new-function -@caption{Registering A New Function} +@caption{Registering a new function} @ifinfo -@center @image{api-figure2, , , Registering A New Function, txt} +@center @image{api-figure2, , , Registering a new Function, txt} @end ifinfo @ifnotinfo -@center @image{api-figure2, , , Registering A New Function} +@center @image{api-figure2, , , Registering a new Function} @end ifnotinfo @end float @end ifnotdocbook @docbook <figure id="figure-register-new-function" float="0"> -<title>Registering A New Function</title> +<title>Registering a new function</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure2.png" format="PNG"/></imageobject> </mediaobject> @@ -31527,7 +31651,7 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-call-new-function"/>} @ifnotdocbook @float Figure,figure-call-new-function -@caption{Calling The New Function} +@caption{Calling the new function} @ifinfo @center @image{api-figure3, , , Calling the new function, txt} @end ifinfo @@ -31539,7 +31663,7 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-call-new-function"/>} @docbook <figure id="figure-call-new-function" float="0"> -<title>Calling The New Function</title> +<title>Calling the new function</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure3.png" format="PNG"/></imageobject> </mediaobject> @@ -31575,10 +31699,9 @@ The API also provides major and minor version numbers, so that an extension can check if the @command{gawk} it is loaded with supports the facilities it was compiled with. (Version mismatches ``shouldn't'' happen, but we all know how @emph{that} goes.) -@xref{Extension Versioning}, for details. +@DBXREF{Extension Versioning} for details. @end itemize - @node Extension API Description @section API Description @cindex extension API @@ -31620,20 +31743,23 @@ Allocating, reallocating, and releasing memory. @item Registration functions. You may register: + +@c nested list @itemize @value{MINUS} @item -extension functions, +Extension functions @item -exit callbacks, +Exit callbacks @item -a version string, +A version string @item -input parsers, +Input parsers @item -output wrappers, +Output wrappers @item -and two-way processors. +Two-way processors @end itemize + All of these are discussed in detail, later in this @value{CHAPTER}. @item @@ -31680,7 +31806,7 @@ Some points about using the API: @itemize @value{BULLET} @item -The following types and/or macros and/or functions are referenced +The following types, macros, and/or functions are referenced in @file{gawkapi.h}. For correct use, you must therefore include the corresponding standard header file @emph{before} including @file{gawkapi.h}: @@ -31694,7 +31820,7 @@ corresponding standard header file @emph{before} including @file{gawkapi.h}: @item @code{memset()} @tab @code{<string.h>} @item @code{size_t} @tab @code{<sys/types.h>} @item @code{struct stat} @tab @code{<sys/stat.h>} -@end multitable +@end multitable Due to portability concerns, especially to systems that are not fully standards-compliant, it is your responsibility @@ -31726,7 +31852,7 @@ and is managed by @command{gawk} from then on. The API defines several simple @code{struct}s that map values as seen from @command{awk}. A value can be a @code{double}, a string, or an array (as in multidimensional arrays, or when creating a new array). -String values maintain both pointer and length since embedded @sc{nul} +String values maintain both pointer and length, because embedded @sc{nul} characters are allowed. @quotation NOTE @@ -31751,14 +31877,14 @@ so that the extension can, e.g., print an error message @c The table there should be presented here @end itemize -While you may call the API functions by using the function pointers -directly, the interface is not so pretty. To make extension code look +You may call the API functions by using the function pointers +directly, but the interface is not so pretty. To make extension code look more like regular code, the @file{gawkapi.h} header file defines several macros that you should use in your code. This @value{SECTION} presents the macros as if they were functions. @node General Data Types -@subsection General Purpose Data Types +@subsection General-Purpose Data Types @cindex Robbins, Arnold @cindex Ramey, Chet @@ -31773,9 +31899,10 @@ can accommodate both love and hate.} @author Chet Ramey @end quotation -The extension API defines a number of simple types and structures for general -purpose use. Additional, more specialized, data structures are introduced -in subsequent @value{SECTION}s, together with the functions that use them. +The extension API defines a number of simple types and structures for +general-purpose use. Additional, more specialized, data structures are +introduced in subsequent @value{SECTION}s, together with the functions +that use them. @table @code @item typedef void *awk_ext_id_t; @@ -31802,8 +31929,9 @@ A simple boolean type. This represents a mutable string. @command{gawk} owns the memory pointed to if it supplied the value. Otherwise, it takes ownership of the memory pointed to. -@strong{Such memory must come from calling one of the -@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()} functions!} +@emph{Such memory must come from calling one of the +@code{gawk_malloc()}, @code{gawk_calloc()}, or +@code{gawk_realloc()} functions!} As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -31829,7 +31957,7 @@ It is used in the following @code{struct}. @itemx @ @ @ @ @ @ @ @ awk_value_cookie_t@ vc; @itemx @ @ @ @ @} u; @itemx @} awk_value_t; -An ``@command{awk} value.'' +An ``@command{awk} value.'' The @code{val_type} member indicates what kind of value the @code{union} holds, and each member is of the appropriate type. @@ -31842,13 +31970,14 @@ These macros make accessing the fields of the @code{awk_value_t} more readable. @item typedef void *awk_scalar_t; -Scalars can be represented as an opaque type. These values are obtained from -@command{gawk} and then passed back into it. This is discussed in a general fashion below, -and in more detail in @ref{Symbol table by cookie}. +Scalars can be represented as an opaque type. These values are obtained +from @command{gawk} and then passed back into it. This is discussed +in a general fashion in the text following this list, and in more detail in +@ref{Symbol table by cookie}. @item typedef void *awk_value_cookie_t; A ``value cookie'' is an opaque type representing a cached value. -This is also discussed in a general fashion below, +This is also discussed in a general fashion in the text following this list, and in more detail in @ref{Cached values}. @end table @@ -31858,7 +31987,7 @@ Scalar values in @command{awk} are either numbers or strings. The indicates what is in the @code{union}. Representing numbers is easy---the API uses a C @code{double}. Strings -require more work. Since @command{gawk} allows embedded @sc{nul} bytes +require more work. Because @command{gawk} allows embedded @sc{nul} bytes in string values, a string must be represented as a pair containing a data-pointer and length. This is the @code{awk_string_t} type. @@ -31871,13 +32000,13 @@ itself be an array. Discussion of arrays is delayed until The various macros listed earlier make it easier to use the elements of the @code{union} as if they were fields in a @code{struct}; this is a common coding practice in C. Such code is easier to write and to -read, however it remains @emph{your} responsibility to make sure that +read, but it remains @emph{your} responsibility to make sure that the @code{val_type} member correctly reflects the type of the value in the @code{awk_value_t}. Conceptually, the first three members of the @code{union} (number, string, and array) are all that is needed for working with @command{awk} values. -However, since the API provides routines for accessing and changing +However, because the API provides routines for accessing and changing the value of global scalar variables only by using the variable's name, there is a performance penalty: @command{gawk} must find the variable each time it is accessed and changed. This turns out to be a real issue, @@ -31917,7 +32046,7 @@ The API provides a number of @dfn{memory allocation} functions for allocating memory that can be passed to @command{gawk}, as well as a number of convenience macros. This @value{SUBSECTION} presents them all as function prototypes, in -the way that extension code would use them. +the way that extension code would use them: @table @code @item void *gawk_malloc(size_t size); @@ -31962,7 +32091,8 @@ The arguments to this macro are as follows: The pointer variable to point at the allocated storage. @item type -The type of the pointer variable, used to create a cast for the call to @code{gawk_malloc()}. +The type of the pointer variable. This is used to create a cast for +the call to @code{gawk_malloc()}. @item size The total number of bytes to be allocated. @@ -31997,7 +32127,7 @@ The arguments are the same as for the @code{emalloc()} macro. The API provides a number of @dfn{constructor} functions for creating string and numeric values, as well as a number of convenience macros. This @value{SUBSECTION} presents them all as function prototypes, in -the way that extension code would use them. +the way that extension code would use them: @table @code @item static inline awk_value_t * @@ -32076,8 +32206,8 @@ This is a pointer to the C function that provides the extension's functionality. The function must fill in @code{*result} with either a number or a string. @command{gawk} takes ownership of any string memory. -As mentioned earlier, string memory @strong{must} come from one of @code{gawk_malloc()}, -@code{gawk_calloc()} or @code{gawk_realloc()}. +As mentioned earlier, string memory @strong{must} come from one of +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The @code{num_actual_args} argument tells the C function how many actual parameters were passed from the calling @command{awk} code. @@ -32112,7 +32242,7 @@ Such functions are useful if you have general ``cleanup'' tasks that should be performed in your extension (such as closing database connections or other resource deallocations). You can register such -a function with @command{gawk} using the following function. +a function with @command{gawk} using the following function: @table @code @item void awk_atexit(void (*funcp)(void *data, int exit_status), @@ -32133,8 +32263,9 @@ the function pointed to by @code{funcp}. @end table @end table -Exit callback functions are called in Last-In-First-Out (LIFO) order---that is, in -the reverse order in which they are registered with @command{gawk}. +Exit callback functions are called in last-in-first-out (LIFO) +order---that is, in the reverse order in which they are registered with +@command{gawk}. @node Extension Version String @subsubsection Registering An Extension Version String @@ -32145,7 +32276,7 @@ version of your extension, with @command{gawk}, as follows: @table @code @item void register_ext_version(const char *version); Register the string pointed to by @code{version} with @command{gawk}. -@command{gawk} does @emph{not} copy the @code{version} string, so +Note that @command{gawk} does @emph{not} copy the @code{version} string, so it should not be changed. @end table @@ -32170,14 +32301,14 @@ To provide an input parser, you must first provide two functions (where @var{XXX} is a prefix name for your extension): @table @code -@item awk_bool_t @var{XXX}_can_take_file(const awk_input_buf_t *iobuf) +@item awk_bool_t @var{XXX}_can_take_file(const awk_input_buf_t *iobuf); This function examines the information available in @code{iobuf} (which we discuss shortly). Based on the information there, it decides if the input parser should be used for this file. If so, it should return true. Otherwise, it should return false. It should not change any state (variable values, etc.) within @command{gawk}. -@item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf) +@item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf); When @command{gawk} decides to hand control of the file over to the input parser, it calls this function. This function in turn must fill in certain fields in the @code{awk_input_buf_t} structure, and ensure @@ -32227,7 +32358,7 @@ appropriately. @item When your extension is loaded, register your input parser with @command{gawk} using the @code{register_input_parser()} API function -(described below). +(described next). @end enumerate An @code{awk_input_buf_t} looks like this: @@ -32257,7 +32388,7 @@ The name of the file. @item int fd; A file descriptor for the file. If @command{gawk} was able to -open the file, then @code{fd} will @emph{not} be equal to +open the file, then @code{fd} will @emph{not} be equal to @code{INVALID_HANDLE}. Otherwise, it will. @item struct stat sbuf; @@ -32271,15 +32402,15 @@ The decision can be made based upon @command{gawk} state (the value of a variable defined previously by the extension and set by @command{awk} code), the name of the file, whether or not the file descriptor is valid, the information -in the @code{struct stat}, or any combination of the above. +in the @code{struct stat}, or any combination of these factors. Once @code{@var{XXX}_can_take_file()} has returned true, and @command{gawk} has decided to use your input parser, it calls @code{@var{XXX}_take_control_of()}. That function then fills one of either the @code{get_record} field or the @code{read_func} field in the @code{awk_input_buf_t}. It must also ensure that @code{fd} is @emph{not} -set to @code{INVALID_HANDLE}. All of the fields that may be filled by -@code{@var{XXX}_take_control_of()} are as follows: +set to @code{INVALID_HANDLE}. The following list describes the fields that +may be filled by @code{@var{XXX}_take_control_of()}: @table @code @item void *opaque; @@ -32294,13 +32425,13 @@ is not required to use this pointer. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len); This function pointer should point to a function that creates the input records. Said function is the core of the input parser. Its behavior -is described below. +is described in the text following this list. @item ssize_t (*read_func)(); This function pointer should point to function that has the same behavior as the standard POSIX @code{read()} system call. It is an alternative to the @code{get_record} pointer. Its behavior -is also described below. +is also described in the text following this list. @item void (*close_func)(struct awk_input *iobuf); This function pointer should point to a function that does @@ -32438,7 +32569,7 @@ values, etc.) within @command{gawk}. The function pointed to by this field is called when @command{gawk} decides to let the output wrapper take control of the file. It should fill in appropriate members of the @code{awk_output_buf_t} structure, -as described below, and return true if successful, false otherwise. +as described next, and return true if successful, false otherwise. @item awk_const struct output_wrapper *awk_const next; This is for use by @command{gawk}; @@ -32581,9 +32712,9 @@ Register the two-way processor pointed to by @code{two_way_processor} with @cindex messages from extensions You can print different kinds of warning messages from your -extension, as described below. Note that for these functions, +extension, as described here. Note that for these functions, you must pass in the extension id received from @command{gawk} -when the extension was loaded.@footnote{Because the API uses only ISO C 90 +when the extension was loaded:@footnote{Because the API uses only ISO C 90 features, it cannot make use of the ISO C 99 variadic macro feature to hide that parameter. More's the pity.} @@ -32640,7 +32771,7 @@ value type, as appropriate. This behavior is summarized in @ref{table-value-types-returned}. @float Table,table-value-types-returned -@caption{API Value Types Returned} +@caption{API value types returned} @docbook <informaltable> <tgroup cols="6"> @@ -32652,7 +32783,7 @@ value type, as appropriate. This behavior is summarized in <colspec colwidth="16.6*" colname="c6"/> <spanspec spanname="hspan" namest="c3" nameend="c6" align="center"/> <thead> - <row><entry></entry><entry spanname="hspan"><para>Type of Actual Value:</para></entry></row> + <row><entry></entry><entry spanname="hspan"><para>Type of Actual Value</para></entry></row> <row> <entry></entry> <entry></entry> @@ -32688,7 +32819,7 @@ value type, as appropriate. This behavior is summarized in <entry><para>false</para></entry> </row> <row> - <entry><para><emphasis role="bold">Requested:</emphasis></para></entry> + <entry><para><emphasis role="bold">Requested</emphasis></para></entry> <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> <entry><para>Scalar</para></entry> <entry><para>Scalar</para></entry> @@ -32719,7 +32850,7 @@ value type, as appropriate. This behavior is summarized in @ifnotplaintext @ifnotdocbook @multitable @columnfractions .50 .50 -@headitem @tab Type of Actual Value: +@headitem @tab Type of Actual Value @end multitable @c 10/2014: Thanks to Karl Berry for this bit to reduce the space: @tex @@ -32730,7 +32861,7 @@ value type, as appropriate. This behavior is summarized in @item @tab @b{String} @tab String @tab String @tab false @tab false @item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false @item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false -@item @b{Requested:} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false +@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false @item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined @item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false @end multitable @@ -32784,7 +32915,7 @@ indicates the type of value expected. @item awk_bool_t set_argument(size_t count, awk_array_t array); Convert a parameter that was undefined into an array; this provides call-by-reference for arrays. Return false if @code{count} is too big, -or if the argument's type is not undefined. @xref{Array Manipulation}, +or if the argument's type is not undefined. @DBXREF{Array Manipulation} for more information on creating arrays. @end table @@ -32839,7 +32970,7 @@ cannot change any of those variables. @quotation CAUTION It is possible for the lookup of @code{PROCINFO} to fail. This happens if the @command{awk} program being run does not reference @code{PROCINFO}; -in this case @command{gawk} doesn't bother to create the array and +in this case, @command{gawk} doesn't bother to create the array and populate it. @end quotation @@ -32849,9 +32980,9 @@ populate it. A @dfn{scalar cookie} is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in @command{gawk}'s symbol table every time -access is needed. This was discussed earlier, in @ref{General Data Types}. +access is needed. This was discussed earlier in @ref{General Data Types}. -The following functions let you work with scalar cookies. +The following functions let you work with scalar cookies: @table @code @item awk_bool_t sym_lookup_scalar(awk_scalar_t cookie, @@ -32896,18 +33027,21 @@ do_magic(int nargs, awk_value_t *result) @noindent This code looks (and is) simple and straightforward. So what's the problem? -Consider what happens if @command{awk}-level code associated with your -extension calls the @code{magic()} function (implemented in C by @code{do_magic()}), -once per record, while processing hundreds of thousands or millions of records. -The @code{MAGIC_VAR} variable is looked up in the symbol table once or twice per function call! +Well, consider what happens if @command{awk}-level code associated +with your extension calls the @code{magic()} function (implemented in +C by @code{do_magic()}), once per record, while processing hundreds +of thousands or millions of records. The @code{MAGIC_VAR} variable is +looked up in the symbol table once or twice per function call! -The symbol table lookup is really pure overhead; it is considerably more efficient -to get a cookie that represents the variable, and use that to get the variable's -value and update it as needed.@footnote{The difference is measurable and quite real. Trust us.} +The symbol table lookup is really pure overhead; it is considerably +more efficient to get a cookie that represents the variable, and use +that to get the variable's value and update it as needed.@footnote{The +difference is measurable and quite real. Trust us.} -Thus, the way to use cookies is as follows. First, install your extension's variable -in @command{gawk}'s symbol table using @code{sym_update()}, as usual. Then get a -scalar cookie for the variable using @code{sym_lookup()}: +Thus, the way to use cookies is as follows. First, install +your extension's variable in @command{gawk}'s symbol table using +@code{sym_update()}, as usual. Then get a scalar cookie for the variable +using @code{sym_lookup()}: @example static awk_scalar_t magic_var_cookie; /* cookie for MAGIC_VAR */ @@ -32970,7 +33104,7 @@ or @code{sym_update_scalar()}, as you like. However, you can understand the point of cached values if you remember that @emph{every} string value's storage @emph{must} come from @code{gawk_malloc()}, -@code{gawk_calloc()} or @code{gawk_realloc()}. +@code{gawk_calloc()}, or @code{gawk_realloc()}. If you have 20 variables, all of which have the same string value, you must create 20 identical copies of the string.@footnote{Numeric values are clearly less problematic, requiring only a C @code{double} to store.} @@ -32981,11 +33115,11 @@ is what the routines in this section let you do. The functions are as follows: @table @code @item awk_bool_t create_value(awk_value_t *value, awk_value_cookie_t *result); -Create a cached string or numeric value from @code{value} for efficient later -assignment. -Only values of type @code{AWK_NUMBER} and @code{AWK_STRING} are allowed. Any other type -is rejected. While @code{AWK_UNDEFINED} could be allowed, doing so would -result in inferior performance. +Create a cached string or numeric value from @code{value} for +efficient later assignment. Only values of type @code{AWK_NUMBER} +and @code{AWK_STRING} are allowed. Any other type is rejected. +@code{AWK_UNDEFINED} could be allowed, but doing so would result in +inferior performance. @item awk_bool_t release_value(awk_value_cookie_t vc); Release the memory associated with a value cookie obtained @@ -33006,7 +33140,7 @@ my_extension_init() size_t long_string_len; /* code from earlier */ - @dots{} + @dots{} /* @dots{} fill in long_string and long_string_len @dots{} */ make_malloced_string(long_string, long_string_len, & value); create_value(& value, & answer_cookie); /* create cookie */ @@ -33036,7 +33170,7 @@ do_magic(int nargs, awk_value_t *result) @end example @noindent -Using value cookies in this way saves considerable storage, since all of +Using value cookies in this way saves considerable storage, as all of @code{VAR1} through @code{VAR100} share the same value. You might be wondering, ``Is this sharing problematic? @@ -33058,7 +33192,7 @@ you should release any cached values that you created, using @subsection Array Manipulation @cindex array manipulation in extensions -The primary data structure@footnote{Okay, the only data structure.} in @command{awk} +The primary data structure@footnote{OK, the only data structure.} in @command{awk} is the associative array (@pxref{Arrays}). Extensions need to be able to manipulate @command{awk} arrays. The API provides a number of data structures for working with arrays, @@ -33079,7 +33213,7 @@ both work with and create true arrays of arrays (@pxref{General Data Types}). @node Array Data Types @subsubsection Array Data Types -The data types associated with arrays are listed below. +The data types associated with arrays are as follows: @table @code @item typedef void *awk_array_t; @@ -33198,7 +33332,7 @@ The following functions relate to arrays as a whole: @table @code @item awk_array_t create_array(void); Create a new array to which elements may be added. -@xref{Creating Arrays}, for a discussion of how to +@DBXREF{Creating Arrays} for a discussion of how to create a new array and add elements to it. @item awk_bool_t clear_array(awk_array_t a_cookie); @@ -33233,7 +33367,7 @@ The function returns true upon success, false otherwise. @node Flattening Arrays @subsubsection Working With All The Elements of an Array -To @dfn{flatten} an array is create a structure that +To @dfn{flatten} an array is to create a structure that represents the full array in a fashion that makes it easy for C code to traverse the entire array. Test code in @file{extension/testext.c} does this, and also serves @@ -33401,7 +33535,7 @@ code) once you have called @code{release_flattened_array()}: @} @end example -Finally, since everything was successful, the function sets the +Finally, because everything was successful, the function sets the return value to success, and returns: @example @@ -33436,7 +33570,7 @@ code can access them and manipulate them. There are two important points about creating arrays from extension code: -@enumerate 1 +@itemize @value{BULLET} @item You must install a new array into @command{gawk}'s symbol table immediately upon creating it. Once you have done so, @@ -33458,7 +33592,7 @@ using @code{sym_update()}, or install it as an element in a previously existing array using @code{set_array_element()}. We show example code shortly. @item -Due to gawk internals, after using @code{sym_update()} to install an array +Due to @command{gawk} internals, after using @code{sym_update()} to install an array into @command{gawk}, you have to retrieve the array cookie from the value passed in to @command{sym_update()} before doing anything else with it, like so: @@ -33478,7 +33612,7 @@ new_array = val.array_cookie; /* YOU MUST DO THIS */ If installing an array as a subarray, you must also retrieve the value of the array cookie after the call to @code{set_element()}. -@end enumerate +@end itemize The following C code is a simple test extension to create an array with two regular elements and with a subarray. The leading @code{#include} @@ -33597,7 +33731,7 @@ dl_load_func(func_table, testarray, "") @end ignore @end example -Here is sample script that loads the extension +Here is a sample script that loads the extension and then dumps the array: @example @@ -33627,7 +33761,7 @@ $ @kbd{AWKLIBPATH=$PWD ./gawk -f subarray.awk} @end example @noindent -(@xref{Finding Extensions}, for more information on the +(@DBXREF{Finding Extensions} for more information on the @env{AWKLIBPATH} environment variable.) @node Extension API Variables @@ -33713,8 +33847,7 @@ whether the corresponding command-line options were enabled when This variable is true if @command{gawk} was invoked with @option{--debug} option. @item do_lint -This variable is true if @command{gawk} was invoked with @option{--lint} option -(@pxref{Options}). +This variable is true if @command{gawk} was invoked with @option{--lint} option. @item do_mpfr This variable is true if @command{gawk} was invoked with @option{--bignum} option. @@ -33739,8 +33872,8 @@ The others should not change during execution. As mentioned earlier (@pxref{Extension Mechanism Outline}), the function definitions as presented are really macros. To use these macros, your extension must provide a small amount of boilerplate code (variables and -functions) towards the top of your source file, using pre-defined names -as described below. The boilerplate needed is also provided in comments +functions) toward the top of your source file, using predefined names +as described here. The boilerplate needed is also provided in comments in the @file{gawkapi.h} header file: @example @@ -33828,7 +33961,7 @@ This macro expands to a @code{dl_load()} function that performs all the necessary initializations. @end table -The point of the all the variables and arrays is to let the +The point of all the variables and arrays is to let the @code{dl_load()} function (from the @code{dl_load_func()} macro) do all the standard work. It does the following: @@ -33863,7 +33996,7 @@ Compiled extensions have to be installed in a directory where built in the default fashion, the directory in which to find extensions is @file{/usr/local/lib/gawk}. You can also specify a search path with a list of directories to search for compiled extensions. -@xref{AWKLIBPATH Variable}, for more information. +@DBXREF{AWKLIBPATH Variable} for more information. @node Extension Example @section Example: Some File Functions @@ -33871,7 +34004,7 @@ path with a list of directories to search for compiled extensions. @quotation @i{No matter where you go, there you are.} -@author Buckaroo Bonzai +@author Buckaroo Banzai @end quotation @c It's enough to show chdir and stat, no need for fts @@ -34044,9 +34177,9 @@ in the @command{gawk} distribution for the complete version.} The file includes a number of standard header files, and then includes the @file{gawkapi.h} header file which provides the API definitions. -Those are followed by the necessary variable declarations +Those are followed by the necessary variable declarations to make use of the API macros and boilerplate code -(@pxref{Extension API Boilerplate}). +(@pxref{Extension API Boilerplate}): @example #ifdef HAVE_CONFIG_H @@ -34087,7 +34220,7 @@ that implements it is called @code{do_foo()}. The function should have two arguments: the first is an @code{int} usually called @code{nargs}, that represents the number of actual arguments for the function. The second is a pointer to an @code{awk_value_t}, usually named -@code{result}. +@code{result}: @example /* do_chdir --- provide dynamically loaded chdir() function for gawk */ @@ -34107,13 +34240,13 @@ do_chdir(int nargs, awk_value_t *result) @end example The @code{newdir} -variable represents the new directory to change to, retrieved +variable represents the new directory to change to, which is retrieved with @code{get_argument()}. Note that the first argument is numbered zero. If the argument is retrieved successfully, the function calls the @code{chdir()} system call. If the @code{chdir()} fails, @code{ERRNO} -is updated. +is updated: @example if (get_argument(0, AWK_STRING, & newdir)) @{ @@ -34314,7 +34447,7 @@ of @code{stat()}) to get the file information, in case the file is a symbolic link. However, if there were three arguments, @code{statfunc} is set point to @code{stat()}, instead. -Here is the @code{do_stat()} function. It starts with +Here is the @code{do_stat()} function, which starts with variable declarations and argument checking: @ignore @@ -34429,7 +34562,7 @@ dl_load_func(func_table, filefuncs, "") And that's it! @node Using Internal File Ops -@subsection Integrating The Extensions +@subsection Integrating the Extensions @cindex @command{gawk}, interpreter@comma{} adding code to Now that the code is written, it must be possible to add it at @@ -34438,9 +34571,9 @@ code must be compiled. Assuming that the functions are in a file named @file{filefuncs.c}, and @var{idir} is the location of the @file{gawkapi.h} header file, the following steps@footnote{In practice, you would probably want to -use the GNU Autotools---Automake, Autoconf, Libtool, and @command{gettext}---to +use the GNU Autotools (Automake, Autoconf, Libtool, and @command{gettext}) to configure and build your libraries. Instructions for doing so are beyond -the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for Internet links to +the scope of this @value{DOCUMENT}. @DBXREF{gawkextlib} for Internet links to the tools.} create a GNU/Linux shared library: @example @@ -34448,7 +34581,7 @@ $ @kbd{gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g -I@var{idir} filefuncs.c} $ @kbd{gcc -o filefuncs.so -shared filefuncs.o} @end example -Once the library exists, it is loaded by using the @code{@@load} keyword. +Once the library exists, it is loaded by using the @code{@@load} keyword: @example # file testff.awk @@ -34512,13 +34645,14 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @end example @node Extension Samples -@section The Sample Extensions In The @command{gawk} Distribution +@section The Sample Extensions in the @command{gawk} Distribution @cindex extensions distributed with @command{gawk} This @value{SECTION} provides brief overviews of the sample extensions that come in the @command{gawk} distribution. Some of them are intended -for production use, such the @code{filefuncs}, @code{readdir} and @code{inplace} extensions. -Others mainly provide example code that shows how to use the extension API. +for production use (e.g., the @code{filefuncs}, @code{readdir} and +@code{inplace} extensions). Others mainly provide example code that +shows how to use the extension API. @menu * Extension Sample File Functions:: The file functions sample. @@ -34539,9 +34673,9 @@ Others mainly provide example code that shows how to use the extension API. @end menu @node Extension Sample File Functions -@subsection File Related Functions +@subsection File-Related Functions -The @code{filefuncs} extension provides three different functions, as follows: +The @code{filefuncs} extension provides three different functions, as follows. The usage is: @table @asis @@ -34552,7 +34686,7 @@ This is how you load the extension. @item @code{result = chdir("/some/directory")} The @code{chdir()} function is a direct hook to the @code{chdir()} system call to change the current directory. It returns zero -upon success or less than zero upon error. In the latter case it updates +upon success or less than zero upon error. In the latter case, it updates @code{ERRNO}. @cindex @code{stat()} extension function @@ -34560,7 +34694,7 @@ upon success or less than zero upon error. In the latter case it updates The @code{stat()} function provides a hook into the @code{stat()} system call. It returns zero upon success or less than zero upon error. -In the latter case it updates @code{ERRNO}. +In the latter case, it updates @code{ERRNO}. By default, it uses the @code{lstat()} system call. However, if passed a third argument, it uses @code{stat()} instead. @@ -34607,8 +34741,8 @@ Not all systems support all file types. @tab All @item @code{flags = or(FTS_PHYSICAL, ...)} @itemx @code{result = fts(pathlist, flags, filedata)} Walk the file trees provided in @code{pathlist} and fill in the -@code{filedata} array as described below. @code{flags} is the bitwise -OR of several predefined values, also described below. +@code{filedata} array as described next. @code{flags} is the bitwise +OR of several predefined values, also described in a moment. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -34656,7 +34790,7 @@ whether or not @code{FTS_LOGICAL} is set. By default, the C library @code{fts()} routines do not return entries for @file{.} (dot) and @file{..} (dot-dot). This option causes entries for dot-dot to also be included. (The extension always includes an entry -for dot, see below.) +for dot; more on this in a moment.) @item FTS_XDEV During a traversal, do not cross onto a different mounted filesystem. @@ -34666,7 +34800,7 @@ During a traversal, do not cross onto a different mounted filesystem. The @code{filedata} array is first cleared. Then, @code{fts()} creates an element in @code{filedata} for every element in @code{pathlist}. The index is the name of the directory or file given in @code{pathlist}. -The element for this index is itself an array. There are two cases. +The element for this index is itself an array. There are two cases: @c nested table @table @emph @@ -34692,8 +34826,8 @@ contain an element named @code{"error"}, which is a string describing the error. @item The path is a directory In this case, the array contains one element for each entry in the -directory. If an entry is a file, that element is as for files, just -described. If the entry is a directory, that element is (recursively), +directory. If an entry is a file, that element is the same as for files, just +described. If the entry is a directory, that element is (recursively) an array describing the subdirectory. If @code{FTS_SEEDOT} was provided in the flags, then there will also be an element named @code{".."}. This element will be an array containing the data as provided by @code{stat()}. @@ -34712,8 +34846,8 @@ The @code{fts()} extension does not exactly mimic the interface of the C library @code{fts()} routines, choosing instead to provide an interface that is based on associative arrays, which is more comfortable to use from an @command{awk} program. This includes the -lack of a comparison function, since @command{gawk} already provides -powerful array sorting facilities. While an @code{fts_read()}-like +lack of a comparison function, because @command{gawk} already provides +powerful array sorting facilities. Although an @code{fts_read()}-like interface could have been provided, this felt less natural than simply creating a multidimensional array to represent the file hierarchy and its information. @@ -34723,7 +34857,7 @@ See @file{test/fts.awk} in the @command{gawk} distribution for an example use of the @code{fts()} extension function. @node Extension Sample Fnmatch -@subsection Interface To @code{fnmatch()} +@subsection Interface to @code{fnmatch()} This extension provides an interface to the C library @code{fnmatch()} function. The usage is: @@ -34736,10 +34870,10 @@ This is how you load the extension. @item result = fnmatch(pattern, string, flags) The return value is zero on success, @code{FNM_NOMATCH} if the string did not match the pattern, or -a different non-zero value if an error occurred. +a different nonzero value if an error occurred. @end table -Besides the @code{fnmatch()} function, the @code{fnmatch} extension +In addition to the @code{fnmatch()} function, the @code{fnmatch} extension adds one constant (@code{FNM_NOMATCH}), and an array of flag values named @code{FNM}. @@ -34757,7 +34891,7 @@ Either zero, or the bitwise OR of one or more of the flags in the @code{FNM} array. @end table -The flags are follows: +The flags are as follows: @multitable @columnfractions .25 .75 @headitem Array element @tab Corresponding flag defined by @code{fnmatch()} @@ -34780,9 +34914,9 @@ if (fnmatch("*.a", "foo.c", flags) == FNM_NOMATCH) @end example @node Extension Sample Fork -@subsection Interface To @code{fork()}, @code{wait()} and @code{waitpid()} +@subsection Interface to @code{fork()}, @code{wait()}, and @code{waitpid()} -The @code{fork} extension adds three functions, as follows. +The @code{fork} extension adds three functions, as follows: @table @code @item @@load "fork" @@ -34880,7 +35014,7 @@ $ @kbd{gawk -i inplace -v INPLACE_SUFFIX=.bak '@{ gsub(/foo/, "bar") @}} @subsection Character and Numeric values: @code{ord()} and @code{chr()} The @code{ordchr} extension adds two functions, named -@code{ord()} and @code{chr()}, as follows. +@code{ord()} and @code{chr()}, as follows: @table @code @item @@load "ordchr" @@ -34928,7 +35062,7 @@ indicating the type of the file. The letters and their corresponding file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types -@caption{File Types Returned By The @code{readdir} Extension} +@caption{File types returned by the @code{readdir} extension} @multitable @columnfractions .1 .9 @headitem Letter @tab File Type @item @code{b} @tab Block device @@ -34965,7 +35099,7 @@ BEGIN @{ FS = "/" @} @subsection Reversing Output The @code{revoutput} extension adds a simple output wrapper that reverses -the characters in each output line. It's main purpose is to show how to +the characters in each output line. Its main purpose is to show how to write an output wrapper, although it may be mildly amusing for the unwary. Here is an example: @@ -34987,7 +35121,7 @@ The output from this program is: The @code{revtwoway} extension adds a simple two-way processor that reverses the characters in each line sent to it for reading back by -the @command{awk} program. It's main purpose is to show how to write +the @command{awk} program. Its main purpose is to show how to write a two-way processor, although it may also be mildly amusing. The following example shows how to use it: @@ -35014,7 +35148,7 @@ is: @samp{cinap t'nod}. @node Extension Sample Read write array -@subsection Dumping and Restoring An Array +@subsection Dumping and Restoring an Array The @code{rwarray} extension adds two functions, named @code{writea()} and @code{reada()}, as follows: @@ -35040,7 +35174,7 @@ Here too, the return value is one on success and zero upon failure. The array created by @code{reada()} is identical to that written by @code{writea()} in the sense that the contents are the same. However, -due to implementation issues, the array traversal order of the recreated +due to implementation issues, the array traversal order of the re-created array is likely to be different from that of the original array. As array traversal order in @command{awk} is by default undefined, this is (technically) not a problem. If you need to guarantee a particular traversal @@ -35048,7 +35182,7 @@ order, use the array sorting features in @command{gawk} to do so (@pxref{Array Sorting}). The file contains binary data. All integral values are written in network -byte order. However, double precision floating-point values are written +byte order. However, double-precision floating-point values are written as native binary data. Thus, arrays containing only string data can theoretically be dumped on systems with one byte order and restored on systems with a different one, but this has not been tried. @@ -35064,7 +35198,7 @@ ret = reada("arraydump.bin", array) @end example @node Extension Sample Readfile -@subsection Reading An Entire File +@subsection Reading an Entire File The @code{readfile} extension adds a single function named @code{readfile()}, and an input parser: @@ -35111,7 +35245,7 @@ This is how you load the extension. @cindex @code{gettimeofday()} extension function @item the_time = gettimeofday() Return the time in seconds that has elapsed since 1970-01-01 UTC as a -floating point value. If the time is unavailable on this platform, return +floating-point value. If the time is unavailable on this platform, return @minus{}1 and set @code{ERRNO}. The returned time should have sub-second precision, but the actual precision may vary based on the platform. If the standard C @code{gettimeofday()} system call is available on this @@ -35150,26 +35284,29 @@ project provides a number of @command{gawk} extensions, including one for processing XML files. This is the evolution of the original @command{xgawk} (XML @command{gawk}) project. -As of this writing, there are five extensions: +As of this writing, there are six extensions: @itemize @value{BULLET} @item -GD graphics library extension. +GD graphics library extension + +@item +PDF extension @item -PDF extension. +PostgreSQL extension @item -PostgreSQL extension. +MPFR library extension +(this provides access to a number of MPFR functions which @command{gawk}'s +native MPFR support does not) @item -MPFR library extension. -This provides access to a number of MPFR functions which @command{gawk}'s -native MPFR support does not. +Redis extension @item XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} -XML parsing library. +XML parsing library @end itemize @cindex @command{git} utility @@ -35220,9 +35357,9 @@ to install both @command{gawk} and @code{gawkextlib}, depending upon how your system works. If you write an extension that you wish to share with other -@command{gawk} users, please consider doing so through the +@command{gawk} users, consider doing so through the @code{gawkextlib} project. -See the project's web site for more information. +See the project's website for more information. @node Extension summary @section Summary @@ -35230,7 +35367,7 @@ See the project's web site for more information. @itemize @value{BULLET} @item You can write extensions (sometimes called plug-ins) for @command{gawk} -in C or C++ using the Application Programming Interface (API) defined +in C or C++ using the application programming interface (API) defined by the @command{gawk} developers. @item @@ -35261,44 +35398,44 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item -Allocating, reallocating, and releasing memory. +Allocating, reallocating, and releasing memory @item -Registration functions. You may register +Registration functions (you may register extension functions, exit callbacks, a version string, input parsers, output wrappers, -and two-way processors. +and two-way processors) @item -Printing fatal, warning, and ``lint'' warning messages. +Printing fatal, warning, and ``lint'' warning messages @item -Updating @code{ERRNO}, or unsetting it. +Updating @code{ERRNO}, or unsetting it @item Accessing parameters, including converting an undefined parameter into -an array. +an array @item -Symbol table access: retrieving a global variable, creating one, -or changing one. +Symbol table access (retrieving a global variable, creating one, +or changing one) @item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and -can be a big performance win. +can be a big performance win @item -Manipulating arrays: -retrieving, adding, deleting, and modifying elements; +Manipulating arrays +(retrieving, adding, deleting, and modifying elements; getting the count of elements in an array; creating a new array; clearing an array; and -flattening an array for easy C style looping over all its indices and elements. +flattening an array for easy C style looping over all its indices and elements) @end itemize @item @@ -35327,8 +35464,8 @@ that loaded it. @item It is easiest to start a new extension by copying the boilerplate code -described in this @value{CHAPTER}. Macros in the @file{gawkapi.h} make -this easier to do. +described in this @value{CHAPTER}. Macros in the @file{gawkapi.h} header +file make this easier to do. @item The @command{gawk} distribution includes a number of small but useful @@ -35377,34 +35514,34 @@ and the Glossary: @end ifclear @ifset FOR_PRINT -Part IV contains two appendices and the license that +Part IV contains three appendices, the last of which is the license that covers the @command{gawk} source code: @end ifset @itemize @value{BULLET} @item -@ref{Language History}. +@ref{Language History} @item -@ref{Installation}. +@ref{Installation} @ifclear FOR_PRINT @item -@ref{Notes}. +@ref{Notes} @item -@ref{Basic Concepts}. +@ref{Basic Concepts} @item -@ref{Glossary}. +@ref{Glossary} @end ifclear @item -@ref{Copying}. +@ref{Copying} @ifclear FOR_PRINT @item -@ref{GNU Free Documentation License}. +@ref{GNU Free Documentation License} @end ifclear @end itemize @end ifdocbook @@ -35413,7 +35550,7 @@ covers the @command{gawk} source code: @appendix The Evolution of the @command{awk} Language This @value{DOCUMENT} describes the GNU implementation of @command{awk}, -which follows the POSIX specification. Many long-time @command{awk} +which follows the POSIX specification. Many longtime @command{awk} users learned @command{awk} programming with the original @command{awk} implementation in Version 7 Unix. (This implementation was the basis for @command{awk} in Berkeley Unix, through 4.3-Reno. Subsequent versions @@ -35581,7 +35718,7 @@ for case translation (@pxref{String Functions}). @item -A cleaner specification for the @code{%c} format-control letter in the +A cleaner specification for the @samp{%c} format-control letter in the @code{printf} function (@pxref{Control Letters}). @@ -35648,7 +35785,7 @@ The ability to delete all of an array at once with @samp{delete @var{array}} @end itemize -@xref{Common Extensions}, for a list of common extensions +@DBXREF{Common Extensions} for a list of common extensions not permitted by the POSIX standard. The 2008 POSIX standard can be found online at @@ -35668,7 +35805,7 @@ has made his version available via his home page (@pxref{Other Versions}). This @value{SECTION} describes common extensions that -originally appeared in his version of @command{awk}. +originally appeared in his version of @command{awk}: @itemize @value{BULLET} @item @@ -35694,7 +35831,7 @@ or array elements through it. @end ignore @end itemize -@xref{Common Extensions}, for a full list of the extensions +@DBXREF{Common Extensions} for a full list of the extensions available in his @command{awk}. @node POSIX/GNU @@ -35750,7 +35887,7 @@ The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and @item The @file{/inet}, @file{/inet4}, and @samp{/inet6} special files for TCP/IP networking using @samp{|&} to specify which version of the -IP protocol to use. +IP protocol to use (@pxref{TCP/IP Networking}). @end itemize @@ -35798,7 +35935,7 @@ New keywords: @itemize @value{MINUS} @item -The @code{BEGINFILE} and @code{ENDFILE} special patterns. +The @code{BEGINFILE} and @code{ENDFILE} special patterns (@pxref{BEGINFILE/ENDFILE}). @item @@ -35835,7 +35972,7 @@ making translations easier @item The @code{split()} function's additional optional fourth -argument which is an array to hold the text of the field separators. +argument which is an array to hold the text of the field separators (@pxref{String Functions}). @end itemize @@ -36602,7 +36739,7 @@ load @command{awk} library files. @item The @option{-l} and @option{--load} options load compiled dynamic extensions. -@item +@item The @option{-M} and @option{--bignum} options enable MPFR. @item @@ -36641,7 +36778,7 @@ The dynamic extension interface was completely redone @cindex extensions, @command{mawk} The following table summarizes the common extensions supported by @command{gawk}, Brian Kernighan's @command{awk}, and @command{mawk}, -the three most widely-used freely available versions of @command{awk} +the three most widely used freely available versions of @command{awk} (@pxref{Other Versions}). @multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} {Now standard} @@ -36659,7 +36796,7 @@ the three most widely-used freely available versions of @command{awk} @item @code{func} keyword @tab X @tab @tab X @tab @item @code{BINMODE} variable @tab @tab X @tab X @tab @item @code{RS} as regexp @tab @tab X @tab X @tab -@item Time related functions @tab @tab X @tab X @tab +@item Time-related functions @tab @tab X @tab X @tab @end multitable @node Ranges and Locales @@ -36675,7 +36812,7 @@ the first character in the range and the last character in the range, inclusive. Ordering was based on the numeric value of each character in the machine's native character set. Thus, on ASCII-based systems, @samp{[a-z]} matched all the lowercase letters, and only the lowercase -letters, since the numeric values for the letters from @samp{a} through +letters, as the numeric values for the letters from @samp{a} through @samp{z} were contiguous. (On an EBCDIC system, the range @samp{[a-z]} includes additional, non-alphabetic characters as well.) @@ -36686,8 +36823,8 @@ that @samp{[A-Z]} was the ``correct'' way to match uppercase letters. And indeed, this was true.@footnote{And Life was good.} The 1992 POSIX standard introduced the idea of locales (@pxref{Locales}). -Since many locales include other letters besides the plain twenty-six -letters of the American English alphabet, the POSIX standard added +Because many locales include other letters besides the plain 26 +letters of the English alphabet, the POSIX standard added character classes (@pxref{Bracket Expressions}) as a way to match different kinds of characters besides the traditional ones in the ASCII character set. @@ -36704,7 +36841,7 @@ In other words, these locales sort characters in dictionary order, and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; instead it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. -This point needs to be emphasized: Much literature teaches that you should +This point needs to be emphasized: much literature teaches that you should use @samp{[a-z]} to match a lowercase character. But on systems with non-ASCII locales, this also matches all of the uppercase characters except @samp{A} or @samp{Z}! This was a continuous cause of confusion, even well @@ -36720,7 +36857,7 @@ $ @kbd{echo something1234abc | gawk-3.1.8 '@{ sub("[A-Z]*$", ""); print @}'} @end example @noindent -This output is unexpected, since the @samp{bc} at the end of +This output is unexpected, as the @samp{bc} at the end of @samp{something1234abc} should not normally match @samp{[A-Z]*}. This result is due to the locale setting (and thus you may not see it on your system). @@ -36742,7 +36879,7 @@ like ``why does @samp{[A-Z]} match lowercase letters?!?'' @cindex Berry, Karl This situation existed for close to 10 years, if not more, and the @command{gawk} maintainer grew weary of trying to explain that -@command{gawk} was being nicely standards-compliant, and that the issue +@command{gawk} was being nicely standards compliant, and that the issue was in the user's locale. During the development of @value{PVERSION} 4.0, he modified @command{gawk} to always treat ranges in the original, pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).@footnote{And @@ -36955,7 +37092,7 @@ Michael Benzinger contributed the initial code for @code{switch} statements. @cindex McPhee, Patrick Patrick T.J.@: McPhee contributed the code for dynamic loading in Windows32 environments. -(This is no longer supported) +(This is no longer supported.) @item @cindex Wallin, Anders @@ -36979,7 +37116,7 @@ into a byte-code interpreter, including the debugger. The addition of true arrays of arrays. @item -The additional modifications for support of arbitrary precision arithmetic. +The additional modifications for support of arbitrary-precision arithmetic. @item The initial text of @@ -37035,7 +37172,7 @@ helping David Trueman, and as the primary maintainer since around 1994. @itemize @value{BULLET} @item The @command{awk} language has evolved over time. The first release -was with V7 Unix circa 1978. In 1987 for System V Release 3.1, +was with V7 Unix circa 1978. In 1987, for System V Release 3.1, major additions, including user-defined functions, were made to the language. Additional changes were made for System V Release 4, in 1989. Since then, further minor changes happen under the auspices of the @@ -37077,8 +37214,8 @@ This appendix provides instructions for installing @command{gawk} on the various platforms that are supported by the developers. The primary developer supports GNU/Linux (and Unix), whereas the other ports are contributed. -@xref{Bugs}, -for the electronic mail addresses of the people who maintain +@DBXREF{Bugs} +for the email addresses of the people who maintain the respective ports. @menu @@ -37132,7 +37269,7 @@ wget http://ftp.gnu.org/gnu/gawk/gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz The GNU software archive is mirrored around the world. The up-to-date list of mirror sites is available from -@uref{http://www.gnu.org/order/ftp.html, the main FSF web site}. +@uref{http://www.gnu.org/order/ftp.html, the main FSF website}. Try to use one of the mirrors; they will be less busy, and you can usually find one closer to your site. @@ -37143,7 +37280,7 @@ different compression programs: @command{gzip}, @command{bzip2}, and @command{xz}. For simplicity, the rest of these instructions assume you are using the one compressed with the GNU Zip program, @code{gzip}. -Once you have the distribution (for example, +Once you have the distribution (e.g., @file{gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz}), use @code{gzip} to expand the file and then use @code{tar} to extract it. You can use the following @@ -37236,7 +37373,7 @@ as a list of things that the POSIX standard should describe but does not. @item doc/awkforai.txt Pointers to the original draft of a short article describing why @command{gawk} is a good language for -Artificial Intelligence (AI) programming. +artificial intelligence (AI) programming. @item doc/bc_notes A brief description of @command{gawk}'s ``byte code'' internals. @@ -37367,11 +37504,11 @@ Files needed for building @command{gawk} under MS-Windows @ifclear FOR_PRINT and OS/2 @end ifclear -(@pxref{PC Installation}, for details). +(@DBPXREF{PC Installation} for details). @item vms/* Files needed for building @command{gawk} under Vax/VMS and OpenVMS -(@pxref{VMS Installation}, for details). +(@DBPXREF{VMS Installation} for details). @item test/* A test suite for @@ -37383,7 +37520,7 @@ be confident of a successful port. @c ENDOFRANGE gawdis @node Unix Installation -@appendixsec Compiling and Installing @command{gawk} on Unix-like Systems +@appendixsec Compiling and Installing @command{gawk} on Unix-Like Systems Usually, you can compile and install @command{gawk} by typing only two commands. However, if you use an unusual system, you may need @@ -37397,7 +37534,7 @@ to configure @command{gawk} for your system yourself. @end menu @node Quick Installation -@appendixsubsec Compiling @command{gawk} for Unix-like Systems +@appendixsubsec Compiling @command{gawk} for Unix-Like Systems The normal installation steps should work on all modern commercial Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin @@ -37414,7 +37551,7 @@ described fully in @cite{Autoconf---Generating Automatic Configuration Scripts}, which can be found online at @uref{http://www.gnu.org/software/autoconf/manual/index.html, -the Free Software Foundation's web site}.) +the Free Software Foundation's website}.) @end ifnotinfo @ifinfo (The Autoconf software is described fully starting with @@ -37461,7 +37598,7 @@ run @samp{make check}. All of the tests should succeed. If these steps do not work, or if any of the tests fail, check the files in the @file{README_d} directory to see if you've found a known problem. If the failure is not described there, -please send in a bug report (@pxref{Bugs}). +send in a bug report (@pxref{Bugs}). Of course, once you've built @command{gawk}, it is likely that you will wish to install it. To do so, you need to run the command @samp{make @@ -37563,7 +37700,7 @@ function for deficient systems. @end table Use the command @samp{./configure --help} to see the full list of -options that @command{configure} supplies. +options supplied by @command{configure}. @node Configuration Philosophy @appendixsubsec The Configuration Process @@ -37597,19 +37734,19 @@ facts about your operating system. For example, there may not be an @cindex @code{custom.h} file It is possible for your C compiler to lie to @command{configure}. It may do so by not exiting with an error when a library function is not -available. To get around this, edit the file @file{custom.h}. +available. To get around this, edit the @file{custom.h} file. Use an @samp{#ifdef} that is appropriate for your system, and either @code{#define} any constants that @command{configure} should have defined but didn't, or @code{#undef} any constants that @command{configure} defined and -should not have. @file{custom.h} is automatically included by -@file{config.h}. +should not have. The @file{custom.h} file is automatically included by +the @file{config.h} file. It is also possible that the @command{configure} program generated by Autoconf will not work on your system in some other fashion. -If you do have a problem, the file @file{configure.ac} is the input for +If you do have a problem, the @file{configure.ac} file is the input for Autoconf. You may be able to change this file and generate a new version of @command{configure} that works on your system -(@pxref{Bugs}, +(@DBPXREF{Bugs} for information on how to report problems in configuring @command{gawk}). The same mechanism may be used to send in updates to @file{configure.ac} and/or @file{custom.h}. @@ -37649,7 +37786,7 @@ The limitations of MS-DOS (and MS-DOS shells under the other operating systems) has meant that various ``DOS extenders'' are often used with programs such as @command{gawk}. The varying capabilities of Microsoft Windows 3.1 and Windows32 can add to the confusion. For an overview -of the considerations, please refer to @file{README_d/README.pc} in +of the considerations, refer to @file{README_d/README.pc} in the distribution. @menu @@ -37812,7 +37949,7 @@ Ancient OS/2 ports of GNU @command{make} are not able to handle the Makefiles of this package. If you encounter any problems with @command{make}, try GNU Make 3.79.1 or later versions. You should find the latest version on -@uref{ftp://hobbes.nmsu.edu/pub/os2/}.@footnote{As of May, 2014, +@uref{ftp://hobbes.nmsu.edu/pub/os2/}.@footnote{As of November 2014, this site is still there, but the author could not find a package for GNU Make.} @end quotation @@ -38022,7 +38159,7 @@ need to use the @code{BINMODE} variable. This can cause problems with other Unix-like components that have been ported to MS-Windows that expect @command{gawk} to do automatic -translation of @code{"\r\n"}, since it won't. +translation of @code{"\r\n"}, because it won't. @node VMS Installation @appendixsubsec Compiling and Installing @command{gawk} on Vax/VMS and OpenVMS @@ -38086,14 +38223,14 @@ The most recent builds used HP C V7.3 on Alpha VMS 8.3 and both Alpha and IA64 VMS 8.4 used HP C 7.3.@footnote{The IA64 architecture is also known as ``Itanium.''} -@xref{VMS GNV}, for information on building +@DBXREF{VMS GNV} for information on building @command{gawk} as a PCSI kit that is compatible with the GNV product. @node VMS Dynamic Extensions @appendixsubsubsec Compiling @command{gawk} Dynamic Extensions on VMS The extensions that have been ported to VMS can be built using one of -the following commands. +the following commands: @example $ @kbd{MMS/DESCRIPTION=[.vms]descrip.mms extensions} @@ -38110,7 +38247,7 @@ $ @kbd{MMK/DESCRIPTION=[.vms]descrip.mms extensions} or a logical name to find the dynamic extensions. Dynamic extensions need to be compiled with the same compiler options for -floating point, pointer size, and symbol name handling as were used +floating-point, pointer size, and symbol name handling as were used to compile @command{gawk} itself. Alpha and Itanium should use IEEE floating point. The pointer size is 32 bits, and the symbol name handling should be exact case with CRC shortening for @@ -38240,7 +38377,7 @@ Note that uppercase and mixed-case text must be quoted. The VMS port of @command{gawk} includes a @code{DCL}-style interface in addition to the original shell-style interface (see the help entry for details). One side effect of dual command-line parsing is that if there is only a -single parameter (as in the quoted string program above), the command +single parameter (as in the quoted string program), the command becomes ambiguous. To work around this, the normally optional @option{--} flag is required to force Unix-style parsing rather than @code{DCL} parsing. If any other dash-type options (or multiple parameters such as @value{DF}s to @@ -38360,10 +38497,10 @@ recommend compiling and using the current version. @node Bugs @appendixsec Reporting Problems and Bugs -@cindex archeologists +@cindex archaeologists @quotation -@i{There is nothing more dangerous than a bored archeologist.} -@author The Hitchhiker's Guide to the Galaxy +@i{There is nothing more dangerous than a bored archaeologist.} +@author Douglas Adams, @cite{The Hitchhiker's Guide to the Galaxy} @end quotation @c the radio show, not the book. :-) @@ -38372,10 +38509,10 @@ recommend compiling and using the current version. @c STARTOFRANGE tblgawb @cindex troubleshooting, @command{gawk}, bug reports If you have problems with @command{gawk} or think that you have found a bug, -please report it to the developers; we cannot promise to do anything +report it to the developers; we cannot promise to do anything but we might well want to fix it. -Before reporting a bug, please make sure you have really found a genuine bug. +Before reporting a bug, make sure you have really found a genuine bug. Carefully reread the documentation and see if it says you can do what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation! @@ -38388,7 +38525,7 @@ the compiler you used to compile @command{gawk}, and the exact results @command{gawk} gave you. Also say what you expected to occur; this helps us decide whether the problem is really in the documentation. -Please include the version number of @command{gawk} you are using. +Make sure to include the version number of @command{gawk} you are using. You can get this information with the command @samp{gawk --version}. @cindex @code{bug-gawk@@gnu.org} bug reporting address @@ -38400,7 +38537,7 @@ Once you have a precise problem description, send email to The @command{gawk} maintainers subscribe to this address and thus they will receive your bug report. Although you can send mail to the maintainers directly, -the bug reporting address is preferred since the +the bug reporting address is preferred because the email list is archived at the GNU Project. @emph{All email must be in English. This is the only language understood in common by all the maintainers.} @@ -38409,19 +38546,19 @@ understood in common by all the maintainers.} @quotation CAUTION Do @emph{not} try to report bugs in @command{gawk} by posting to the Usenet/Internet newsgroup @code{comp.lang.awk}. -While the @command{gawk} developers do occasionally read this newsgroup, -there is no guarantee that we will see your posting. The steps described -above are the only official recognized way for reporting bugs. +The @command{gawk} developers do occasionally read this newsgroup, +but there is no guarantee that we will see your posting. The steps described +here are the only officially recognized way for reporting bugs. Really. @end quotation @quotation NOTE Many distributions of GNU/Linux and the various BSD-based operating systems have their own bug reporting systems. If you report a bug using your distribution's -bug reporting system, @emph{please} also send a copy to +bug reporting system, you should also send a copy to @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. -This is for two reasons. First, while some distributions forward +This is for two reasons. First, although some distributions forward bug reports ``upstream'' to the GNU mailing list, many don't, so there is a good chance that the @command{gawk} maintainers won't even see the bug report! Second, mail to the GNU list is archived, and having everything at the GNU project @@ -38432,8 +38569,8 @@ Non-bug suggestions are always welcome as well. If you have questions about things that are unclear in the documentation or are just obscure features, ask on the bug list; we will try to help you out if we can. -If you find bugs in one of the non-Unix ports of @command{gawk}, please -send an electronic mail message to the bug list, with a copy to the +If you find bugs in one of the non-Unix ports of @command{gawk}, +send an email to the bug list, with a copy to the person who maintains that port. They are named in the following list, as well as in the @file{README} file in the @command{gawk} distribution. Information in the @file{README} file should be considered authoritative @@ -38464,9 +38601,8 @@ The people maintaining the various @command{gawk} ports are: @item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. @end multitable -If your bug is also reproducible under Unix, please send a copy of your -report to the @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org} email -list as well. +If your bug is also reproducible under Unix, send a copy of your +report to the @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org} email list as well. @c ENDOFRANGE dbugg @c ENDOFRANGE tblgawb @@ -38509,7 +38645,7 @@ This @value{SECTION} briefly describes where to get them: Brian Kernighan, one of the original designers of Unix @command{awk}, has made his implementation of @command{awk} freely available. -You can retrieve this version via the World Wide Web from +You can retrieve this version via @uref{http://www.cs.princeton.edu/~bwk, his home page}. It is available in several archive formats: @@ -38532,7 +38668,7 @@ git clone git://github.com/onetrueawk/awk bwkawk @end example @noindent -The above command creates a copy of the @uref{http://www.git-scm.com, Git} +This command creates a copy of the @uref{http://www.git-scm.com, Git} repository in a directory named @file{bwkawk}. If you leave that argument off the @command{git} command line, the repository copy is created in a directory named @file{awk}. @@ -38540,9 +38676,13 @@ directory named @file{awk}. This version requires an ISO C (1990 standard) compiler; the C compiler from GCC (the GNU Compiler Collection) works quite nicely. -@xref{Common Extensions}, +@DBXREF{Common Extensions} for a list of extensions in this @command{awk} that are not in POSIX @command{awk}. +As a side note, Dan Bornstein has created a Git repository tracking +all the versions of BWK @command{awk} that he could find. It's +available at @uref{git://github.com/danfuzz/one-true-awk}. + @cindex Brennan, Michael @cindex @command{mawk} utility @cindex source code, @command{mawk} @@ -38572,7 +38712,7 @@ Once you have it, is similar to @command{gawk}'s (@pxref{Unix Installation}). -@xref{Common Extensions}, +@DBXREF{Common Extensions} for a list of extensions in @command{mawk} that are not in POSIX @command{awk}. @cindex Sumner, Andrew @@ -38634,8 +38774,8 @@ has not been done, at least to our knowledge. @cindex Illumos @cindex Illumos, POSIX-compliant @command{awk} @cindex source code, Illumos @command{awk} -The source code used to be available from the OpenSolaris web site. -However, that project was ended and the web site shut down. Fortunately, the +The source code used to be available from the OpenSolaris website. +However, that project was ended and the website shut down. Fortunately, the @uref{http://wiki.illumos.org/display/illumos/illumos+Home, Illumos project} makes this implementation available. You can view the files one at a time from @uref{https://github.com/joyent/illumos-joyent/blob/master/usr/src/cmd/awk_xpg4}. @@ -38654,7 +38794,7 @@ from POSIX @command{awk}. More information is available on the @cindex libmawk @cindex source code, libmawk This is an embeddable @command{awk} interpreter derived from -@command{mawk}. For more information see +@command{mawk}. For more information, see @uref{http://repo.hu/projects/libmawk/}. @item @code{pawk} @@ -38668,7 +38808,7 @@ modified version of BWK @command{awk}, described earlier.) @item @w{QSE Awk} @cindex QSE Awk @cindex source code, QSE Awk -This is an embeddable @command{awk} interpreter. For more information +This is an embeddable @command{awk} interpreter. For more information, see @uref{http://code.google.com/p/qse/} and @uref{http://awk.info/?tools/qse}. @item @command{QTawk} @@ -38683,9 +38823,10 @@ including the manual and a download link. The project may also be frozen; no new code changes have been made since approximately 2008. -@item Other Versions -See also the @uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations, -Wikipedia article}, for information on additional versions. +@item Other versions +See also the ``Versions and implementations'' section of the +@uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations, +Wikipedia article} for information on additional versions. @end table @c ENDOFRANGE awkim @@ -38887,7 +39028,7 @@ This document describes how GNU software should be written. If you haven't read it, please do so, preferably @emph{before} starting to modify @command{gawk}. (The @cite{GNU Coding Standards} are available from the GNU Project's -@uref{http://www.gnu.org/prep/standards_toc.html, web site}. +@uref{http://www.gnu.org/prep/standards_toc.html, website}. Texinfo, Info, and DVI versions are also available.) @cindex @command{gawk}, coding style in @@ -39972,6 +40113,13 @@ pattern matches an input record, @command{awk} executes the rule's action. Actions are always enclosed in braces. (@xref{Action Overview}.) +@cindex Ada programming language +@cindex programming languages, Ada +@item Ada +A programming language originally defined by the U.S.@: Department of +Defense for embedded programming. It was designed to enforce good +Software Engineering practices. + @cindex Spencer, Henry @cindex @command{sed} utility @cindex amazing @command{awk} assembler (@command{aaa}) @@ -39983,13 +40131,6 @@ microcomputers. It is a good example of a program that would have been better written in another language. You can get it from @uref{http://awk.info/?awk100/aaa}. -@cindex Ada programming language -@cindex programming languages, Ada -@item Ada -A programming language originally defined by the U.S.@: Department of -Defense for embedded programming. It was designed to enforce good -Software Engineering practices. - @cindex amazingly workable formatter (@command{awf}) @cindex @command{awf} (amazingly workable formatter) program @item Amazingly Workable Formatter (@command{awf}) @@ -40753,7 +40894,7 @@ record or a string. @end docbook @c This file is intended to be included within another document, -@c hence no sectioning command or @node. +@c hence no sectioning command or @node. @display Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} @@ -40975,7 +41116,7 @@ terms of section 4, provided that you also meet all of these conditions: @enumerate a -@item +@item The work must carry prominent notices stating that you modified it, and giving a relevant date. @@ -41425,7 +41566,7 @@ state the exclusion of warranty; and each file should have at least the ``copyright'' line and a pointer to where the full notice is found. @smallexample -@var{one line to give the program's name and a brief idea of what it does.} +@var{one line to give the program's name and a brief idea of what it does.} Copyright (C) @var{year} @var{name of author} This program is free software: you can redistribute it and/or modify @@ -41448,7 +41589,7 @@ If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: @smallexample -@var{program} Copyright (C) @var{year} @var{name of author} +@var{program} Copyright (C) @var{year} @var{name of author} This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. This is free software, and you are welcome to redistribute it under certain conditions; type @samp{show c} for details. diff --git a/doc/gawktexi.in b/doc/gawktexi.in index c06bca82..f330e8e0 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -51,7 +51,7 @@ @set PATCHLEVEL 2 @ifset FOR_PRINT -@set TITLE Effective AWK Programming +@set TITLE Effective Awk Programming @end ifset @ifclear FOR_PRINT @set TITLE GAWK: Effective AWK Programming @@ -170,12 +170,24 @@ @macro DBREF{text} @ref{\text\} @end macro +@macro DBXREF{text} +@xref{\text\} +@end macro +@macro DBPXREF{text} +@pxref{\text\} +@end macro @end ifdocbook @ifnotdocbook @macro DBREF{text} @ref{\text\}, @end macro +@macro DBXREF{text} +@xref{\text\}, +@end macro +@macro DBPXREF{text} +@pxref{\text\}, +@end macro @end ifnotdocbook @ifclear FOR_PRINT @@ -310,7 +322,7 @@ A copy of the license is included in the section entitled A copy of the license may be found on the Internet at @uref{http://www.gnu.org/software/gawk/manual/html_node/GNU-Free-Documentation-License.html, -the GNU Project's web site}. +the GNU Project's website}. @end ifset @enumerate a @@ -378,10 +390,10 @@ ISBN 1-882114-28-0 @* @sp 9 @center @i{To my parents, for their love, and for the wonderful example they set for me.} @sp 1 -@center @i{To my wife Miriam, for making me complete. +@center @i{To my wife, Miriam, for making me complete. Thank you for building your life together with me.} @sp 1 -@center @i{To our children Chana, Rivka, Nachum and Malka, for enrichening our lives in innumerable ways.} +@center @i{To our children, Chana, Rivka, Nachum, and Malka, for enrichening our lives in innumerable ways.} @sp 1 @w{ } @page @@ -1071,7 +1083,7 @@ for enrichening our lives in innumerable ways. <!-- can't put mawk into command tags. sigh. --> <affiliation><jobtitle>Author of mawk</jobtitle></affiliation> </author> - <date>March, 2001</date> + <date>March 2001</date> </prefaceinfo> @end docbook @@ -1083,21 +1095,23 @@ The circumstances started a couple of years earlier. I was working at a new job and noticed an unplugged Unix computer sitting in the corner. No one knew how to use it, and neither did I. However, -a couple of days later it was running, and +a couple of days later, it was running, and I was @code{root} and the one-and-only user. That day, I began the transition from statistician to Unix programmer. On one of many trips to the library or bookstore in search of -books on Unix, I found the gray AWK book, a.k.a.@: Aho, Kernighan and -Weinberger, @cite{The AWK Programming Language}, Addison-Wesley, -1988. AWK's simple programming paradigm---find a pattern in the +books on Unix, I found the gray AWK book, a.k.a.@: +Alfred V.@: Aho, Brian W.@: Kernighan, and +Peter J.@: Weinberger's @cite{The AWK Programming Language} (Addison-Wesley, +1988). @command{awk}'s simple programming paradigm---find a pattern in the input and then perform an action---often reduced complex or tedious data manipulations to a few lines of code. I was excited to try my hand at programming in AWK. Alas, the @command{awk} on my computer was a limited version of the -language described in the AWK book. I discovered that my computer -had ``old @command{awk}'' and the AWK book described ``new @command{awk}.'' +language described in the gray book. I discovered that my computer +had ``old @command{awk}'' and the book described +``new @command{awk}.'' I learned that this was typical; the old version refused to step aside or relinquish its name. If a system had a new @command{awk}, it was invariably called @command{nawk}, and few systems had it. @@ -1115,7 +1129,7 @@ My Unix system started out unplugged from the wall; it certainly was not plugged into a network. So, oblivious to the existence of @command{gawk} and the Unix community in general, and desiring a new @command{awk}, I wrote my own, called @command{mawk}. -Before I was finished I knew about @command{gawk}, +Before I was finished, I knew about @command{gawk}, but it was too late to stop, so I eventually posted to a @code{comp.sources} newsgroup. @@ -1124,7 +1138,7 @@ from Arnold introducing himself. He suggested we share design and algorithms and attached a draft of the POSIX standard so that I could update @command{mawk} to support language extensions added -after publication of the AWK book. +after publication of @cite{The AWK Programming Language}. Frankly, if our roles had been reversed, I would not have been so open and we probably would @@ -1143,7 +1157,7 @@ standard. On the other hand, the novice AWK programmer can study a wealth of practical programs that emphasize the power of AWK's basic idioms: -data driven control-flow, pattern matching with regular expressions, +data-driven control flow, pattern matching with regular expressions, and associative arrays. Those looking for something new can try out @command{gawk}'s interface to network protocols via special @file{/inet} files. @@ -1204,7 +1218,7 @@ AWK or want to learn how, then read this book. @display Michael Brennan Author of @command{mawk} -March, 2001 +March 2001 @end display @end ifnotdocbook @@ -1222,7 +1236,7 @@ March, 2001 <!-- can't put mawk into command tags. sigh. --> <affiliation><jobtitle>Author of mawk</jobtitle></affiliation> </author> - <date>October, 2014</date> + <date>October 2014</date> </prefaceinfo> @end docbook @@ -1256,7 +1270,7 @@ details, and as expected, many examples to help you learn the ins and outs. @display Michael Brennan Author of @command{mawk} -October, 2014 +October 2014 @end display @end ifnotdocbook @@ -1276,9 +1290,9 @@ October, 2014 <firstname>Arnold</firstname> <surname>Robbins</surname> <affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation> - <affiliation><jobtitle>ISRAEL</jobtitle></affiliation> + <affiliation><jobtitle>Israel</jobtitle></affiliation> </author> - <date>December, 2014</date> + <date>December 2014</date> </prefaceinfo> @end docbook @@ -1290,7 +1304,7 @@ The @command{awk} utility interprets a special-purpose programming language that makes it easy to handle simple data-reformatting jobs. The GNU implementation of @command{awk} is called @command{gawk}; if you -invoke it with the proper options or environment variables +invoke it with the proper options or environment variables, it is fully compatible with the POSIX@footnote{The 2008 POSIX standard is accessible online at @w{@url{http://www.opengroup.org/onlinepubs/9699919799/}.}} @@ -1397,7 +1411,7 @@ has been removed.} @unnumberedsec History of @command{awk} and @command{gawk} @cindex recipe for a programming language @cindex programming language, recipe for -@sidebar Recipe For A Programming Language +@sidebar Recipe for a Programming Language @multitable {2 parts} {1 part @code{egrep}} {1 part @code{snobol}} @item @tab 1 part @code{egrep} @tab 1 part @code{snobol} @@ -1416,7 +1430,7 @@ more parts C. Document very well and release. @cindex Kernighan, Brian @cindex @command{awk}, history of The name @command{awk} comes from the initials of its designers: Alfred V.@: -Aho, Peter J.@: Weinberger and Brian W.@: Kernighan. The original version of +Aho, Peter J.@: Weinberger, and Brian W.@: Kernighan. The original version of @command{awk} was written in 1977 at AT&T Bell Laboratories. In 1985, a new version made the programming language more powerful, introducing user-defined functions, multiple input @@ -1442,7 +1456,7 @@ Circa 1994, I became the primary maintainer. Current development focuses on bug fixes, performance improvements, standards compliance and, occasionally, new features. -In May of 1997, J@"urgen Kahrs felt the need for network access +In May 1997, J@"urgen Kahrs felt the need for network access from @command{awk}, and with a little help from me, set about adding features to do this for @command{gawk}. At that time, he also wrote the bulk of @@ -1455,7 +1469,7 @@ John Haque rewrote the @command{gawk} internals, in the process providing an @command{awk}-level debugger. This version became available as @command{gawk} @value{PVERSION} 4.0, in 2011. -@xref{Contributors}, +@DBXREF{Contributors} for a full list of those who made important contributions to @command{gawk}. @node Names @@ -1465,7 +1479,7 @@ for a full list of those who made important contributions to @command{gawk}. The @command{awk} language has evolved over the years. Full details are provided in @ref{Language History}. The language described in this @value{DOCUMENT} -is often referred to as ``new @command{awk}''. +is often referred to as ``new @command{awk}.'' By analogy, the original version of @command{awk} is referred to as ``old @command{awk}.'' @@ -1544,12 +1558,15 @@ Most of the time, the examples use complete @command{awk} programs. Some of the more advanced sections show only the part of the @command{awk} program that illustrates the concept being described. -While this @value{DOCUMENT} is aimed principally at people who have not been +Although this @value{DOCUMENT} is aimed principally at people who have not been exposed to @command{awk}, there is a lot of information here that even the @command{awk} expert should find useful. In particular, the description of POSIX @command{awk} and the example programs in -@ref{Library Functions}, and in +@ref{Library Functions}, and +@ifnotdocbook +in +@end ifnotdocbook @ref{Sample Programs}, should be of interest. @@ -1557,22 +1574,30 @@ This @value{DOCUMENT} is split into several parts, as follows: @c FULLXREF ON +@itemize @value{BULLET} +@item Part I describes the @command{awk} language and @command{gawk} program in detail. It starts with the basics, and continues through all of the features of @command{awk}. It contains the following chapters: +@c nested +@itemize @value{MINUS} +@item @ref{Getting Started}, provides the essentials you need to know to begin using @command{awk}. +@item @ref{Invoking Gawk}, describes how to run @command{gawk}, the meaning of its command-line options, and how it finds @command{awk} program source files. +@item @ref{Regexp}, introduces regular expressions in general, and in particular the flavors supported by POSIX @command{awk} and @command{gawk}. +@item @ref{Reading Files}, describes how @command{awk} reads your data. It introduces the concepts of records and fields, as well @@ -1580,46 +1605,62 @@ as the @code{getline} command. I/O redirection is first described here. Network I/O is also briefly introduced here. +@item @ref{Printing}, describes how @command{awk} programs can produce output with @code{print} and @code{printf}. +@item @ref{Expressions}, describes expressions, which are the basic building blocks for getting most things done in a program. +@item @ref{Patterns and Actions}, describes how to write patterns for matching records, actions for doing something when a record is matched, and the predefined variables @command{awk} and @command{gawk} use. +@item @ref{Arrays}, covers @command{awk}'s one-and-only data structure: associative arrays. Deleting array elements and whole arrays is also described, as well as sorting arrays in @command{gawk}. It also describes how @command{gawk} provides arrays of arrays. +@item @ref{Functions}, describes the built-in functions @command{awk} and @command{gawk} provide, as well as how to define your own functions. It also discusses how @command{gawk} lets you call functions indirectly. +@end itemize +@item Part II shows how to use @command{awk} and @command{gawk} for problem solving. There is lots of code here for you to read and learn from. It contains the following chapters: +@c nested +@itemize @value{MINUS} +@item @ref{Library Functions}, which provides a number of functions meant to be used from main @command{awk} programs. +@item @ref{Sample Programs}, which provides many sample @command{awk} programs. +@end itemize Reading these two chapters allows you to see @command{awk} solving real problems. +@item Part III focuses on features specific to @command{gawk}. It contains the following chapters: +@c nested +@itemize @value{MINUS} +@item @ref{Advanced Features}, describes a number of advanced features. Of particular note @@ -1628,18 +1669,24 @@ have two-way communications with another process, perform TCP/IP networking, and profile your @command{awk} programs. +@item @ref{Internationalization}, describes special features for translating program messages into different languages at runtime. +@item @ref{Debugger}, describes the @command{gawk} debugger. +@item @ref{Arbitrary Precision Arithmetic}, describes advanced arithmetic facilities. +@item @ref{Dynamic Extensions}, describes how to add new variables and functions to @command{gawk} by writing extensions in C or C++. +@end itemize +@item @ifclear FOR_PRINT Part IV provides the appendices, the Glossary, and two licenses that cover the @command{gawk} source code and this @value{DOCUMENT}, respectively. @@ -1650,11 +1697,14 @@ Part IV provides the following appendices, including the GNU General Public License: @end ifset +@itemize @value{MINUS} +@item @ref{Language History}, describes how the @command{awk} language has evolved since its first release to present. It also describes how @command{gawk} has acquired features over time. +@item @ref{Installation}, describes how to get @command{gawk}, how to compile it on POSIX-compatible systems, @@ -1662,17 +1712,22 @@ and how to compile and use it on different non-POSIX systems. It also describes how to report bugs in @command{gawk} and where to get other freely available @command{awk} implementations. +@end itemize @ifset FOR_PRINT - +@itemize @value{MINUS} +@item @ref{Copying}, presents the license that covers the @command{gawk} source code. +@end itemize The version of this @value{DOCUMENT} distributed with @command{gawk} contains additional appendices and other end material. To save space, we have omitted them from the printed edition. You may find them online, as follows: +@itemize @value{BULLET} +@item @uref{http://www.gnu.org/software/gawk/manual/html_node/Notes.html, The appendix on implementation notes} describes how to disable @command{gawk}'s extensions, how to contribute @@ -1680,44 +1735,54 @@ new code to @command{gawk}, where to find information on some possible future directions for @command{gawk} development, and the design decisions behind the extension API. +@item @uref{http://www.gnu.org/software/gawk/manual/html_node/Basic-Concepts.html, The appendix on basic concepts} provides some very cursory background material for those who are completely unfamiliar with computer programming. +@item @uref{http://www.gnu.org/software/gawk/manual/html_node/Glossary.html, The Glossary} -defines most, if not all, the significant terms used +defines most, if not all of, the significant terms used throughout the @value{DOCUMENT}. If you find terms that you aren't familiar with, try looking them up here. +@item @uref{http://www.gnu.org/software/gawk/manual/html_node/GNU-Free-Documentation-License.html, The GNU FDL} is the license that covers this @value{DOCUMENT}. +@end itemize Some of the chapters have exercise sections; these have also been omitted from the print edition but are available online. @end ifset @ifclear FOR_PRINT +@itemize @value{MINUS} +@item @ref{Notes}, describes how to disable @command{gawk}'s extensions, as well as how to contribute new code to @command{gawk}, and some possible future directions for @command{gawk} development. +@item @ref{Basic Concepts}, provides some very cursory background material for those who are completely unfamiliar with computer programming. -The @ref{Glossary}, defines most, if not all, the significant terms used +The @ref{Glossary}, defines most, if not all of, the significant terms used throughout the @value{DOCUMENT}. If you find terms that you aren't familiar with, try looking them up here. +@item @ref{Copying}, and @ref{GNU Free Documentation License}, present the licenses that cover the @command{gawk} source code and this @value{DOCUMENT}, respectively. +@end itemize @end ifclear +@end itemize @c FULLXREF OFF @@ -1780,7 +1845,7 @@ pressing the @kbd{d} key and finally releasing both keys. For the sake of brevity, throughout this @value{DOCUMENT}, we refer to Brian Kernighan's version of @command{awk} as ``BWK @command{awk}.'' -(@xref{Other Versions}, for information on his and other versions.) +(@DBXREF{Other Versions} for information on his and other versions.) @ifset FOR_PRINT @quotation NOTE @@ -1796,7 +1861,7 @@ Cautionary or warning notes look like this. @unnumberedsubsec Dark Corners @cindex Kernighan, Brian @quotation -@i{Dark corners are basically fractal --- no matter how much +@i{Dark corners are basically fractal---no matter how much you illuminate, there's always a smaller but darker one.} @author Brian Kernighan @end quotation @@ -1866,7 +1931,7 @@ The GPL applies to the C language source code for @command{gawk}. To find out more about the FSF and the GNU Project online, see @uref{http://www.gnu.org, the GNU Project's home page}. This @value{DOCUMENT} may also be read from -@uref{http://www.gnu.org/software/gawk/manual/, their web site}. +@uref{http://www.gnu.org/software/gawk/manual/, GNU's website}. @ifclear FOR_PRINT A shell, an editor (Emacs), highly portable optimizing C, C++, and @@ -1903,10 +1968,10 @@ License in @ref{GNU Free Documentation License}.) @cindex Close, Diane The @value{DOCUMENT} itself has gone through multiple previous editions. Paul Rubin wrote the very first draft of @cite{The GAWK Manual}; -it was around 40 pages in size. +it was around 40 pages long. Diane Close and Richard Stallman improved it, yielding a version that was -around 90 pages long and barely described the original, ``old'' +around 90 pages and barely described the original, ``old'' version of @command{awk}. I started working with that version in the fall of 1988. @@ -1939,17 +2004,17 @@ and the major new additions are @ref{Arbitrary Precision Arithmetic}, and @ref{Dynamic Extensions}. This @value{DOCUMENT} will undoubtedly continue to evolve. If you -find an error in this @value{DOCUMENT}, please report it! @xref{Bugs}, +find an error in this @value{DOCUMENT}, please report it! @DBXREF{Bugs} for information on submitting problem reports electronically. @ifset FOR_PRINT @c fakenode --- for prepinfo @unnumberedsec How to Stay Current -It may be you have a version of @command{gawk} which is newer than the +You may have a newer version of @command{gawk} than the one described here. To find out what has changed, you should first look at the @file{NEWS} file in the @command{gawk} -distribution, which provides a high level summary of what changed in +distribution, which provides a high-level summary of what changed in each release. You can then look at the @uref{http://www.gnu.org/software/gawk/manual/, @@ -1974,13 +2039,13 @@ contributed code: the archive did not grow and the domain went unused for several years. Late in 2008, a volunteer took on the task of setting up -an @command{awk}-related web site---@uref{http://awk.info}---and did a very +an @command{awk}-related website---@uref{http://awk.info}---and did a very nice job. If you have written an interesting @command{awk} program, or have written a @command{gawk} extension that you would like to share with the rest of the world, please see @uref{http://awk.info/?contribute} for how to -contribute it to the web site. +contribute it to the website. @ignore As of this writing, this website is in search of a maintainer; please @@ -2127,15 +2192,16 @@ portable program it is today. It has been and continues to be a pleasure working with this team of fine people. Notable code and documentation contributions were made by -a number of people. @xref{Contributors}, for the full list. +a number of people. @DBXREF{Contributors} for the full list. @ifset FOR_PRINT @cindex Oram, Andy Thanks to Andy Oram, of O'Reilly Media, for initiating the fourth edition and for his support during the work. +Thanks to Jasmine Kwityn for her copy-editing work. @end ifset -Thanks to Michael Brennan for the Foreword. +Thanks to Michael Brennan for the Forewords. @cindex Duman, Patrice @cindex Berry, Karl @@ -2146,7 +2212,7 @@ the Texinfo markup language sane. @cindex Kernighan, Brian @cindex Brennan, Michael @cindex Day, Robert P.J.@: -Robert P.J.@: Day, Michael Brennan and Brian Kernighan kindly acted as +Robert P.J.@: Day, Michael Brennan, and Brian Kernighan kindly acted as reviewers for the 2015 edition of this @value{DOCUMENT}. Their feedback helped improve the final work. @@ -2158,7 +2224,7 @@ or its documentation without his help. Brian is in a class by himself as a programmer and technical author. I have to thank him (yet again) for his ongoing friendship -and the role model he has been for me for close to 30 years! +and for being a role model to me for close to 30 years! Having him as a reviewer is an exciting privilege. It has also been extremely humbling@enddots{} @@ -2179,8 +2245,8 @@ take advantage of those opportunities. @noindent Arnold Robbins @* Nof Ayalon @* -ISRAEL @* -December, 2014 +Israel @* +December 2014 @end iftex @ifnotinfo @@ -2197,31 +2263,31 @@ following chapters: @itemize @value{BULLET} @item -@ref{Getting Started}. +@ref{Getting Started} @item -@ref{Invoking Gawk}. +@ref{Invoking Gawk} @item -@ref{Regexp}. +@ref{Regexp} @item -@ref{Reading Files}. +@ref{Reading Files} @item -@ref{Printing}. +@ref{Printing} @item -@ref{Expressions}. +@ref{Expressions} @item -@ref{Patterns and Actions}. +@ref{Patterns and Actions} @item -@ref{Arrays}. +@ref{Arrays} @item -@ref{Functions}. +@ref{Functions} @end itemize @end ifdocbook @@ -2236,17 +2302,17 @@ following chapters: The basic function of @command{awk} is to search files for lines (or other units of text) that contain certain patterns. When a line matches one of the patterns, @command{awk} performs specified actions on that line. -@command{awk} keeps processing input lines in this way until it reaches +@command{awk} continues to process input lines in this way until it reaches the end of the input files. @cindex @command{awk}, uses for @cindex programming languages@comma{} data-driven vs.@: procedural @cindex @command{awk} programs Programs in @command{awk} are different from programs in most other languages, -because @command{awk} programs are @dfn{data-driven}; that is, you describe -the data you want to work with and then what to do when you find it. +because @command{awk} programs are @dfn{data driven} (i.e., you describe +the data you want to work with and then what to do when you find it). Most other languages are @dfn{procedural}; you have to describe, in great -detail, every step the program is to take. When working with procedural +detail, every step the program should take. When working with procedural languages, it is usually much harder to clearly describe the data your program will process. For this reason, @command{awk} programs are often refreshingly easy to @@ -2256,9 +2322,9 @@ read and write. @cindex rule, definition of When you run @command{awk}, you specify an @command{awk} @dfn{program} that tells @command{awk} what to do. The program consists of a series of -@dfn{rules}. (It may also contain @dfn{function definitions}, -an advanced feature that we will ignore for now. -@xref{User-defined}.) Each rule specifies one +@dfn{rules} (it may also contain @dfn{function definitions}, +an advanced feature that we will ignore for now; +@pxref{User-defined}). Each rule specifies one pattern to search for and one action to perform upon finding the pattern. @@ -2358,10 +2424,11 @@ programs from shell scripts, because it avoids the need for a separate file for the @command{awk} program. A self-contained shell script is more reliable because there are no other files to misplace. +Later in this chapter, +@ifdocbook +the section +@end ifdocbook @ref{Very Simple}, -@ifnotinfo -later in this @value{CHAPTER}, -@end ifnotinfo presents several short, self-contained programs. @@ -2420,7 +2487,7 @@ startup file. This next simple @command{awk} program emulates the @command{cat} utility; it copies whatever you type on the -keyboard to its standard output (why this works is explained shortly). +keyboard to its standard output (why this works is explained shortly): @example $ @kbd{awk '@{ print @}'} @@ -2505,7 +2572,7 @@ affect the execution of the @command{awk} program but it does make Once you have learned @command{awk}, you may want to write self-contained @command{awk} scripts, using the @samp{#!} script mechanism. You can do this on many systems.@footnote{The @samp{#!} mechanism works on -GNU/Linux systems, BSD-based systems and commercial Unix systems.} +GNU/Linux systems, BSD-based systems, and commercial Unix systems.} For example, you could update the file @file{advice} to look like this: @example @@ -2544,7 +2611,7 @@ according to the instructions in your program. (This is different from a @dfn{compiled} language such as C, where your program is first compiled into machine code that is executed directly by your system's processor.) The @command{awk} utility is thus termed an @dfn{interpreter}. -Many modern languages are interperted. +Many modern languages are interpreted. The line beginning with @samp{#!} lists the full @value{FN} of an interpreter to run and a single optional initial command-line argument @@ -2590,14 +2657,14 @@ can explain what the program does and how it works. Nearly all programming languages have provisions for comments, as programs are typically hard to understand without them. -In the @command{awk} language, a comment starts with the sharp sign +In the @command{awk} language, a comment starts with the number sign character (@samp{#}) and continues to the end of the line. The @samp{#} does not have to be the first character on the line. The -@command{awk} language ignores the rest of a line following a sharp sign. +@command{awk} language ignores the rest of a line following a number sign. For example, we could have put the following into @file{advice}: @example -# This program prints a nice friendly message. It helps +# This program prints a nice, friendly message. It helps # keep novice users from being afraid of the computer. BEGIN @{ print "Don't Panic!" @} @end example @@ -2613,7 +2680,8 @@ when reading it at a later time. @quotation CAUTION As mentioned in @ref{One-shot}, -you can enclose small to medium programs in single quotes, in order to keep +you can enclose short to medium-sized programs in single quotes, +in order to keep your shell scripts self-contained. When doing so, @emph{don't} put an apostrophe (i.e., a single quote) into a comment (or anywhere else in your program). The shell interprets the quote as the closing @@ -2642,7 +2710,7 @@ $ @kbd{awk '@{ print "hello" @} # let's be cute'} @cindex @code{\} (backslash) @cindex backslash (@code{\}) Putting a backslash before the single quote in @samp{let's} wouldn't help, -since backslashes are not special inside single quotes. +because backslashes are not special inside single quotes. The next @value{SUBSECTION} describes the shell's quoting rules. @end quotation @@ -2654,7 +2722,7 @@ The next @value{SUBSECTION} describes the shell's quoting rules. * DOS Quoting:: Quoting in Windows Batch Files. @end menu -For short to medium length @command{awk} programs, it is most convenient +For short to medium-length @command{awk} programs, it is most convenient to enter the program on the @command{awk} command line. This is best done by enclosing the entire program in single quotes. This is true whether you are entering the program interactively at @@ -2678,8 +2746,8 @@ or empty, string. The null string is character data that has no value. In other words, it is empty. It is written in @command{awk} programs like this: @code{""}. In the shell, it can be written using single -or double quotes: @code{""} or @code{''}. While the null string has -no characters in it, it does exist. Consider this command: +or double quotes: @code{""} or @code{''}. Although the null string has +no characters in it, it does exist. For example, consider this command: @example $ @kbd{echo ""} @@ -2689,8 +2757,7 @@ $ @kbd{echo ""} Here, the @command{echo} utility receives a single argument, even though that argument has no characters in it. In the rest of this @value{DOCUMENT}, we use the terms @dfn{null string} and @dfn{empty string} -interchangeably. Now, on to the quoting rules. - +interchangeably. Now, on to the quoting rules: @itemize @value{BULLET} @item @@ -2713,7 +2780,7 @@ The shell does no interpretation of the quoted text, passing it on verbatim to the command. It is @emph{impossible} to embed a single quote inside single-quoted text. Refer back to -@ref{Comments}, +@DBREF{Comments} for an example of what happens if you try. @item @@ -2723,7 +2790,7 @@ Double quotes protect most things between the opening and closing quotes. The shell does at least variable and command substitution on the quoted text. Different shells may do additional kinds of processing on double-quoted text. -Since certain characters within double-quoted text are processed by the shell, +Because certain characters within double-quoted text are processed by the shell, they must be @dfn{escaped} within the text. Of note are the characters @samp{$}, @samp{`}, @samp{\}, and @samp{"}, all of which must be preceded by a backslash within double-quoted text if they are to be passed on literally @@ -2785,7 +2852,7 @@ $ @kbd{awk 'BEGIN @{ print "Here is a single quote <'"'"'>" @}'} @noindent This program consists of three concatenated quoted strings. The first and the -third are single-quoted, the second is double-quoted. +third are single quoted, the second is double quoted. This can be ``simplified'' to: @@ -2830,7 +2897,7 @@ escapes mean. A fourth option is to use command-line variable assignment, like this: @example -$ awk -v sq="'" 'BEGIN @{ print "Here is a single quote <" sq ">" @}' +$ @kbd{awk -v sq="'" 'BEGIN @{ print "Here is a single quote <" sq ">" @}'} @print{} Here is a single quote <'> @end example @@ -2901,7 +2968,7 @@ information about monthly shipments. In both files, each line is considered to be one @dfn{record}. In @file{mail-list}, each record contains the name of a person, -his/her phone number, his/her email-address, and a code for their relationship +his/her phone number, his/her email address, and a code for his/her relationship with the author of the list. The columns are aligned using spaces. An @samp{A} in the last column @@ -3022,8 +3089,8 @@ empty action that does nothing (i.e., no lines are printed). Many practical @command{awk} programs are just a line or two. Following is a collection of useful, short programs to get you started. Some of these programs contain constructs that haven't been covered yet. (The description -of the program will give you a good idea of what is going on, but please -read the rest of the @value{DOCUMENT} to become an @command{awk} expert!) +of the program will give you a good idea of what is going on, but you'll +need to read the rest of the @value{DOCUMENT} to become an @command{awk} expert!) Most of the examples use a @value{DF} named @file{data}. This is just a placeholder; if you use these programs yourself, substitute your own @value{FN}s for @file{data}. @@ -3064,7 +3131,7 @@ expand data | awk '@{ if (x < length($0)) x = length($0) @} @end example This example differs slightly from the previous one: -The input is processed by the @command{expand} utility to change TABs +the input is processed by the @command{expand} utility to change TABs into spaces, so the widths compared are actually the right-margin columns, as opposed to the number of input characters on each line. @@ -3318,7 +3385,7 @@ lines in the middle of a regular expression or a string. with the C shell.} It works for @command{awk} programs in files and for one-shot programs, @emph{provided} you are using a POSIX-compliant shell, such as the Unix Bourne shell or Bash. But the C shell behaves -differently! There, you must use two backslashes in a row, followed by +differently! There you must use two backslashes in a row, followed by a newline. Note also that when using the C shell, @emph{every} newline in your @command{awk} program must be escaped with a backslash. To illustrate: @@ -3359,9 +3426,9 @@ starts a comment, it ignores @emph{everything} on the rest of the line. For example: @example -$ gawk 'BEGIN @{ print "dont panic" # a friendly \ -> BEGIN rule -> @}' +$ @kbd{gawk 'BEGIN @{ print "dont panic" # a friendly \} +> @kbd{ BEGIN rule} +> @kbd{@}'} @error{} gawk: cmd. line:2: BEGIN rule @error{} gawk: cmd. line:2: ^ syntax error @end example @@ -3411,7 +3478,7 @@ and array sorting. As we develop our presentation of the @command{awk} language, we introduce most of the variables and many of the functions. They are described -systematically in @ref{Built-in Variables}, and in +systematically in @DBREF{Built-in Variables} and in @ref{Built-in}. @node When @@ -3445,8 +3512,8 @@ eight-bit microprocessors, @end ifset and a microcode assembler for a special-purpose Prolog computer. -While the original @command{awk}'s capabilities were strained by tasks -of such complexity, modern versions are more capable. +The original @command{awk}'s capabilities were strained by tasks +of such complexity, but modern versions are more capable. @cindex @command{awk} programs, complex If you find yourself writing @command{awk} scripts of more than, say, @@ -3501,7 +3568,7 @@ a comma, open brace, question mark, colon, This @value{CHAPTER} covers how to run @command{awk}, both POSIX-standard and @command{gawk}-specific command-line options, and what @command{awk} and -@command{gawk} do with non-option arguments. +@command{gawk} do with nonoption arguments. It then proceeds to cover how @command{gawk} searches for source files, reading standard input along with other files, @command{gawk}'s environment variables, @command{gawk}'s exit status, using include files, @@ -3545,7 +3612,7 @@ enclosed in [@dots{}] in these templates are optional: @cindex GNU long options @cindex long options @cindex options, long -Besides traditional one-letter POSIX-style options, @command{gawk} also +In addition to traditional one-letter POSIX-style options, @command{gawk} also supports GNU long options. @cindex dark corner, invoking @command{awk} @@ -3608,7 +3675,7 @@ Set the @code{FS} variable to @var{fs} @cindex @option{--file} option @cindex @command{awk} programs, location of Read @command{awk} program source from @var{source-file} -instead of in the first non-option argument. +instead of in the first nonoption argument. This option may be given multiple times; the @command{awk} program consists of the concatenation of the contents of each specified @var{source-file}. @@ -3777,7 +3844,13 @@ Command-line variable assignments of the form This option is particularly necessary for World Wide Web CGI applications that pass arguments through the URL; using this option prevents a malicious (or other) user from passing in options, assignments, or @command{awk} source -code (via @option{-e}) to the CGI application. This option should be used +code (via @option{-e}) to the CGI application.@footnote{For more detail, +please see Section 4.4 of @uref{http://www.ietf.org/rfc/rfc3875, +RFC 3875}. Also see the +@uref{http://lists.gnu.org/archive/html/bug-gawk/2014-11/msg00022.html, +explanatory note sent to the @command{gawk} bug +mailing list}.} +This option should be used with @samp{#!} scripts (@pxref{Executable Scripts}), like so: @example @@ -3868,7 +3941,7 @@ care to search for all occurrences of each inappropriate construct. As @itemx @option{--bignum} @cindex @option{-M} option @cindex @option{--bignum} option -Force arbitrary precision arithmetic on numbers. This option has no effect +Force arbitrary-precision arithmetic on numbers. This option has no effect if @command{gawk} is not compiled to use the GNU MPFR and MP libraries (@pxref{Arbitrary Precision Arithmetic}). @@ -3884,10 +3957,8 @@ values in input data (@pxref{Nondecimal Data}). @quotation CAUTION -This option can severely break old programs. -Use with care. - -This option may disappear in a future version of @command{gawk}. +This option can severely break old programs. Use with care. Also note +that this option may disappear in a future version of @command{gawk}. @end quotation @item @option{-N} @@ -3919,7 +3990,7 @@ This is no longer the case. @cindex @option{--optimize} option @cindex @option{-O} option Enable some optimizations on the internal representation of the program. -At the moment this includes just simple constant folding. +At the moment, this includes just simple constant folding. @item @option{-p}[@var{file}] @itemx @option{--profile}[@code{=}@var{file}] @@ -3996,8 +4067,8 @@ Allow interval expressions (@pxref{Regexp Operators}) in regexps. This is now @command{gawk}'s default behavior. -Nevertheless, this option remains both for backward compatibility, -and for use in combination with @option{--traditional}. +Nevertheless, this option remains (both for backward compatibility +and for use in combination with @option{--traditional}). @item @option{-S} @itemx @option{--sandbox} @@ -4050,7 +4121,7 @@ If it is, @command{awk} reads its program source from all of the named files, as if they had been concatenated together into one big file. This is useful for creating libraries of @command{awk} functions. These functions can be written once and then retrieved from a standard place, instead -of having to be included into each individual program. +of having to be included in each individual program. The @option{-i} option is similar in this regard. (As mentioned in @ref{Definition Syntax}, @@ -4061,7 +4132,7 @@ if the program is entered at the keyboard, by specifying @samp{-f /dev/tty}. After typing your program, type @kbd{Ctrl-d} (the end-of-file character) to terminate it. (You may also use @samp{-f -} to read program source from the standard -input but then you will not be able to also use the standard input as a +input, but then you will not be able to also use the standard input as a source of data.) Because it is clumsy using the standard @command{awk} mechanisms to mix @@ -4074,7 +4145,7 @@ options may also be used multiple times on the command line. @cindex @option{-e} option If no @option{-f} or @option{-e} option is specified, then @command{gawk} -uses the first non-option command-line argument as the text of the +uses the first nonoption command-line argument as the text of the program source code. @cindex @env{POSIXLY_CORRECT} environment variable @@ -4141,7 +4212,7 @@ All the command-line arguments are made available to your @command{awk} program and the program text (if present) are omitted from @code{ARGV}. All other arguments, including variable assignments, are included. As each element of @code{ARGV} is processed, @command{gawk} -sets the variable @code{ARGIND} to the index in @code{ARGV} of the +sets @code{ARGIND} to the index in @code{ARGV} of the current element. @c FIXME: One day, move the ARGC and ARGV node closer to here. @@ -4321,7 +4392,7 @@ manipulate the @env{AWKPATH} variable. @code{ENVIRON["AWKPATH"]}. This provides access to the actual search path value from within an @command{awk} program. -While you can change @code{ENVIRON["AWKPATH"]} within your @command{awk} +Although you can change @code{ENVIRON["AWKPATH"]} within your @command{awk} program, this has no effect on the running program's behavior. This makes sense: the @env{AWKPATH} environment variable is used to find the program source files. Once your program is running, all the files have been @@ -4360,7 +4431,7 @@ path value from within an @command{awk} program. A number of other environment variables affect @command{gawk}'s behavior, but they are more specialized. Those in the following -list are meant to be used by regular users. +list are meant to be used by regular users: @table @env @item GAWK_MSEC_SLEEP @@ -4380,7 +4451,7 @@ retry a two-way TCP/IP (socket) connection before giving up. @xref{TCP/IP Networking}. @item POSIXLY_CORRECT -Causes @command{gawk} to switch to POSIX compatibility +Causes @command{gawk} to switch to POSIX-compatibility mode, disabling all traditional and GNU extensions. @xref{Options}. @end table @@ -4412,11 +4483,11 @@ for debugging problems on filesystems on non-POSIX operating systems where I/O is performed in records, not in blocks. @item GAWK_MSG_SRC -If this variable exists, @command{gawk} includes the file -name and line number within the @command{gawk} source code +If this variable exists, @command{gawk} includes the @value{FN} +and line number within the @command{gawk} source code from which warning and/or fatal messages are generated. Its purpose is to help isolate the source of a -message, since there are multiple places which produce the +message, as there are multiple places which produce the same warning or error message. @item GAWK_NO_DFA @@ -4460,11 +4531,11 @@ If an error occurs, @command{gawk} exits with the value of the C constant @code{EXIT_FAILURE}. This is usually one. If @command{gawk} exits because of a fatal error, the exit -status is 2. On non-POSIX systems, this value may be mapped +status is two. On non-POSIX systems, this value may be mapped to @code{EXIT_FAILURE}. @node Include Files -@section Including Other Files Into Your Program +@section Including Other Files into Your Program @c Panos Papadopoulos <panos1962@gmail.com> contributed the original @c text for this section. @@ -4513,9 +4584,9 @@ $ @kbd{gawk -f test2} @print{} This is script test2. @end example -@code{gawk} runs the @file{test2} script which includes @file{test1} +@code{gawk} runs the @file{test2} script, which includes @file{test1} using the @code{@@include} -keyword. So, to include external @command{awk} source files you just +keyword. So, to include external @command{awk} source files, you just use @code{@@include} followed by the name of the file to be included, enclosed in double quotes. @@ -4552,26 +4623,26 @@ The @value{FN} can, of course, be a pathname. For example: @end example @noindent -or: +and: @example @@include "/usr/awklib/network" @end example @noindent -are valid. The @env{AWKPATH} environment variable can be of great +are both valid. The @env{AWKPATH} environment variable can be of great value when using @code{@@include}. The same rules for the use of the @env{AWKPATH} variable in command-line file searches (@pxref{AWKPATH Variable}) apply to @code{@@include} also. This is very helpful in constructing @command{gawk} function libraries. -If you have a large script with useful, general purpose @command{awk} +If you have a large script with useful, general-purpose @command{awk} functions, you can break it down into library files and put those files in a special directory. You can then include those ``libraries,'' using either the full pathnames of the files, or by setting the @env{AWKPATH} environment variable accordingly and then using @code{@@include} with -just the file part of the full pathname. Of course you can have more +just the file part of the full pathname. Of course, you can have more than one directory to keep library files; the more complex the working environment is, the more directories you may need to organize the files to be included. @@ -4589,7 +4660,7 @@ searched first for source files, before searching in @env{AWKPATH}, and this also applies to files named with @code{@@include}. @node Loading Shared Libraries -@section Loading Dynamic Extensions Into Your Program +@section Loading Dynamic Extensions into Your Program This @value{SECTION} describes a feature that is specific to @command{gawk}. @@ -4599,7 +4670,7 @@ This @value{SECTION} describes a feature that is specific to @command{gawk}. The @code{@@load} keyword can be used to read external @command{awk} extensions (stored as system shared libraries). This allows you to link in compiled code that may offer superior -performance and/or give you access to extended capabilities not supported +performance and/or give you access to extended capabilities not supported by the @command{awk} language. The @env{AWKLIBPATH} variable is used to search for the extension. Using @code{@@load} is completely equivalent to using the @option{-l} command-line option. @@ -4607,7 +4678,7 @@ to using the @option{-l} command-line option. If the extension is not initially found in @env{AWKLIBPATH}, another search is conducted after appending the platform's default shared library suffix to the @value{FN}. For example, on GNU/Linux systems, the suffix -@samp{.so} is used. +@samp{.so} is used: @example $ @kbd{gawk '@@load "ordchr"; BEGIN @{print chr(65)@}'} @@ -4742,13 +4813,13 @@ The three standard options for all versions of @command{awk} are and many others, as well as corresponding GNU-style long options. @item -Non-option command-line arguments are usually treated as @value{FN}s, +Nonoption command-line arguments are usually treated as @value{FN}s, unless they have the form @samp{@var{var}=@var{value}}, in which case they are taken as variable assignments to be performed at that point in processing the input. @item -All non-option command-line arguments, excluding the program text, +All nonoption command-line arguments, excluding the program text, are placed in the @code{ARGV} array. Adjusting @code{ARGC} and @code{ARGV} affects how @command{awk} processes input. @@ -4797,7 +4868,7 @@ belongs to that set. The simplest regular expression is a sequence of letters, numbers, or both. Such a regexp matches any string that contains that sequence. Thus, the regexp @samp{foo} matches any string containing @samp{foo}. -Therefore, the pattern @code{/foo/} matches any input record containing +Thus, the pattern @code{/foo/} matches any input record containing the three adjacent characters @samp{foo} @emph{anywhere} in the record. Other kinds of regexps let you specify more complicated classes of strings. @@ -4860,17 +4931,16 @@ and @samp{!~} perform regular expression comparisons. Expressions using these operators can be used as patterns, or in @code{if}, @code{while}, @code{for}, and @code{do} statements. (@xref{Statements}.) -For example: +For example, the following is true if the expression @var{exp} (taken +as a string) matches @var{regexp}: @example @var{exp} ~ /@var{regexp}/ @end example @noindent -is true if the expression @var{exp} (taken as a string) -matches @var{regexp}. The following example matches, or selects, -all input records with the uppercase letter @samp{J} somewhere in the -first field: +This example matches, or selects, all input records with the uppercase +letter @samp{J} somewhere in the first field: @example $ @kbd{awk '$1 ~ /J/' inventory-shipped} @@ -4940,9 +5010,9 @@ string or regexp. Thus, the string whose contents are the two characters @samp{"} and @samp{\} must be written @code{"\"\\"}. Other escape sequences represent unprintable characters -such as TAB or newline. While there is nothing to stop you from entering most +such as TAB or newline. There is nothing to stop you from entering most unprintable characters directly in a string constant or regexp constant, -they may look ugly. +but they may look ugly. The following list presents all the escape sequences used in @command{awk} and @@ -5032,7 +5102,7 @@ A literal slash (necessary for regexp constants only). This sequence is used when you want to write a regexp constant that contains a slash (such as @code{/.*:\/home\/[[:alnum:]]+:.*/}; the @samp{[[:alnum:]]} -notation is discussed shortly, in @ref{Bracket Expressions}). +notation is discussed in @ref{Bracket Expressions}). Because the regexp is delimited by slashes, you need to escape any slash that is part of the pattern, in order to tell @command{awk} to keep processing the rest of the regexp. @@ -5055,7 +5125,7 @@ with a backslash have special meaning in regexps. In a regexp, a backslash before any character that is not in the previous list and not listed in -@ref{GNU Regexp Operators}, +@DBREF{GNU Regexp Operators} means that the next character should be taken literally, even if it would normally be a regexp operator. For example, @code{/a\+b/} matches the three characters @samp{a+b}. @@ -5066,25 +5136,7 @@ characters @samp{a+b}. For complete portability, do not use a backslash before any character not shown in the previous list and that is not an operator. -To summarize: - -@itemize @value{BULLET} -@item -The escape sequences in the list above are always processed first, -for both string constants and regexp constants. This happens very early, -as soon as @command{awk} reads your program. - -@item -@command{gawk} processes both regexp constants and dynamic regexps -(@pxref{Computed Regexps}), -for the special operators listed in -@ref{GNU Regexp Operators}. - -@item -A backslash before any other character means to treat that character -literally. -@end itemize - +@c 11/2014: Moved so as to not stack sidebars @sidebar Backslash Before Regular Characters @cindex portability, backslash in escape sequences @cindex POSIX @command{awk}, backslashes in string constants @@ -5120,6 +5172,25 @@ In such implementations, typing @code{"a\qc"} is the same as typing @end table @end sidebar +To summarize: + +@itemize @value{BULLET} +@item +The escape sequences in the preceding list are always processed first, +for both string constants and regexp constants. This happens very early, +as soon as @command{awk} reads your program. + +@item +@command{gawk} processes both regexp constants and dynamic regexps +(@pxref{Computed Regexps}), +for the special operators listed in +@ref{GNU Regexp Operators}. + +@item +A backslash before any other character means to treat that character +literally. +@end itemize + @sidebar Escape Sequences for Metacharacters @cindex metacharacters, escape sequences for @@ -5167,7 +5238,7 @@ sequences and that are not listed in the following stand for themselves: @cindex backslash (@code{\}), regexp operator @cindex @code{\} (backslash), regexp operator @item @code{\} -This is used to suppress the special meaning of a character when +This suppresses the special meaning of a character when matching. For example, @samp{\$} matches the character @samp{$}. @@ -5176,8 +5247,9 @@ matches the character @samp{$}. @cindex @code{^} (caret), regexp operator @cindex caret (@code{^}), regexp operator @item @code{^} -This matches the beginning of a string. For example, @samp{^@@chapter} -matches @samp{@@chapter} at the beginning of a string and can be used +This matches the beginning of a string. @samp{^@@chapter} +matches @samp{@@chapter} at the beginning of a string, +for example, and can be used to identify chapter beginnings in Texinfo source files. The @samp{^} is known as an @dfn{anchor}, because it anchors the pattern to match only at the beginning of the string. @@ -5283,7 +5355,7 @@ There are two subtle points to understand about how @samp{*} works. First, the @samp{*} applies only to the single preceding regular expression component (e.g., in @samp{ph*}, it applies just to the @samp{h}). To cause @samp{*} to apply to a larger sub-expression, use parentheses: -@samp{(ph)*} matches @samp{ph}, @samp{phph}, @samp{phphph} and so on. +@samp{(ph)*} matches @samp{ph}, @samp{phph}, @samp{phphph}, and so on. Second, @samp{*} finds as many repetitions as possible. If the text to be matched is @samp{phhhhhhhhhhhhhhooey}, @samp{ph*} matches all of @@ -5383,7 +5455,7 @@ expressions are not available in regular expressions. @cindex range expressions (regexps) @cindex character lists in regular expression -As mentioned earlier, a bracket expression matches any character amongst +As mentioned earlier, a bracket expression matches any character among those listed between the opening and closing square brackets. Within a bracket expression, a @dfn{range expression} consists of two @@ -5441,23 +5513,23 @@ a keyword denoting the class, and @samp{:]}. POSIX standard. @float Table,table-char-classes -@caption{POSIX Character Classes} +@caption{POSIX character classes} @multitable @columnfractions .15 .85 @headitem Class @tab Meaning -@item @code{[:alnum:]} @tab Alphanumeric characters. -@item @code{[:alpha:]} @tab Alphabetic characters. -@item @code{[:blank:]} @tab Space and TAB characters. -@item @code{[:cntrl:]} @tab Control characters. -@item @code{[:digit:]} @tab Numeric characters. -@item @code{[:graph:]} @tab Characters that are both printable and visible. -(A space is printable but not visible, whereas an @samp{a} is both.) -@item @code{[:lower:]} @tab Lowercase alphabetic characters. -@item @code{[:print:]} @tab Printable characters (characters that are not control characters). -@item @code{[:punct:]} @tab Punctuation characters (characters that are not letters, digits, -control characters, or space characters). -@item @code{[:space:]} @tab Space characters (such as space, TAB, and formfeed, to name a few). -@item @code{[:upper:]} @tab Uppercase alphabetic characters. -@item @code{[:xdigit:]} @tab Characters that are hexadecimal digits. +@item @code{[:alnum:]} @tab Alphanumeric characters +@item @code{[:alpha:]} @tab Alphabetic characters +@item @code{[:blank:]} @tab Space and TAB characters +@item @code{[:cntrl:]} @tab Control characters +@item @code{[:digit:]} @tab Numeric characters +@item @code{[:graph:]} @tab Characters that are both printable and visible +(a space is printable but not visible, whereas an @samp{a} is both) +@item @code{[:lower:]} @tab Lowercase alphabetic characters +@item @code{[:print:]} @tab Printable characters (characters that are not control characters) +@item @code{[:punct:]} @tab Punctuation characters (characters that are not letters, digits +control characters, or space characters) +@item @code{[:space:]} @tab Space characters (such as space, TAB, and formfeed, to name a few) +@item @code{[:upper:]} @tab Uppercase alphabetic characters +@item @code{[:xdigit:]} @tab Characters that are hexadecimal digits @end multitable @end float @@ -5472,7 +5544,7 @@ and numeric characters in your character set. @c Thanks to @c Date: Tue, 01 Jul 2014 07:39:51 +0200 @c From: Hermann Peifer <peifer@gmx.eu> -Some utilities that match regular expressions provide a non-standard +Some utilities that match regular expressions provide a nonstandard @code{[:ascii:]} character class; @command{awk} does not. However, you can simulate such a construct using @code{[\x00-\x7F]}. This matches all values numerically between zero and 127, which is the defined @@ -5658,7 +5730,7 @@ $ @kbd{awk '$0 ~ "[ \t\n]"'} @error{} ]... @error{} source line number 1 @error{} context is -@error{} $0 ~ "[ >>> \t\n]" <<< +@error{} $0 ~ "[ >>> \t\n]" <<< @end example @cindex newlines, in regexp constants @@ -5768,9 +5840,9 @@ word-constituent characters. For example, @cindex regular expressions, operators, for buffers @cindex operators, string-matching, for buffers There are two other operators that work on buffers. In Emacs, a -@dfn{buffer} is, naturally, an Emacs buffer. For other programs, -@command{gawk}'s regexp library routines consider the entire -string to match as the buffer. +@dfn{buffer} is, naturally, an Emacs buffer. +Other GNU programs, including @command{gawk}, +consider the entire string to match as the buffer. The operators are: @table @code @@ -5831,16 +5903,16 @@ in @ref{Regexp Operators}. @end ifnottex @item @code{--posix} -Only POSIX regexps are supported; the GNU operators are not special +Match only POSIX regexps; the GNU operators are not special (e.g., @samp{\w} matches a literal @samp{w}). Interval expressions are allowed. @cindex Brian Kernighan's @command{awk} @item @code{--traditional} -Traditional Unix @command{awk} regexps are matched. The GNU operators +Match traditional Unix @command{awk} regexps. The GNU operators are not special, and interval expressions are not available. -The POSIX character classes (@samp{[[:alnum:]]}, etc.) are supported, -as BWK @command{awk} supports them. +Because BWK @command{awk} supports them, +the POSIX character classes (@samp{[[:alnum:]]}, etc.) are available. Characters described by octal and hexadecimal escape sequences are treated literally, even if they represent regexp metacharacters. @@ -5900,7 +5972,7 @@ When @code{IGNORECASE} is not zero, @emph{all} regexp and string operations ignore case. Changing the value of @code{IGNORECASE} dynamically controls the -case-sensitivity of the program as it runs. Case is significant by +case sensitivity of the program as it runs. Case is significant by default because @code{IGNORECASE} (like most variables) is initialized to zero: @@ -5913,7 +5985,7 @@ if (x ~ /ab/) @dots{} # now it will succeed @end example In general, you cannot use @code{IGNORECASE} to make certain rules -case-insensitive and other rules case-sensitive, because there is no +case insensitive and other rules case sensitive, as there is no straightforward way to set @code{IGNORECASE} just for the pattern of a particular rule.@footnote{Experienced C and C++ programmers will note @@ -5924,13 +5996,13 @@ and However, this is somewhat obscure and we don't recommend it.} To do this, use either bracket expressions or @code{tolower()}. However, one thing you can do with @code{IGNORECASE} only is dynamically turn -case-sensitivity on or off for all the rules at once. +case sensitivity on or off for all the rules at once. @code{IGNORECASE} can be set on the command line or in a @code{BEGIN} rule (@pxref{Other Arguments}; also @pxref{Using BEGIN/END}). Setting @code{IGNORECASE} from the command line is a way to make -a program case-insensitive without having to edit it. +a program case insensitive without having to edit it. @c @cindex ISO 8859-1 @c @cindex ISO Latin-1 @@ -5967,12 +6039,12 @@ in conditional expressions, or as part of matching expressions using the @samp{~} and @samp{!~} operators. @item -Escape sequences let you represent non-printable characters and +Escape sequences let you represent nonprintable characters and also let you represent regexp metacharacters as literal characters to be matched. @item -Regexp operators provide grouping, alternation and repetition. +Regexp operators provide grouping, alternation, and repetition. @item Bracket expressions give you a shorthand for specifying sets @@ -5987,8 +6059,8 @@ the match, such as for text substitution and when the record separator is a regexp. @item -Matching expressions may use dynamic regexps, that is, string values -treated as regular expressions. +Matching expressions may use dynamic regexps (i.e., string values +treated as regular expressions). @item @command{gawk}'s @code{IGNORECASE} variable lets you control the @@ -6062,7 +6134,7 @@ used with it do not have to be named on the @command{awk} command line @command{awk} divides the input for your program into records and fields. It keeps track of the number of records that have been read so far from the current input file. This value is stored in a predefined variable -called @code{FNR} which is reset to zero every time a new file is started. +called @code{FNR}, which is reset to zero every time a new file is started. Another predefined variable, @code{NR}, records the total number of input records read so far from all @value{DF}s. It starts at zero, but is never automatically reset to zero. @@ -6073,7 +6145,7 @@ never automatically reset to zero. @end menu @node awk split records -@subsection Record Splitting With Standard @command{awk} +@subsection Record Splitting with Standard @command{awk} @cindex separators, for records @cindex record separators @@ -6090,7 +6162,7 @@ the value of @code{RS} can be changed in the @command{awk} program with the assignment operator, @samp{=} (@pxref{Assignment Ops}). The new record-separator character should be enclosed in quotation marks, -which indicate a string constant. Often the right time to do this is +which indicate a string constant. Often, the right time to do this is at the beginning of execution, before any input is processed, so that the very first record is read with the proper separator. To do this, use the special @code{BEGIN} pattern @@ -6104,7 +6176,7 @@ awk 'BEGIN @{ RS = "u" @} @noindent changes the value of @code{RS} to @samp{u}, before reading any input. -This is a string whose first character is the letter ``u;'' as a result, records +This is a string whose first character is the letter ``u''; as a result, records are separated by the letter ``u.'' Then the input file is read, and the second rule in the @command{awk} program (the action with no pattern) prints each record. Because each @code{print} statement adds a newline at the end of @@ -6152,7 +6224,7 @@ $ @kbd{awk 'BEGIN @{ RS = "u" @}} @print{} m@@ny @print{} .ed @print{} R -@print{} +@print{} @end example @noindent @@ -6198,7 +6270,7 @@ being fully POSIX-compliant (@pxref{Options}). Then, the following (extreme) pipeline prints a surprising @samp{1}: @example -$ echo | gawk --posix 'BEGIN @{ RS = "a" @} ; @{ print NF @}' +$ @kbd{echo | gawk --posix 'BEGIN @{ RS = "a" @} ; @{ print NF @}'} @print{} 1 @end example @@ -6220,7 +6292,7 @@ The empty string @code{""} (a string without any characters) has a special meaning as the value of @code{RS}. It means that records are separated by one or more blank lines and nothing else. -@xref{Multiple Line}, for more details. +@DBXREF{Multiple Line} for more details. If you change the value of @code{RS} in the middle of an @command{awk} run, the new value is used to delimit subsequent records, but the record @@ -6240,7 +6312,7 @@ sets the variable @code{RT} to the text in the input that matched @code{RS}. @node gawk split records -@subsection Record Splitting With @command{gawk} +@subsection Record Splitting with @command{gawk} @cindex common extensions, @code{RS} as a regexp @cindex extensions, common@comma{} @code{RS} as a regexp @@ -6284,11 +6356,11 @@ $ @kbd{echo record 1 AAAA record 2 BBBB record 3 |} The square brackets delineate the contents of @code{RT}, letting you see the leading and trailing whitespace. The final value of @code{RT} is a newline. -@xref{Simple Sed}, for a more useful example +@DBXREF{Simple Sed} for a more useful example of @code{RS} as a regexp and @code{RT}. If you set @code{RS} to a regular expression that allows optional -trailing text, such as @samp{RS = "abc(XYZ)?"} it is possible, due +trailing text, such as @samp{RS = "abc(XYZ)?"}, it is possible, due to implementation constraints, that @command{gawk} may match the leading part of the regular expression, but not the trailing part, particularly if the input text that could match the trailing part is fairly long. @@ -6302,7 +6374,7 @@ the beginning and end of a @emph{line}. As a result, something like @samp{RS = "^[[:upper:]]"} can only match at the beginning of a file. This is because @command{gawk} views the input file as one long string that happens to contain newline characters. -It is thus best to avoid anchor characters in the value of @code{RS}. +It is thus best to avoid anchor metacharacters in the value of @code{RS}. @end quotation @cindex differences in @command{awk} and @command{gawk}, @code{RS}/@code{RT} variables @@ -6351,9 +6423,9 @@ character as a record separator. However, this is a special case: @cindex records, treating files as @cindex treating files, as single records -@xref{Readfile Function}, for an interesting way to read -whole files. If you are using @command{gawk}, see @ref{Extension Sample -Readfile}, for another option. +@DBXREF{Readfile Function} for an interesting way to read +whole files. If you are using @command{gawk}, see @DBREF{Extension Sample +Readfile} for another option. @end sidebar @c ENDOFRANGE inspl @c ENDOFRANGE recspl @@ -6375,9 +6447,9 @@ called @dfn{fields}. By default, fields are separated by @dfn{whitespace}, like words in a line. Whitespace in @command{awk} means any string of one or more spaces, TABs, or newlines;@footnote{In POSIX @command{awk}, newlines are not -considered whitespace for separating fields.} other characters, such as -formfeed, vertical tab, etc., that are -considered whitespace by other languages, are @emph{not} considered +considered whitespace for separating fields.} other characters +that are considered whitespace by other languages +(such as formfeed, vertical tab, etc.) are @emph{not} considered whitespace by @command{awk}. The purpose of fields is to make it more convenient for you to refer to @@ -6394,7 +6466,7 @@ to refer to a field in an @command{awk} program, followed by the number of the field you want. Thus, @code{$1} refers to the first field, @code{$2} to the second, and so on. (Unlike the Unix shells, the field numbers are not limited to single digits. -@code{$127} is the one hundred twenty-seventh field in the record.) +@code{$127} is the 127th field in the record.) For example, suppose the following is a line of input: @example @@ -6464,7 +6536,7 @@ awk '@{ print $NR @}' @noindent Recall that @code{NR} is the number of records read so far: one in the -first record, two in the second, etc. So this example prints the first +first record, two in the second, and so on. So this example prints the first field of the first record, the second field of the second record, and so on. For the twentieth record, field number 20 is printed; most likely, the record has fewer than 20 fields, so this prints a blank line. @@ -6481,7 +6553,7 @@ The parentheses are used so that the multiplication is done before the @samp{$} operation; they are necessary whenever there is a binary operator@footnote{A @dfn{binary operator}, such as @samp{*} for multiplication, is one that takes two operands. The distinction -is required, since @command{awk} also has unary (one-operand) +is required, because @command{awk} also has unary (one-operand) and ternary (three-operand) operators.} in the field-number expression. This example, then, prints the type of relationship (the fourth field) for every line of the file @@ -6555,7 +6627,7 @@ $ @kbd{awk '@{ $2 = $2 - 10; print $0 @}' inventory-shipped} @dots{} @end example -It is also possible to also assign contents to fields that are out +It is also possible to assign contents to fields that are out of range. For example: @example @@ -6606,9 +6678,9 @@ else @noindent should print @samp{everything is normal}, because @code{NF+1} is certain -to be out of range. (@xref{If Statement}, +to be out of range. (@DBXREF{If Statement} for more information about @command{awk}'s @code{if-else} statements. -@xref{Typing and Comparison}, +@DBXREF{Typing and Comparison} for more information about the @samp{!=} operator.) It is important to note that making an assignment to an existing field @@ -6648,8 +6720,8 @@ after the new value of @code{NF} and recomputes @code{$0}. Here is an example: @example -$ echo a b c d e f | awk '@{ print "NF =", NF; -> NF = 3; print $0 @}' +$ @kbd{echo a b c d e f | awk '@{ print "NF =", NF;} +> @kbd{ NF = 3; print $0 @}'} @print{} NF = 6 @print{} a b c @end example @@ -6693,7 +6765,7 @@ in a record simply by setting @code{FS} and @code{OFS}, and then expecting a plain @samp{print} or @samp{print $0} to print the modified record. -But this does not work, since nothing was done to change the record +But this does not work, because nothing was done to change the record itself. Instead, you must force the record to be rebuilt, typically with a statement such as @samp{$1 = $1}, as described earlier. @end sidebar @@ -6745,7 +6817,7 @@ the Unix Bourne shell, @command{sh}, or Bash). @cindex @code{FS} variable, changing value of The value of @code{FS} can be changed in the @command{awk} program with the assignment operator, @samp{=} (@pxref{Assignment Ops}). -Often the right time to do this is at the beginning of execution +Often, the right time to do this is at the beginning of execution before any input has been processed, so that the very first record is read with the proper separator. To do this, use the special @code{BEGIN} pattern @@ -6901,7 +6973,7 @@ statement prints the new @code{$0}. @cindex dark corner, @code{^}, in @code{FS} There is an additional subtlety to be aware of when using regular expressions for field splitting. -It is not well-specified in the POSIX standard, or anywhere else, what @samp{^} +It is not well specified in the POSIX standard, or anywhere else, what @samp{^} means when splitting fields. Does the @samp{^} match only at the beginning of the entire record? Or is each field separator a new string? It turns out that different @command{awk} versions answer this question differently, and you @@ -7067,11 +7139,11 @@ awk -F: '$5 == ""' /etc/passwd @end example @node Full Line Fields -@subsection Making The Full Line Be A Single Field +@subsection Making the Full Line Be a Single Field Occasionally, it's useful to treat the whole input line as a single field. This can be done easily and portably simply by -setting @code{FS} to @code{"\n"} (a newline).@footnote{Thanks to +setting @code{FS} to @code{"\n"} (a newline):@footnote{Thanks to Andrew Schorr for this tip.} @example @@ -7081,42 +7153,6 @@ awk -F'\n' '@var{program}' @var{files @dots{}} @noindent When you do this, @code{$1} is the same as @code{$0}. -@node Field Splitting Summary -@subsection Field-Splitting Summary - -It is important to remember that when you assign a string constant -as the value of @code{FS}, it undergoes normal @command{awk} string -processing. For example, with Unix @command{awk} and @command{gawk}, -the assignment @samp{FS = "\.."} assigns the character string @code{".."} -to @code{FS} (the backslash is stripped). This creates a regexp meaning -``fields are separated by occurrences of any two characters.'' -If instead you want fields to be separated by a literal period followed -by any single character, use @samp{FS = "\\.."}. - -The following list summarizes how fields are split, based on the value -of @code{FS} (@samp{==} means ``is equal to''): - -@table @code -@item FS == " " -Fields are separated by runs of whitespace. Leading and trailing -whitespace are ignored. This is the default. - -@item FS == @var{any other single character} -Fields are separated by each occurrence of the character. Multiple -successive occurrences delimit empty fields, as do leading and -trailing occurrences. -The character can even be a regexp metacharacter; it does not need -to be escaped. - -@item FS == @var{regexp} -Fields are separated by occurrences of characters that match @var{regexp}. -Leading and trailing matches of @var{regexp} delimit empty fields. - -@item FS == "" -Each individual character in the record becomes a separate field. -(This is a common extension; it is not specified by the POSIX standard.) -@end table - @sidebar Changing @code{FS} Does Not Affect the Fields @cindex POSIX @command{awk}, field separators and @@ -7158,10 +7194,46 @@ on an incorrect implementation of @command{awk}, while @command{gawk} prints the full first line of the file, something like: @example -root:nSijPlPhZZwgE:0:0:Root:/: +root:x:0:0:Root:/: @end example @end sidebar +@node Field Splitting Summary +@subsection Field-Splitting Summary + +It is important to remember that when you assign a string constant +as the value of @code{FS}, it undergoes normal @command{awk} string +processing. For example, with Unix @command{awk} and @command{gawk}, +the assignment @samp{FS = "\.."} assigns the character string @code{".."} +to @code{FS} (the backslash is stripped). This creates a regexp meaning +``fields are separated by occurrences of any two characters.'' +If instead you want fields to be separated by a literal period followed +by any single character, use @samp{FS = "\\.."}. + +The following list summarizes how fields are split, based on the value +of @code{FS} (@samp{==} means ``is equal to''): + +@table @code +@item FS == " " +Fields are separated by runs of whitespace. Leading and trailing +whitespace are ignored. This is the default. + +@item FS == @var{any other single character} +Fields are separated by each occurrence of the character. Multiple +successive occurrences delimit empty fields, as do leading and +trailing occurrences. +The character can even be a regexp metacharacter; it does not need +to be escaped. + +@item FS == @var{regexp} +Fields are separated by occurrences of characters that match @var{regexp}. +Leading and trailing matches of @var{regexp} delimit empty fields. + +@item FS == "" +Each individual character in the record becomes a separate field. +(This is a common extension; it is not specified by the POSIX standard.) +@end table + @sidebar @code{FS} and @code{IGNORECASE} The @code{IGNORECASE} variable @@ -7180,7 +7252,7 @@ print $1 @noindent The output is @samp{aCa}. If you really want to split fields on an alphabetic character while ignoring case, use a regexp that will -do it for you. E.g., @samp{FS = "[c]"}. In this case, @code{IGNORECASE} +do it for you (e.g., @samp{FS = "[c]"}). In this case, @code{IGNORECASE} will take effect. @end sidebar @@ -7190,20 +7262,20 @@ will take effect. @node Constant Size @section Reading Fixed-Width Data -@quotation NOTE +@cindex data, fixed-width +@cindex fixed-width data +@cindex advanced features, fixed-width data + +@c O'Reilly doesn't like it as a note the first thing in the section. This @value{SECTION} discusses an advanced feature of @command{gawk}. If you are a novice @command{awk} user, you might want to skip it on the first reading. -@end quotation -@cindex data, fixed-width -@cindex fixed-width data -@cindex advanced features, fixed-width data -@command{gawk} provides a facility for dealing with -fixed-width fields with no distinctive field separator. For example, -data of this nature arises in the input for old Fortran programs where -numbers are run together, or in the output of programs that did not -anticipate the use of their output as input for other programs. +@command{gawk} provides a facility for dealing with fixed-width fields +with no distinctive field separator. For example, data of this nature +arises in the input for old Fortran programs where numbers are run +together, or in the output of programs that did not anticipate the use +of their output as input for other programs. An example of the latter is a table where all the columns are lined up by the use of a variable number of spaces and @emph{empty fields are just @@ -7242,15 +7314,10 @@ dave ttyq4 26Jun9115days 46 46 wnewmail @end group @end example -The following program takes the above input, converts the idle time to +The following program takes this input, converts the idle time to number of seconds, and prints out the first two fields and the calculated idle time: -@quotation NOTE -This program uses a number of @command{awk} features that -haven't been introduced yet. -@end quotation - @example BEGIN @{ FIELDWIDTHS = "9 6 10 6 7 7 35" @} NR > 2 @{ @@ -7269,6 +7336,11 @@ NR > 2 @{ @} @end example +@quotation NOTE +The preceding program uses a number of @command{awk} features that +haven't been introduced yet. +@end quotation + Running the program on the data produces the following results: @example @@ -7314,17 +7386,16 @@ else This information is useful when writing a function that needs to temporarily change @code{FS} or @code{FIELDWIDTHS}, read some records, and then restore the original settings -(@pxref{Passwd Functions}, +(@DBPXREF{Passwd Functions} for an example of such a function). @node Splitting By Content -@section Defining Fields By Content +@section Defining Fields by Content -@quotation NOTE +@c O'Reilly doesn't like it as a note the first thing in the section. This @value{SECTION} discusses an advanced feature of @command{gawk}. If you are a novice @command{awk} user, you might want to skip it on the first reading. -@end quotation @cindex advanced features, specifying field content Normally, when using @code{FS}, @command{gawk} defines the fields as the @@ -7335,14 +7406,16 @@ However, there are times when you really want to define the fields by what they are, and not by what they are not. The most notorious such case -is so-called @dfn{comma separated value} (CSV) data. Many spreadsheet programs, +is so-called @dfn{comma-separated values} (CSV) data. Many spreadsheet programs, for example, can export their data into text files, where each record is terminated with a newline, and fields are separated by commas. If only commas separated the data, there wouldn't be an issue. The problem comes when -one of the fields contains an @emph{embedded} comma. While there is no -formal standard specification for CSV data@footnote{At least, we don't know of one.}, -in such cases, most programs embed the field in double quotes. So we might -have data like this: +one of the fields contains an @emph{embedded} comma. +In such cases, most programs embed the field in double quotes.@footnote{The +CSV format lacked a formal standard definition for many years. +@uref{http://www.ietf.org/rfc/rfc4180.txt, RFC 4180} +standardizes the most common practices.} +So we might have data like this: @example @c file eg/misc/addresses.csv @@ -7356,7 +7429,7 @@ The @code{FPAT} variable offers a solution for cases like this. The value of @code{FPAT} should be a string that provides a regular expression. This regular expression describes the contents of each field. -In the case of CSV data as presented above, each field is either ``anything that +In the case of CSV data as presented here, each field is either ``anything that is not a comma,'' or ``a double quote, anything that is not a double quote, and a closing double quote.'' If written as a regular expression constant (@pxref{Regexp}), @@ -7421,10 +7494,10 @@ will be @code{"FPAT"} if content-based field splitting is being used. @quotation NOTE Some programs export CSV data that contains embedded newlines between the double quotes. @command{gawk} provides no way to deal with this. -Since there is no formal specification for CSV data, there isn't much +Even though a formal specification for CSV data exists, there isn't much more to be done; the @code{FPAT} mechanism provides an elegant solution for the majority -of cases, and the @command{gawk} developers are satisfied with that. +of cases, and the @command{gawk} developers are satisfied with that. @end quotation As written, the regexp used for @code{FPAT} requires that each field @@ -7578,7 +7651,7 @@ $ @kbd{awk -f addrs.awk addresses} @dots{} @end example -@xref{Labels Program}, for a more realistic program that deals with +@DBXREF{Labels Program} for a more realistic program dealing with address lists. The following list summarizes how records are split, based on the value of @ifinfo @@ -7673,7 +7746,7 @@ represents a shell command. @quotation NOTE When @option{--sandbox} is specified (@pxref{Options}), -reading lines from files, pipes and coprocesses is disabled. +reading lines from files, pipes, and coprocesses is disabled. @end quotation @menu @@ -7816,7 +7889,7 @@ free @end example The @code{getline} command used in this way sets only the variables -@code{NR}, @code{FNR} and @code{RT} (and of course, @var{var}). +@code{NR}, @code{FNR}, and @code{RT} (and of course, @var{var}). The record is not split into fields, so the values of the fields (including @code{$0}) and the value of @code{NF} do not change. @@ -7870,7 +7943,7 @@ you want your program to be portable to all @command{awk} implementations. Use @samp{getline @var{var} < @var{file}} to read input from the file -@var{file}, and put it in the variable @var{var}. As above, @var{file} +@var{file}, and put it in the variable @var{var}. As earlier, @var{file} is a string-valued expression that specifies the file from which to read. In this version of @code{getline}, none of the predefined variables are @@ -7906,7 +7979,7 @@ One deficiency of this program is that it does not process nested @code{@@include} statements (i.e., @code{@@include} statements in included files) the way a true macro preprocessor would. -@xref{Igawk Program}, for a program +@DBXREF{Igawk Program} for a program that does handle nested @code{@@include} statements. @node Getline/Pipe @@ -8153,7 +8226,7 @@ Using @code{FILENAME} with @code{getline} is likely to be a source for confusion. @command{awk} opens a separate input stream from the current input file. However, by not using a variable, @code{$0} -and @code{NR} are still updated. If you're doing this, it's +and @code{NF} are still updated. If you're doing this, it's probably by accident, and you should reconsider what it is you're trying to accomplish. @@ -8205,7 +8278,7 @@ and whether the variant is standard or a @command{gawk} extension. Note: for each variant, @command{gawk} sets the @code{RT} predefined variable. @float Table,table-getline-variants -@caption{@code{getline} Variants and What They Set} +@caption{@code{getline} variants and what they set} @multitable @columnfractions .33 .38 .27 @headitem Variant @tab Effect @tab @command{awk} / @command{gawk} @item @code{getline} @tab Sets @code{$0}, @code{NF}, @code{FNR}, @code{NR}, and @code{RT} @tab @command{awk} @@ -8223,7 +8296,7 @@ Note: for each variant, @command{gawk} sets the @code{RT} predefined variable. @c ENDOFRANGE infir @node Read Timeout -@section Reading Input With A Timeout +@section Reading Input with a Timeout @cindex timeout, reading input @cindex differences in @command{awk} and @command{gawk}, read timeouts @@ -8231,7 +8304,7 @@ This @value{SECTION} describes a feature that is specific to @command{gawk}. You may specify a timeout in milliseconds for reading input from the keyboard, a pipe, or two-way communication, including TCP/IP sockets. This can be done -on a per input, command or connection basis, by setting a special element +on a per input, command, or connection basis, by setting a special element in the @code{PROCINFO} array (@pxref{Auto-set}): @example @@ -8296,7 +8369,7 @@ for the input to arrive: PROCINFO[Service, "READ_TIMEOUT"] = 1000 while ((Service |& getline) > 0) @{ print $0 - PROCINFO[S, "READ_TIMEOUT"] -= 100 + PROCINFO[Service, "READ_TIMEOUT"] -= 100 @} @end example @@ -8305,11 +8378,11 @@ You should not assume that the read operation will block exactly after the tenth record has been printed. It is possible that @command{gawk} will read and buffer more than one record's worth of data the first time. Because of this, changing the value -of timeout like in the above example is not very useful. +of timeout like in the preceding example is not very useful. @end quotation -If the @code{PROCINFO} element is not present and the environment -variable @env{GAWK_READ_TIMEOUT} exists, +If the @code{PROCINFO} element is not present and the +@env{GAWK_READ_TIMEOUT} environment variable exists, @command{gawk} uses its value to initialize the timeout value. The exclusive use of the environment variable to specify timeout has the disadvantage of not being able to control it @@ -8330,7 +8403,7 @@ or the attempt to open a FIFO special file for reading can block indefinitely until some other process opens it for writing. @node Command-line directories -@section Directories On The Command Line +@section Directories on the Command Line @cindex differences in @command{awk} and @command{gawk}, command-line directories @cindex directories, command-line @cindex command line, directories on @@ -8345,14 +8418,14 @@ command line, but otherwise ignores it. This makes it easier to use shell wildcards with your @command{awk} program: @example -$ @kbd{gawk -f whizprog.awk *} @ii{Directories could kill this progam} +$ @kbd{gawk -f whizprog.awk *} @ii{Directories could kill this program} @end example If either of the @option{--posix} or @option{--traditional} options is given, then @command{gawk} reverts to treating a directory on the command line as a fatal error. -@xref{Extension Sample Readdir}, for a way to treat directories +@DBXREF{Extension Sample Readdir} for a way to treat directories as usable data from an @command{awk} program. @node Input Summary @@ -8364,7 +8437,7 @@ Input is split into records based on the value of @code{RS}. The possibilities are as follows: @multitable @columnfractions .25 .35 .40 -@headitem Value of @code{RS} @tab Records are split on @tab @command{awk} / @command{gawk} +@headitem Value of @code{RS} @tab Records are split on @dots{} @tab @command{awk} / @command{gawk} @item Any single character @tab That character @tab @command{awk} @item The empty string (@code{""}) @tab Runs of two or more newlines @tab @command{awk} @item A regexp @tab Text that matches the regexp @tab @command{gawk} @@ -8379,7 +8452,7 @@ The possibilities are as follows: @item After splitting the input into records, @command{awk} further splits -the record into individual fields, named @code{$1}, @code{$2} and so +the record into individual fields, named @code{$1}, @code{$2}, and so on. @code{$0} is the whole record, and @code{NF} indicates how many fields there are. The default way to split fields is between whitespace characters. @@ -8393,7 +8466,7 @@ greater than @code{NF} creates the field and rebuilds the record, using thing. Decrementing @code{NF} throws away fields and rebuilds the record. @item -Field splitting is more complicated than record splitting. +Field splitting is more complicated than record splitting: @multitable @columnfractions .40 .45 .15 @headitem Field separator value @tab Fields are split @dots{} @tab @command{awk} / @command{gawk} @@ -8466,7 +8539,7 @@ The @code{print} statement is not limited when computing @emph{which} values to print. However, with two exceptions, you cannot specify @emph{how} to print them---how many columns, whether to use exponential notation or not, and so on. -(For the exceptions, @pxref{Output Separators}, and +(For the exceptions, @DBPXREF{Output Separators} and @ref{OFMT}.) For printing with specifications, you need the @code{printf} statement (@pxref{Printf}). @@ -8663,14 +8736,14 @@ separated by single spaces. However, this doesn't need to be the case; a single space is simply the default. Any string of characters may be used as the @dfn{output field separator} by setting the predefined variable @code{OFS}. The initial value of this variable -is the string @w{@code{" "}}---that is, a single space. +is the string @w{@code{" "}} (i.e., a single space). -The output from an entire @code{print} statement is called an -@dfn{output record}. Each @code{print} statement outputs one output -record, and then outputs a string called the @dfn{output record separator} -(or @code{ORS}). The initial -value of @code{ORS} is the string @code{"\n"}; i.e., a newline -character. Thus, each @code{print} statement normally makes a separate line. +The output from an entire @code{print} statement is called an @dfn{output +record}. Each @code{print} statement outputs one output record, and +then outputs a string called the @dfn{output record separator} (or +@code{ORS}). The initial value of @code{ORS} is the string @code{"\n"} +(i.e., a newline character). Thus, each @code{print} statement normally +makes a separate line. @cindex output, records @cindex output record separator, See @code{ORS} variable @@ -8693,27 +8766,27 @@ newline: $ @kbd{awk 'BEGIN @{ OFS = ";"; ORS = "\n\n" @}} > @kbd{@{ print $1, $2 @}' mail-list} @print{} Amelia;555-5553 -@print{} +@print{} @print{} Anthony;555-3412 -@print{} +@print{} @print{} Becky;555-7685 -@print{} +@print{} @print{} Bill;555-1675 -@print{} +@print{} @print{} Broderick;555-0542 -@print{} +@print{} @print{} Camilla;555-2912 -@print{} +@print{} @print{} Fabius;555-1234 -@print{} +@print{} @print{} Julie;555-6699 -@print{} +@print{} @print{} Martin;555-6480 -@print{} +@print{} @print{} Samuel;555-3430 -@print{} +@print{} @print{} Jean-Paul;555-2127 -@print{} +@print{} @end example If the value of @code{ORS} does not contain a newline, the program's output @@ -8794,7 +8867,7 @@ printf @var{format}, @var{item1}, @var{item2}, @dots{} @end example @noindent -As print @code{print}, the entire list of arguments may optionally be +As for @code{print}, the entire list of arguments may optionally be enclosed in parentheses. Here too, the parentheses are necessary if any of the item expressions use the @samp{>} relational operator; otherwise, it can be confused with an output redirection (@pxref{Redirection}). @@ -8827,7 +8900,7 @@ $ @kbd{awk 'BEGIN @{} @end example @noindent -Here, neither the @samp{+} nor the @samp{OUCH} appear in +Here, neither the @samp{+} nor the @samp{OUCH!} appear in the output message. @node Control Letters @@ -8871,7 +8944,7 @@ a single byte (0--255). @item @code{%d}, @code{%i} Print a decimal integer. The two control letters are equivalent. -(The @code{%i} specification is for compatibility with ISO C.) +(The @samp{%i} specification is for compatibility with ISO C.) @item @code{%e}, @code{%E} Print a number in scientific (exponential) notation; @@ -8886,7 +8959,7 @@ prints @samp{1.950e+03}, with a total of four significant figures, three of which follow the decimal point. (The @samp{4.3} represents two modifiers, discussed in the next @value{SUBSECTION}.) -@code{%E} uses @samp{E} instead of @samp{e} in the output. +@samp{%E} uses @samp{E} instead of @samp{e} in the output. @item @code{%f} Print a number in floating-point notation. @@ -8902,26 +8975,26 @@ which follow the decimal point. (The @samp{4.3} represents two modifiers, discussed in the next @value{SUBSECTION}.) -On systems supporting IEEE 754 floating point format, values +On systems supporting IEEE 754 floating-point format, values representing negative infinity are formatted as @samp{-inf} or @samp{-infinity}, and positive infinity as -@samp{inf} and @samp{infinity}. +@samp{inf} or @samp{infinity}. The special ``not a number'' value formats as @samp{-nan} or @samp{nan} (@pxref{Math Definitions}). @item @code{%F} -Like @code{%f} but the infinity and ``not a number'' values are spelled +Like @samp{%f} but the infinity and ``not a number'' values are spelled using uppercase letters. -The @code{%F} format is a POSIX extension to ISO C; not all systems -support it. On those that don't, @command{gawk} uses @code{%f} instead. +The @samp{%F} format is a POSIX extension to ISO C; not all systems +support it. On those that don't, @command{gawk} uses @samp{%f} instead. @item @code{%g}, @code{%G} Print a number in either scientific notation or in floating-point notation, whichever uses fewer characters; if the result is printed in -scientific notation, @code{%G} uses @samp{E} instead of @samp{e}. +scientific notation, @samp{%G} uses @samp{E} instead of @samp{e}. @item @code{%o} Print an unsigned octal integer @@ -8933,11 +9006,11 @@ Print a string. @item @code{%u} Print an unsigned decimal integer. (This format is of marginal use, because all numbers in @command{awk} -are floating-point; it is provided primarily for compatibility with C.) +are floating point; it is provided primarily for compatibility with C.) @item @code{%x}, @code{%X} Print an unsigned hexadecimal integer; -@code{%X} uses the letters @samp{A} through @samp{F} +@samp{%X} uses the letters @samp{A} through @samp{F} instead of @samp{a} through @samp{f} (@pxref{Nondecimal-numbers}). @@ -8952,7 +9025,7 @@ argument and it ignores any modifiers. @quotation NOTE When using the integer format-control letters for values that are outside the range of the widest C integer type, @command{gawk} switches to -the @code{%g} format specifier. If @option{--lint} is provided on the +the @samp{%g} format specifier. If @option{--lint} is provided on the command line (@pxref{Options}), @command{gawk} warns about this. Other versions of @command{awk} may print invalid values or do something else entirely. @@ -9001,7 +9074,7 @@ messages at runtime. which describes how and why to use positional specifiers. For now, we ignore them. -@item - +@item - (Minus) The minus sign, used before the width modifier (see later on in this list), says to left-justify @@ -9026,13 +9099,13 @@ says to always supply a sign for numeric conversions, even if the data to format is positive. The @samp{+} overrides the space modifier. @item # -Use an ``alternate form'' for certain control letters. -For @code{%o}, supply a leading zero. -For @code{%x} and @code{%X}, supply a leading @code{0x} or @samp{0X} for +Use an ``alternative form'' for certain control letters. +For @samp{%o}, supply a leading zero. +For @samp{%x} and @samp{%X}, supply a leading @samp{0x} or @samp{0X} for a nonzero result. -For @code{%e}, @code{%E}, @code{%f}, and @code{%F}, the result always +For @samp{%e}, @samp{%E}, @samp{%f}, and @samp{%F}, the result always contains a decimal point. -For @code{%g} and @code{%G}, trailing zeros are not removed from the result. +For @samp{%g} and @samp{%G}, trailing zeros are not removed from the result. @item 0 A leading @samp{0} (zero) acts as a flag indicating that output should be @@ -9043,7 +9116,7 @@ value to print. @item ' A single quote or apostrophe character is a POSIX extension to ISO C. -It indicates that the integer part of a floating point value, or the +It indicates that the integer part of a floating-point value, or the entire part of an integer decimal value, should have a thousands-separator character in it. This only works in locales that support such characters. For example: @@ -9124,7 +9197,7 @@ prints @samp{foob}. @end table The C library @code{printf}'s dynamic @var{width} and @var{prec} -capability (for example, @code{"%*.*s"}) is supported. Instead of +capability (e.g., @code{"%*.*s"}) is supported. Instead of supplying explicit @var{width} and/or @var{prec} values in the format string, they are passed in the argument list. For example: @@ -9224,7 +9297,7 @@ awk 'BEGIN @{ print "Name Number" @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example -The above example mixes @code{print} and @code{printf} statements in +The preceding example mixes @code{print} and @code{printf} statements in the same program. Using just @code{printf} statements can produce the same results: @@ -9371,7 +9444,7 @@ close(report) The @code{close()} function is called here because it's a good idea to close the pipe as soon as all the intended output has been sent to it. -@xref{Close Files And Pipes}, +@DBXREF{Close Files And Pipes} for more information. This example also illustrates the use of a variable to represent @@ -9395,9 +9468,9 @@ but subsidiary to, the @command{awk} program. This feature is a @command{gawk} extension, and is not available in POSIX @command{awk}. -@xref{Getline/Coprocess}, +@DBXREF{Getline/Coprocess} for a brief discussion. -@xref{Two-way I/O}, +@DBXREF{Two-way I/O} for a more complete discussion. @end table @@ -9421,7 +9494,7 @@ print "Avoid improbability generators" >> "guide.txt" @noindent This is indeed how redirections must be used from the shell. But in @command{awk}, it isn't necessary. In this kind of case, a program should -use @samp{>} for all the @code{print} statements, since the output file +use @samp{>} for all the @code{print} statements, because the output file is only opened once. (It happens that if you mix @samp{>} and @samp{>>} that output is produced in the expected order. However, mixing the operators for the same file is definitely poor style, and is confusing to readers @@ -9470,7 +9543,7 @@ The program builds up a list of command lines, using the @command{mv} utility to rename the files. It then sends the list to the shell for execution. -@xref{Shell Quoting}, for a function that can help in generating +@DBXREF{Shell Quoting} for a function that can help in generating command lines to be fed to the shell. @end sidebar @c ENDOFRANGE outre @@ -9535,7 +9608,7 @@ that happens, writing to the screen is not correct. In fact, if terminal at all. Then opening @file{/dev/tty} fails. -@command{gawk}, BWK @command{awk} and @command{mawk} provide +@command{gawk}, BWK @command{awk}, and @command{mawk} provide special @value{FN}s for accessing the three standard streams. If the @value{FN} matches one of these special names when @command{gawk} (or one of the others) redirects input or output, then it directly uses @@ -9578,7 +9651,7 @@ It is a common error to omit the quotes, which leads to confusing results. @command{gawk} does not treat these @value{FN}s as special when -in POSIX compatibility mode. However, since BWK @command{awk} +in POSIX-compatibility mode. However, because BWK @command{awk} supports them, @command{gawk} does support them even when invoked with the @option{--traditional} option (@pxref{Options}). @@ -9587,7 +9660,7 @@ invoked with the @option{--traditional} option (@pxref{Options}). @c STARTOFRANGE gfn @cindex @command{gawk}, file names in -Besides access to standard input, stanard output, and standard error, +Besides access to standard input, standard output, and standard error, @command{gawk} provides access to any open file descriptor. Additionally, there are special @value{FN}s reserved for TCP/IP networking. @@ -9636,7 +9709,7 @@ This is done using a special @value{FN} of the form: @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}} @end example -The @var{net-type} is one of @samp{inet}, @samp{inet4} or @samp{inet6}. +The @var{net-type} is one of @samp{inet}, @samp{inet4}, or @samp{inet6}. The @var{protocol} is one of @samp{tcp} or @samp{udp}, and the other fields represent the other essential pieces of information for making a networking connection. @@ -9825,7 +9898,7 @@ is not closed and released until @code{close()} is called or @command{awk} exits. @code{close()} silently does nothing if given an argument that -does not represent a file, pipe or coprocess that was opened with +does not represent a file, pipe, or coprocess that was opened with a redirection. In such a case, it returns a negative value, indicating an error. In addition, @command{gawk} sets @code{ERRNO} to a string indicating the error. @@ -9859,9 +9932,10 @@ which describes it in more detail and gives an example. @cindex Unix @command{awk}, @code{close()} function and In many older versions of Unix @command{awk}, the @code{close()} function -is actually a statement. It is a syntax error to try and use the return -value from @code{close()}: +is actually a statement. @value{DARKCORNER} +It is a syntax error to try and use the return +value from @code{close()}: @example command = "@dots{}" @@ -9924,11 +9998,11 @@ Output from both @code{print} and @code{printf} may be redirected to files, pipes, and coprocesses. @item -@command{gawk} provides special file names for access to standard input, -output and error, and for network communications. +@command{gawk} provides special @value{FN}s for access to standard input, +output, and error, and for network communications. @item -Use @code{close()} to close open file, pipe and coprocess redirections. +Use @code{close()} to close open file, pipe, and coprocess redirections. For coprocesses, it is possible to close only one direction of the communications. @@ -9996,7 +10070,7 @@ combinations of these with various operators. @end menu @node Values -@section Constants, Variables and Conversions +@section Constants, Variables, and Conversions Expressions are built up from values and the operations performed upon them. This @value{SECTION} describes the elementary objects @@ -10022,7 +10096,7 @@ string, and regular expression. Each is used in the appropriate context when you need a data value that isn't going to change. Numeric constants can -have different forms, but are stored identically internally. +have different forms, but are internally stored in an identical manner. @menu * Scalar Constants:: Numeric and string constants. @@ -10038,7 +10112,7 @@ have different forms, but are stored identically internally. A @dfn{numeric constant} stands for a number. This number can be an integer, a decimal fraction, or a number in scientific (exponential) notation.@footnote{The internal representation of all numbers, -including integers, uses double precision floating-point numbers. +including integers, uses double-precision floating-point numbers. On most modern systems, these are in IEEE 754 standard format. @xref{Arbitrary Precision Arithmetic}, for much more information.} Here are some examples of numeric constants that all @@ -10052,7 +10126,7 @@ have the same value: @cindex string constants A string constant consists of a sequence of characters enclosed in -double-quotation marks. For example: +double quotation marks. For example: @example "parrot" @@ -10074,13 +10148,13 @@ implementations may have difficulty with some character codes. @cindex numbers, octal @cindex numbers, hexadecimal -In @command{awk}, all numbers are in decimal; i.e., base 10. Many other +In @command{awk}, all numbers are in decimal (i.e., base 10). Many other programming languages allow you to specify numbers in other bases, often octal (base 8) and hexadecimal (base 16). -In octal, the numbers go 0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, etc. +In octal, the numbers go 0, 1, 2, 3, 4, 5, 6, 7, 10, 11, 12, and so on. Just as @samp{11}, in decimal, is 1 times 10 plus 1, so @samp{11}, in octal, is 1 times 8, plus 1. This equals 9 in decimal. -In hexadecimal, there are 16 digits. Since the everyday decimal +In hexadecimal, there are 16 digits. Because the everyday decimal number system only has ten digits (@samp{0}--@samp{9}), the letters @samp{a} through @samp{f} are used to represent the rest. (Case in the letters is usually irrelevant; hexadecimal @samp{a} and @samp{A} @@ -10132,11 +10206,12 @@ you can use the @code{strtonum()} function to convert the data into a number. Most of the time, you will want to use octal or hexadecimal constants when working with the built-in bit manipulation functions; -see @ref{Bitwise Functions}, +see @DBREF{Bitwise Functions} for more information. -Unlike some early C implementations, @samp{8} and @samp{9} are not valid -in octal constants; e.g., @command{gawk} treats @samp{018} as decimal 18: +Unlike some early C implementations, @samp{8} and @samp{9} are not +valid in octal constants. For example, @command{gawk} treats @samp{018} +as decimal 18: @example $ @kbd{gawk 'BEGIN @{ print "021 is", 021 ; print 018 @}'} @@ -10193,7 +10268,7 @@ matched. However, regexp constants (such as @code{/foo/}) may be used like simple expressions. When a regexp constant appears by itself, it has the same meaning as if it appeared -in a pattern, i.e., @samp{($0 ~ /foo/)} +in a pattern (i.e., @samp{($0 ~ /foo/)}). @value{DARKCORNER} @xref{Expression Patterns}. This means that the following two code segments: @@ -10290,7 +10365,7 @@ either @code{sub()} or @code{gsub()}. However, what really happens is that the @code{pat} parameter is either one or zero, depending upon whether or not @code{$0} matches @code{/hi/}. @command{gawk} issues a warning when it sees a regexp constant used as -a parameter to a user-defined function, since passing a truth value in +a parameter to a user-defined function, because passing a truth value in this way is probably not what was intended. @c ENDOFRANGE rec @@ -10330,7 +10405,7 @@ variable's current value. Variables are given new values with @dfn{decrement operators}. @xref{Assignment Ops}. In addition, the @code{sub()} and @code{gsub()} functions can -change a variable's value, and the @code{match()}, @code{split()} +change a variable's value, and the @code{match()}, @code{split()}, and @code{patsplit()} functions can change the contents of their array parameters. @xref{String Functions}. @@ -10338,7 +10413,7 @@ array parameters. @xref{String Functions}. @cindex variables, initializing A few variables have special built-in meanings, such as @code{FS} (the field separator), and @code{NF} (the number of fields in the current input -record). @xref{Built-in Variables}, for a list of the predefined variables. +record). @DBXREF{Built-in Variables} for a list of the predefined variables. These predefined variables can be used and assigned just like all other variables, but their values are also used or changed automatically by @command{awk}. All predefined variables' names are entirely uppercase. @@ -10379,7 +10454,7 @@ as in the following: the variable is set at the very beginning, even before the @code{BEGIN} rules execute. The @option{-v} option and its assignment must precede all the @value{FN} arguments, as well as the program text. -(@xref{Options}, for more information about +(@DBXREF{Options} for more information about the @option{-v} option.) Otherwise, the variable assignment is performed at a time determined by its position among the input file arguments---after the processing of the @@ -10419,7 +10494,7 @@ sequences @node Conversion @subsection Conversion of Strings and Numbers -Number to string and string to number conversion are generally +Number-to-string and string-to-number conversion are generally straightforward. There can be subtleties to be aware of; this @value{SECTION} discusses this important facet of @command{awk}. @@ -10430,7 +10505,7 @@ this @value{SECTION} discusses this important facet of @command{awk}. @end menu @node Strings And Numbers -@subsubsection How @command{awk} Converts Between Strings And Numbers +@subsubsection How @command{awk} Converts Between Strings and Numbers @cindex converting, strings to numbers @cindex strings, converting @@ -10461,7 +10536,7 @@ string, concatenate that number with the empty string, @code{""}. To force a string to be converted to a number, add zero to that string. A string is converted to a number by interpreting any numeric prefix of the string as numerals: -@code{"2.5"} converts to 2.5, @code{"1e3"} converts to 1000, and @code{"25fix"} +@code{"2.5"} converts to 2.5, @code{"1e3"} converts to 1,000, and @code{"25fix"} has a numeric value of 25. Strings that can't be interpreted as valid numbers convert to zero. @@ -10501,7 +10576,7 @@ b = a "" @code{b} has the value @code{"12"}, not @code{"12.00"}. @value{DARKCORNER} -@sidebar Pre-POSIX @command{awk} Used @code{OFMT} For String Conversion +@sidebar Pre-POSIX @command{awk} Used @code{OFMT} for String Conversion @cindex POSIX @command{awk}, @code{OFMT} variable and @cindex @code{OFMT} variable @cindex portability, new @command{awk} vs.@: old @command{awk} @@ -10513,7 +10588,7 @@ specifies the output format to use when printing numbers with @code{print}. conversion from the semantics of printing. Both @code{CONVFMT} and @code{OFMT} have the same default value: @code{"%.6g"}. In the vast majority of cases, old @command{awk} programs do not change their behavior. -@xref{Print}, for more information on the @code{print} statement. +@DBXREF{Print} for more information on the @code{print} statement. @end sidebar @node Locale influences conversions @@ -10535,7 +10610,7 @@ The POSIX standard says that @command{awk} always uses the period as the decimal point when reading the @command{awk} program source code, and for command-line variable assignments (@pxref{Other Arguments}). However, when interpreting input data, for @code{print} and @code{printf} output, -and for number to string conversion, the local decimal point character +and for number-to-string conversion, the local decimal point character is used. @value{DARKCORNER} In all cases, numbers in source code and in input data cannot have a thousands separator. Here are some examples indicating the difference in behavior, on a GNU/Linux system: @@ -10560,7 +10635,7 @@ as the full number including the fractional part, 4.321. Some earlier versions of @command{gawk} fully complied with this aspect of the standard. However, many users in non-English locales complained -about this behavior, since their data used a period as the decimal +about this behavior, because their data used a period as the decimal point, so the default behavior was restored to use a period as the decimal point character. You can use the @option{--use-lc-numeric} option (@pxref{Options}) to force @command{gawk} to use the locale's @@ -10573,7 +10648,7 @@ point character is used and when a period is used. Some of these features have not been described yet. @float Table,table-locale-affects -@caption{Locale Decimal Point versus A Period} +@caption{Locale decimal point versus a period} @multitable @columnfractions .15 .20 .45 @headitem Feature @tab Default @tab @option{--posix} or @option{--use-lc-numeric} @item @code{%'g} @tab Use locale @tab Use locale @@ -10583,13 +10658,13 @@ features have not been described yet. @end multitable @end float -Finally, modern day formal standards and IEEE standard floating point +Finally, modern day formal standards and IEEE standard floating-point representation can have an unusual but important effect on the way @command{gawk} converts some special string values to numbers. The details are presented in @ref{POSIX Floating Point Problems}. @node All Operators -@section Operators: Doing Something With Values +@section Operators: Doing Something with Values This @value{SECTION} introduces the @dfn{operators} which make use of the values provided by constants and variables. @@ -10668,7 +10743,7 @@ Multiplication. Division; because all numbers in @command{awk} are floating-point numbers, the result is @emph{not} rounded to an integer---@samp{3 / 4} has the value 0.75. (It is a common mistake, especially for C programmers, -to forget that @emph{all} numbers in @command{awk} are floating-point, +to forget that @emph{all} numbers in @command{awk} are floating point, and that division of integer-looking constants produces a real number, not an integer.) @@ -10753,7 +10828,7 @@ $ @kbd{awk '@{ print "Field number one:" $1 @}' mail-list} @cindex troubleshooting, string concatenation Because string concatenation does not have an explicit operator, it is -often necessary to insure that it happens at the right time by using +often necessary to ensure that it happens at the right time by using parentheses to enclose the items to concatenate. For example, you might expect that the following code fragment concatenates @code{file} and @code{name}: @@ -11015,7 +11090,14 @@ The indices of @code{bar} are practically guaranteed to be different, because @code{rand()} returns different values each time it is called. (Arrays and the @code{rand()} function haven't been covered yet. @xref{Arrays}, -and see @ref{Numeric Functions}, for more information). +and +@ifnotdocbook +@DBPXREF{Numeric Functions} +@end ifnotdocbook +@ifdocbook +@DBREF{Numeric Functions} +@end ifdocbook +for more information). This example illustrates an important fact about assignment operators: the lefthand expression is only evaluated @emph{once}. @@ -11048,20 +11130,20 @@ to a number. @cindex @code{*} (asterisk), @code{**=} operator @cindex asterisk (@code{*}), @code{**=} operator @float Table,table-assign-ops -@caption{Arithmetic Assignment Operators} +@caption{Arithmetic assignment operators} @multitable @columnfractions .30 .70 @headitem Operator @tab Effect -@item @var{lvalue} @code{+=} @var{increment} @tab Add @var{increment} to the value of @var{lvalue}. -@item @var{lvalue} @code{-=} @var{decrement} @tab Subtract @var{decrement} from the value of @var{lvalue}. -@item @var{lvalue} @code{*=} @var{coefficient} @tab Multiply the value of @var{lvalue} by @var{coefficient}. -@item @var{lvalue} @code{/=} @var{divisor} @tab Divide the value of @var{lvalue} by @var{divisor}. -@item @var{lvalue} @code{%=} @var{modulus} @tab Set @var{lvalue} to its remainder by @var{modulus}. +@item @var{lvalue} @code{+=} @var{increment} @tab Add @var{increment} to the value of @var{lvalue} +@item @var{lvalue} @code{-=} @var{decrement} @tab Subtract @var{decrement} from the value of @var{lvalue} +@item @var{lvalue} @code{*=} @var{coefficient} @tab Multiply the value of @var{lvalue} by @var{coefficient} +@item @var{lvalue} @code{/=} @var{divisor} @tab Divide the value of @var{lvalue} by @var{divisor} +@item @var{lvalue} @code{%=} @var{modulus} @tab Set @var{lvalue} to its remainder by @var{modulus} @cindex common extensions, @code{**=} operator @cindex extensions, common@comma{} @code{**=} operator @cindex @command{awk} language, POSIX version @cindex POSIX @command{awk} @item @var{lvalue} @code{^=} @var{power} @tab -@item @var{lvalue} @code{**=} @var{power} @tab Raise @var{lvalue} to the power @var{power}. @value{COMMONEXT} +@item @var{lvalue} @code{**=} @var{power} @tab Raise @var{lvalue} to the power @var{power} @value{COMMONEXT} @end multitable @end float @@ -11092,7 +11174,7 @@ This is most notable in some commercial @command{awk} versions. For example: @example -$ awk /==/ /dev/null +$ @kbd{awk /==/ /dev/null} @error{} awk: syntax error at source line 1 @error{} context is @error{} >>> /= <<< @@ -11144,7 +11226,7 @@ but with the side effect of incrementing it. The post-increment @samp{foo++} is nearly the same as writing @samp{(foo += 1) - 1}. It is not perfectly equivalent because all numbers in -@command{awk} are floating-point---in floating-point, @samp{foo + 1 - 1} does +@command{awk} are floating point---in floating point, @samp{foo + 1 - 1} does not necessarily equal @code{foo}. But the difference is minute as long as you stick to numbers that are fairly small (less than @iftex @@ -11249,8 +11331,8 @@ You should avoid such things in your own programs. @node Truth Values and Conditions @section Truth Values and Conditions -In certain contexts, expression values also serve as ``truth values;'' i.e., -they determine what should happen next as the program runs. This +In certain contexts, expression values also serve as ``truth values''; (i.e., +they determine what should happen next as the program runs). This @value{SECTION} describes how @command{awk} defines ``true'' and ``false'' and how values are compared. @@ -11306,7 +11388,7 @@ the string constant @code{"0"} is actually true, because it is non-null. @subsection Variable Typing and Comparison Expressions @quotation @i{The Guide is definitive. Reality is frequently inaccurate.} -@author The Hitchhiker's Guide to the Galaxy +@author Douglas Adams, @cite{The Hitchhiker's Guide to the Galaxy} @end quotation @c STARTOFRANGE comex @@ -11334,7 +11416,7 @@ compares variables. @end menu @node Variable Typing -@subsubsection String Type Versus Numeric Type +@subsubsection String Type versus Numeric Type @cindex numeric, strings @cindex strings, numeric @@ -11360,7 +11442,7 @@ attribute. @item Fields, @code{getline} input, @code{FILENAME}, @code{ARGV} elements, @code{ENVIRON} elements, and the elements of an array created by -@code{match()}, @code{split()} and @code{patsplit()} that are numeric +@code{match()}, @code{split()}, and @code{patsplit()} that are numeric strings have the @var{strnum} attribute. Otherwise, they have the @var{string} attribute. Uninitialized variables also have the @var{strnum} attribute. @@ -11561,18 +11643,18 @@ operators}, which are a superset of those in C. @cindex exclamation point (@code{!}), @code{!~} operator @cindex @code{in} operator @float Table,table-relational-ops -@caption{Relational Operators} +@caption{Relational operators} @multitable @columnfractions .25 .75 @headitem Expression @tab Result -@item @var{x} @code{<} @var{y} @tab True if @var{x} is less than @var{y}. -@item @var{x} @code{<=} @var{y} @tab True if @var{x} is less than or equal to @var{y}. -@item @var{x} @code{>} @var{y} @tab True if @var{x} is greater than @var{y}. -@item @var{x} @code{>=} @var{y} @tab True if @var{x} is greater than or equal to @var{y}. -@item @var{x} @code{==} @var{y} @tab True if @var{x} is equal to @var{y}. -@item @var{x} @code{!=} @var{y} @tab True if @var{x} is not equal to @var{y}. -@item @var{x} @code{~} @var{y} @tab True if the string @var{x} matches the regexp denoted by @var{y}. -@item @var{x} @code{!~} @var{y} @tab True if the string @var{x} does not match the regexp denoted by @var{y}. -@item @var{subscript} @code{in} @var{array} @tab True if the array @var{array} has an element with the subscript @var{subscript}. +@item @var{x} @code{<} @var{y} @tab True if @var{x} is less than @var{y} +@item @var{x} @code{<=} @var{y} @tab True if @var{x} is less than or equal to @var{y} +@item @var{x} @code{>} @var{y} @tab True if @var{x} is greater than @var{y} +@item @var{x} @code{>=} @var{y} @tab True if @var{x} is greater than or equal to @var{y} +@item @var{x} @code{==} @var{y} @tab True if @var{x} is equal to @var{y} +@item @var{x} @code{!=} @var{y} @tab True if @var{x} is not equal to @var{y} +@item @var{x} @code{~} @var{y} @tab True if the string @var{x} matches the regexp denoted by @var{y} +@item @var{x} @code{!~} @var{y} @tab True if the string @var{x} does not match the regexp denoted by @var{y} +@item @var{subscript} @code{in} @var{array} @tab True if the array @var{array} has an element with the subscript @var{subscript} @end multitable @end float @@ -11610,24 +11692,24 @@ The following list of expressions illustrates the kinds of comparisons @table @code @item 1.5 <= 2.0 -numeric comparison (true) +Numeric comparison (true) @item "abc" >= "xyz" -string comparison (false) +String comparison (false) @item 1.5 != " +2" -string comparison (true) +String comparison (true) @item "1e2" < "3" -string comparison (true) +String comparison (true) @item a = 2; b = "2" @itemx a == b -string comparison (true) +String comparison (true) @item a = 2; b = " +2" @itemx a == b -string comparison (false) +String comparison (false) @end table In this example: @@ -11680,7 +11762,7 @@ dynamic regexp (@pxref{Regexp Usage}; also @cindex @command{awk}, regexp constants and @cindex regexp constants A constant regular -expression in slashes by itself is also an expression. The regexp +expression in slashes by itself is also an expression. @code{/@var{regexp}/} is an abbreviation for the following comparison expression: @example @@ -11694,7 +11776,7 @@ One special place where @code{/foo/} is @emph{not} an abbreviation for where this is discussed in more detail. @node POSIX String Comparison -@subsubsection String Comparison With POSIX Rules +@subsubsection String Comparison with POSIX Rules The POSIX standard says that string comparison is performed based on the locale's @dfn{collating order}. This is the order in which @@ -11950,13 +12032,13 @@ example, the function @code{sqrt()} computes the square root of a number. @cindex functions, built-in A fixed set of functions are @dfn{built-in}, which means they are available in every @command{awk} program. The @code{sqrt()} function is one -of these. @xref{Built-in}, for a list of built-in +of these. @DBXREF{Built-in} for a list of built-in functions and their descriptions. In addition, you can define functions for use in your program. -@xref{User-defined}, +@DBXREF{User-defined} for instructions on how to do this. Finally, @command{gawk} lets you write functions in C or C++ -that may be called from your program: see @ref{Dynamic Extensions}. +that may be called from your program (@pxref{Dynamic Extensions}). @cindex arguments, in function calls The way to use a function is with a @dfn{function call} expression, @@ -11975,7 +12057,7 @@ rand() @ii{no arguments} @cindex troubleshooting, function call syntax @quotation CAUTION -Do not put any space between the function name and the open-parenthesis! +Do not put any space between the function name and the opening parenthesis! A user-defined function name looks just like the name of a variable---a space would make the expression look like concatenation of a variable with an expression inside parentheses. @@ -11996,7 +12078,7 @@ Some of the built-in functions have one or more optional arguments. If those arguments are not supplied, the functions use a reasonable default value. -@xref{Built-in}, for full details. If arguments +@DBXREF{Built-in} for full details. If arguments are omitted in calls to user-defined functions, then those arguments are treated as local variables. Such local variables act like the empty string if referenced where a string value is required, @@ -12151,7 +12233,7 @@ Multiplication, division, remainder. @item @code{+ -} Addition, subtraction. -@item String Concatenation +@item String concatenation There is no special symbol for concatenation. The operands are simply written side by side (@pxref{Concatenation}). @@ -12190,7 +12272,7 @@ statements belong to the statement level, not to expressions. The redirection does not produce an expression that could be the operand of another operator. As a result, it does not make sense to use a redirection operator near another operator of lower precedence without -parentheses. Such combinations (for example, @samp{print foo > a ? b : c}), +parentheses. Such combinations (e.g., @samp{print foo > a ? b : c}), result in syntax errors. The correct way to write this statement is @samp{print foo > (a ? b : c)}. @@ -12248,7 +12330,7 @@ For maximum portability, do not use them. @c ENDOFRANGE oppr @node Locales -@section Where You Are Makes A Difference +@section Where You Are Makes a Difference @cindex locale, definition of Modern systems support the notion of @dfn{locales}: a way to tell the @@ -12268,8 +12350,8 @@ character}, to find the record terminator. Locales can affect how dates and times are formatted (@pxref{Time Functions}). For example, a common way to abbreviate the date September -4, 2015 in the United States is ``9/4/15.'' In many countries in -Europe, however, it is abbreviated ``4.9.15.'' Thus, the @code{%x} +4, 2015, in the United States is ``9/4/15.'' In many countries in +Europe, however, it is abbreviated ``4.9.15.'' Thus, the @samp{%x} specification in a @code{"US"} locale might produce @samp{9/4/15}, while in a @code{"EUROPE"} locale, it might produce @samp{4.9.15}. @@ -12287,13 +12369,13 @@ in @ref{Conversion}. @itemize @value{BULLET} @item Expressions are the basic elements of computation in programs. They are -built from constants, variables, function calls and combinations of the +built from constants, variables, function calls, and combinations of the various kinds of values with operators. @item @command{awk} supplies three kinds of constants: numeric, string, and regexp. @command{gawk} lets you specify numeric constants in octal -and hexadecimal (bases 8 and 16) in addition to decimal (base 10). +and hexadecimal (bases 8 and 16) as well as decimal (base 10). In certain contexts, a standalone regexp constant such as @code{/foo/} has the same meaning as @samp{$0 ~ /foo/}. @@ -12335,8 +12417,8 @@ or numeric). Function calls return a value which may be used as part of a larger expression. Expressions used to pass parameter values are fully evaluated before the function is called. @command{awk} provides -built-in and user-defined functions; this is described later on in this -@value{DOCUMENT}. +built-in and user-defined functions; this is described in +@ref{Functions}. @item Operator precedence specifies the order in which operations are performed, @@ -12496,9 +12578,8 @@ $ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @cindex regexp constants, as patterns @cindex patterns, regexp constants as -A regexp constant as a pattern is also a special case of an expression -pattern. The expression @samp{/li/} has the value one if @samp{li} -appears in the current input record. Thus, as a pattern, @samp{/li/} +pattern. The expression @code{/li/} has the value one if @samp{li} +appears in the current input record. Thus, as a pattern, @code{/li/} matches any record containing @samp{li}. @cindex Boolean expressions, as patterns @@ -12549,7 +12630,7 @@ The subexpressions of a Boolean operator in a pattern can be constant regular expressions, comparisons, or any other @command{awk} expressions. Range patterns are not expressions, so they cannot appear inside Boolean patterns. Likewise, the special patterns @code{BEGIN}, @code{END}, -@code{BEGINFILE} and @code{ENDFILE}, +@code{BEGINFILE}, and @code{ENDFILE}, which never match any input record, are not expressions and cannot appear inside Boolean patterns. @@ -12660,7 +12741,7 @@ They supply startup and cleanup actions for @command{awk} programs. @code{BEGIN} and @code{END} rules must have actions; there is no default action for these rules because there is no current record when they run. @code{BEGIN} and @code{END} rules are often referred to as -``@code{BEGIN} and @code{END} blocks'' by long-time @command{awk} +``@code{BEGIN} and @code{END} blocks'' by longtime @command{awk} programmers. @menu @@ -12691,7 +12772,7 @@ $ @kbd{awk '} This program finds the number of records in the input file @file{mail-list} that contain the string @samp{li}. The @code{BEGIN} rule prints a title for the report. There is no need to use the @code{BEGIN} rule to -initialize the counter @code{n} to zero, since @command{awk} does this +initialize the counter @code{n} to zero, as @command{awk} does this automatically (@pxref{Variables}). The second rule increments the variable @code{n} every time a record containing the pattern @samp{li} is read. The @code{END} rule @@ -12719,7 +12800,7 @@ The order in which library functions are named on the command line controls the order in which their @code{BEGIN} and @code{END} rules are executed. Therefore, you have to be careful when writing such rules in library files so that the order in which they are executed doesn't matter. -@xref{Options}, for more information on +@DBXREF{Options} for more information on using library functions. @xref{Library Functions}, for a number of useful library functions. @@ -12768,11 +12849,11 @@ of Unix @command{awk} do not. The third point follows from the first two. The meaning of @samp{print} inside a @code{BEGIN} or @code{END} rule is the same as always: @samp{print $0}. If @code{$0} is the null string, then this prints an -empty record. Many long time @command{awk} programmers use an unadorned +empty record. Many longtime @command{awk} programmers use an unadorned @samp{print} in @code{BEGIN} and @code{END} rules, to mean @samp{@w{print ""}}, relying on @code{$0} being null. Although one might generally get away with this in @code{BEGIN} rules, it is a very bad idea in @code{END} rules, -at least in @command{gawk}. It is also poor style, since if an empty +at least in @command{gawk}. It is also poor style, because if an empty line is needed in the output, the program should print one explicitly. @cindex @code{next} statement, @code{BEGIN}/@code{END} patterns and @@ -12782,9 +12863,14 @@ line is needed in the output, the program should print one explicitly. Finally, the @code{next} and @code{nextfile} statements are not allowed in a @code{BEGIN} rule, because the implicit read-a-record-and-match-against-the-rules loop has not started yet. Similarly, those statements -are not valid in an @code{END} rule, since all the input has been read. -(@xref{Next Statement}, and see -@ref{Nextfile Statement}.) +are not valid in an @code{END} rule, because all the input has been read. +(@DBXREF{Next Statement} and +@ifnotdocbook +@DBPXREF{Nextfile Statement}.) +@end ifnotdocbook +@ifdocbook +@DBREF{Nextfile Statement}.) +@end ifdocbook @c ENDOFRANGE beg @c ENDOFRANGE end @@ -12937,9 +13023,9 @@ awk "/$pattern/ "'@{ nmatches++ @} @noindent The @command{awk} program consists of two pieces of quoted text that are concatenated together to form the program. -The first part is double-quoted, which allows substitution of +The first part is double quoted, which allows substitution of the @code{pattern} shell variable inside the quotes. -The second part is single-quoted. +The second part is single quoted. Variable substitution via quoting works, but can be potentially messy. It requires a good understanding of the shell's quoting rules @@ -12968,7 +13054,7 @@ The assignment @samp{-v pat="$pattern"} still requires double quotes, in case there is whitespace in the value of @code{$pattern}. The @command{awk} variable @code{pat} could be named @code{pattern} too, but that would be more confusing. Using a variable also -provides more flexibility, since the variable can be used anywhere inside +provides more flexibility, as the variable can be used anywhere inside the program---for printing, as an array subscript, or for any other use---without requiring the quoting tricks at every point in the program. @@ -13041,7 +13127,7 @@ is used in order to put several statements together in the body of an Use the @code{getline} command (@pxref{Getline}). Also supplied in @command{awk} are the @code{next} -statement (@pxref{Next Statement}), +statement (@pxref{Next Statement}) and the @code{nextfile} statement (@pxref{Nextfile Statement}). @@ -13129,7 +13215,7 @@ else print "x is odd" @end example -In this example, if the expression @samp{x % 2 == 0} is true (that is, +In this example, if the expression @samp{x % 2 == 0} is true (i.e., if the value of @code{x} is evenly divisible by two), then the first @code{print} statement is executed; otherwise, the second @code{print} statement is executed. @@ -13208,7 +13294,7 @@ field is printed. Then the @samp{i++} increments the value of @code{i} and the loop repeats. The loop terminates when @code{i} reaches four. A newline is not required between the condition and the -body; however using one makes the program clearer unless the body is a +body; however, using one makes the program clearer unless the body is a compound statement or else is very simple. The newline after the open-brace that begins the compound statement is not required either, but the program is harder to read without it. @@ -13255,7 +13341,7 @@ The following is an example of a @code{do} statement: @noindent This program prints each input record 10 times. However, it isn't a very -realistic example, since in this case an ordinary @code{while} would do +realistic example, because in this case an ordinary @code{while} would do just as well. This situation reflects actual experience; only occasionally is there a real use for a @code{do} statement. @@ -13352,7 +13438,7 @@ very common in loops. It can be easier to think of this counting as part of looping rather than as something to do inside the loop. @cindex @code{in} operator -There is an alternate version of the @code{for} loop, for iterating over +There is an alternative version of the @code{for} loop, for iterating over all the indices of an array: @example @@ -13361,7 +13447,7 @@ for (i in array) @end example @noindent -@xref{Scanning an Array}, +@DBXREF{Scanning an Array} for more information on this version of the @code{for} loop. @node Switch Statement @@ -13381,7 +13467,7 @@ are checked for a match in the order they are defined. If no suitable Each @code{case} contains a single constant, be it numeric, string, or regexp. The @code{switch} expression is evaluated, and then each -@code{case}'s constant is compared against the result in turn. The type of constant +@code{case}'s constant is compared against the result in turn. The type of constant determines the comparison: numeric or string do the usual comparisons. A regexp constant does a regular expression match against the string value of the original expression. The general form of the @code{switch} @@ -13428,9 +13514,9 @@ while ((c = getopt(ARGC, ARGV, "aksx")) != -1) @{ @} @end example -Note that if none of the statements specified above halt execution +Note that if none of the statements specified here halt execution of a matched @code{case} statement, execution falls through to the -next @code{case} until execution halts. In the above example, the +next @code{case} until execution halts. In this example, the @code{case} for @code{"?"} falls through to the @code{default} case, which is to call a function named @code{usage()}. (The @code{getopt()} function being called here is @@ -13557,7 +13643,7 @@ BEGIN @{ @end example @noindent -This program loops forever once @code{x} reaches 5, since +This program loops forever once @code{x} reaches 5, because the increment (@samp{x++}) is never reached. @c @cindex @code{continue}, outside of loops @@ -13618,7 +13704,7 @@ Because of the @code{next} statement, the program's subsequent rules won't see the bad record. The error message is redirected to the standard error output stream, as error messages should be. -For more detail see +For more detail, see @ref{Special Files}. If the @code{next} statement causes the end of the input to be reached, @@ -13684,7 +13770,7 @@ rule to skip over a file that would otherwise cause @command{gawk} to exit with a fatal error. In this case, @code{ENDFILE} rules are not executed. @xref{BEGINFILE/ENDFILE}. -While one might think that @samp{close(FILENAME)} would accomplish +Although it might seem that @samp{close(FILENAME)} would accomplish the same as @code{nextfile}, this isn't true. @code{close()} is reserved for closing files, pipes, and coprocesses that are opened with redirections. It is not related to the main processing that @@ -13692,7 +13778,7 @@ opened with redirections. It is not related to the main processing that @quotation NOTE For many years, @code{nextfile} was a -common extension. In September, 2012, it was accepted for +common extension. In September 2012, it was accepted for inclusion into the POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=607, the Austin Group website}. @end quotation @@ -13741,7 +13827,7 @@ In such a case, if you don't want the @code{END} rule to do its job, set a variable to nonzero before the @code{exit} statement and check that variable in the @code{END} rule. -@xref{Assert Function}, +@DBXREF{Assert Function} for an example that does this. @cindex dark corner, @code{exit} statement @@ -13752,7 +13838,7 @@ In the case where an argument is supplied to a first @code{exit} statement, and then @code{exit} is called a second time from an @code{END} rule with no argument, @command{awk} uses the previously supplied exit value. @value{DARKCORNER} -@xref{Exit Status}, for more information. +@DBXREF{Exit Status} for more information. @cindex programming conventions, @code{exit} statement For example, suppose an error condition occurs that is difficult or @@ -13812,7 +13898,7 @@ their areas of activity. @end menu @node User-modified -@subsection Built-in Variables That Control @command{awk} +@subsection Built-In Variables That Control @command{awk} @c STARTOFRANGE bvaru @cindex predefined variables, user-modifiable @c STARTOFRANGE nmbv @@ -13869,7 +13955,7 @@ A space-separated list of columns that tells @command{gawk} how to split input with fixed columnar boundaries. Assigning a value to @code{FIELDWIDTHS} overrides the use of @code{FS} and @code{FPAT} for field splitting. -@xref{Constant Size}, for more information. +@DBXREF{Constant Size} for more information. @cindex @command{gawk}, @code{FPAT} variable in @cindex @code{FPAT} variable @@ -13881,7 +13967,7 @@ A regular expression (as a string) that tells @command{gawk} to create the fields based on text that matches the regular expression. Assigning a value to @code{FPAT} overrides the use of @code{FS} and @code{FIELDWIDTHS} for field splitting. -@xref{Splitting By Content}, for more information. +@DBXREF{Splitting By Content} for more information. @cindex @code{FS} variable @cindex separators, field @@ -13991,12 +14077,12 @@ character. (@xref{Output Separators}.) @cindex @code{PREC} variable @item PREC # -The working precision of arbitrary precision floating-point numbers, +The working precision of arbitrary-precision floating-point numbers, 53 bits by default (@pxref{Setting precision}). @cindex @code{ROUNDMODE} variable @item ROUNDMODE # -The rounding mode to use for arbitrary precision arithmetic on +The rounding mode to use for arbitrary-precision arithmetic on numbers, by default @code{"N"} (@samp{roundTiesToEven} in the IEEE 754 standard; @pxref{Setting the rounding mode}). @@ -14038,7 +14124,7 @@ really accesses @code{foo["A\034B"]} Used for internationalization of programs at the @command{awk} level. It sets the default text domain for specially marked string constants in the source text, as well as for the -@code{dcgettext()}, @code{dcngettext()} and @code{bindtextdomain()} functions +@code{dcgettext()}, @code{dcngettext()}, and @code{bindtextdomain()} functions (@pxref{Internationalization}). The default value of @code{TEXTDOMAIN} is @code{"messages"}. @end table @@ -14048,7 +14134,7 @@ The default value of @code{TEXTDOMAIN} is @code{"messages"}. @c ENDOFRANGE nmbv @node Auto-set -@subsection Built-in Variables That Convey Information +@subsection Built-In Variables That Convey Information @c STARTOFRANGE bvconi @cindex predefined variables, conveying information @@ -14061,7 +14147,7 @@ information to your program. The variables that are specific to @command{gawk} are marked with a pound sign (@samp{#}). These variables are @command{gawk} extensions. In other @command{awk} implementations or if @command{gawk} is in compatibility -mode (@pxref{Options}), they are not special. +mode (@pxref{Options}), they are not special: @c @asis for docbook @table @asis @@ -14102,7 +14188,7 @@ method of accessing command-line arguments. The value of @code{ARGV[0]} can vary from system to system. Also, you should note that the program text is @emph{not} included in @code{ARGV}, nor are any of @command{awk}'s command-line options. -@xref{ARGC and ARGV}, for information +@DBXREF{ARGC and ARGV} for information about how @command{awk} uses these variables. @value{DARKCORNER} @@ -14144,12 +14230,23 @@ that it creates. You should therefore be especially careful if you modify @code{ENVIRON["PATH"]"}, which is the search path for finding executable programs. +This can also affect the running @command{gawk} program, since some of the +built-in functions may pay attention to certain environment variables. +The most notable instance of this is @code{mktime()} (@pxref{Time +Functions}), which pays attention the value of the @env{TZ} environment +variable on many systems. + Some operating systems may not have environment variables. On such systems, the @code{ENVIRON} array is empty (except for @w{@code{ENVIRON["AWKPATH"]}} and @w{@code{ENVIRON["AWKLIBPATH"]}}; -@pxref{AWKPATH Variable}, and +@DBPXREF{AWKPATH Variable} and +@ifdocbook +@DBREF{AWKLIBPATH Variable}). +@end ifdocbook +@ifnotdocbook @pxref{AWKLIBPATH Variable}). +@end ifnotdocbook @cindex @command{gawk}, @code{ERRNO} variable in @cindex @code{ERRNO} variable @@ -14178,7 +14275,7 @@ The name of the current input file. When no @value{DF}s are listed on the command line, @command{awk} reads from the standard input and @code{FILENAME} is set to @code{"-"}. @code{FILENAME} changes each time a new file is read (@pxref{Reading Files}). Inside a @code{BEGIN} -rule, the value of @code{FILENAME} is @code{""}, since there are no input +rule, the value of @code{FILENAME} is @code{""}, because there are no input files being processed yet.@footnote{Some early implementations of Unix @command{awk} initialized @code{FILENAME} to @code{"-"}, even if there were @value{DF}s to be processed. This behavior was incorrect and should @@ -14210,7 +14307,7 @@ current record. @xref{Changing Fields}. @cindex differences in @command{awk} and @command{gawk}, @code{FUNCTAB} variable @item @code{FUNCTAB #} An array whose indices and corresponding values are the names of all -the built-in, user-defined and extension functions in the program. +the built-in, user-defined, and extension functions in the program. @quotation NOTE Attempting to use the @code{delete} statement with the @code{FUNCTAB} @@ -14304,7 +14401,7 @@ The parent process ID of the current process. If this element exists in @code{PROCINFO}, its value controls the order in which array indices will be processed by @samp{for (@var{indx} in @var{array})} loops. -Since this is an advanced feature, we defer the +This is an advanced feature, so we defer the full description until later; see @ref{Scanning an Array}. @@ -14324,10 +14421,10 @@ The version of @command{gawk}. The following additional elements in the array are available to provide information about the MPFR and GMP libraries -if your version of @command{gawk} supports arbitrary precision arithmetic -(@pxref{Arbitrary Precision Arithmetic}): +if your version of @command{gawk} supports arbitrary-precision arithmetic +(@pxref{Arbitrary Precision Arithmetic}): -@table @code +@table @code @cindex version of GNU MPFR library @item PROCINFO["mpfr_version"] The version of the GNU MPFR library. @@ -14375,7 +14472,7 @@ The @code{PROCINFO} array has the following additional uses: @item It may be used to provide a timeout when reading from any open input file, pipe, or coprocess. -@xref{Read Timeout}, for more information. +@DBXREF{Read Timeout} for more information. @item It may be used to cause coprocesses to communicate over pseudo-ttys @@ -14574,8 +14671,14 @@ use the @code{delete} statement to remove elements from All of these actions are typically done in the @code{BEGIN} rule, before actual processing of the input begins. -@xref{Split Program}, and see -@ref{Tee Program}, for examples +@DBXREF{Split Program} and +@ifnotdocbook +@DBPXREF{Tee Program} +@end ifnotdocbook +@ifdocbook +@DBREF{Tee Program} +@end ifdocbook +for examples of each way of removing elements from @code{ARGV}. To actually get options into an @command{awk} program, @@ -14587,7 +14690,7 @@ awk -f myprog.awk -- -v -q file1 file2 @dots{} @end example The following fragment processes @code{ARGV} in order to examine, and -then remove, the above command-line options: +then remove, the previously mentioned command-line options: @example BEGIN @{ @@ -14623,14 +14726,21 @@ gawk -f myprog.awk -q -v file1 file2 @dots{} @noindent Because @option{-q} is not a valid @command{gawk} option, it and the following @option{-v} are passed on to the @command{awk} program. -(@xref{Getopt Function}, for an @command{awk} library function that +(@DBXREF{Getopt Function} for an @command{awk} library function that parses command-line options.) When designing your program, you should choose options that don't -conflict with @command{gawk}'s, since it will process any options +conflict with @command{gawk}'s, because it will process any options that it accepts before passing the rest of the command line on to your program. Using @samp{#!} with the @option{-E} option may help -(@pxref{Executable Scripts}, and @pxref{Options}). +(@DBXREF{Executable Scripts} +and +@ifnotdocbook +@DBPXREF{Options}). +@end ifnotdocbook +@ifdocbook +@DBREF{Options}). +@end ifdocbook @node Pattern Action Summary @section Summary @@ -14796,7 +14906,7 @@ as shown in @inlineraw{docbook, <xref linkend="figure-array-elements"/>}: @ifnotdocbook @float Figure,figure-array-elements -@caption{A Contiguous Array} +@caption{A contiguous array} @ifinfo @center @image{array-elements, , , Basic Program Stages, txt} @end ifinfo @@ -14808,7 +14918,7 @@ as shown in @inlineraw{docbook, <xref linkend="figure-array-elements"/>}: @docbook <figure id="figure-array-elements" float="0"> -<title>A Contiguous Array</title> +<title>A contiguous array</title> <mediaobject> <imageobject role="web"><imagedata fileref="array-elements.png" format="PNG"/></imageobject> </mediaobject> @@ -14827,7 +14937,7 @@ position with zero elements before it. @cindex associative arrays @cindex arrays, associative Arrays in @command{awk} are different---they are @dfn{associative}. This means -that each array is a collection of pairs: an index and its corresponding +that each array is a collection of pairs---an index and its corresponding array element value: @ifnotdocbook @@ -15008,7 +15118,7 @@ numbers and strings as indices. There are some subtleties to how numbers work when used as array subscripts; this is discussed in more detail in @ref{Numeric Array Subscripts}.) -Here, the number @code{1} isn't double-quoted, since @command{awk} +Here, the number @code{1} isn't double quoted, because @command{awk} automatically converts it to a string. @cindex @command{gawk}, @code{IGNORECASE} variable in @@ -15093,7 +15203,7 @@ This expression tests whether the particular index @var{indx} exists, without the side effect of creating that element if it is not present. The expression has the value one (true) if @code{@var{array}[@var{indx}]} exists and zero (false) if it does not exist. -(We use @var{indx} here, since @samp{index} is the name of a built-in +(We use @var{indx} here, because @samp{index} is the name of a built-in function.) For example, this statement tests whether the array @code{frequencies} contains the index @samp{2}: @@ -15236,7 +15346,7 @@ the word as index. The second rule scans the elements of @code{used} to find all the distinct words that appear in the input. It prints each word that is more than 10 characters long and also prints the number of such words. -@xref{String Functions}, +@DBXREF{String Functions} for more information on the built-in function @code{length()}. @example @@ -15259,7 +15369,7 @@ END @{ @end example @noindent -@xref{Word Sorting}, +@DBXREF{Word Sorting} for a more detailed example of this type. @cindex arrays, elements, order of access by @code{in} operator @@ -15314,7 +15424,7 @@ $ @kbd{nawk -f loopcheck.awk} @end example @node Controlling Scanning -@subsection Using Predefined Array Scanning Orders With @command{gawk} +@subsection Using Predefined Array Scanning Orders with @command{gawk} This @value{SUBSECTION} describes a feature that is specific to @command{gawk}. @@ -15339,7 +15449,7 @@ We describe this now. @item Set @code{PROCINFO["sorted_in"]} to the name of a user-defined function to use for comparison of array elements. This advanced feature -is described later, in @ref{Array Sorting}. +is described later in @ref{Array Sorting}. @end itemize @cindex @code{PROCINFO}, values of @code{sorted_in} @@ -15357,7 +15467,7 @@ the index is @code{"10"} rather than numeric 10.) @item "@@ind_num_asc" Order by indices in ascending order but force them to be treated as numbers in the process. -Any index with a non-numeric value will end up positioned as if it were zero. +Any index with a non-numeric value will end up positioned as if it were zero. @item "@@val_type_asc" Order by element values in ascending order (rather than by indices). @@ -15369,11 +15479,11 @@ which in turn come before all subarrays. @pxref{Arrays of Arrays}.) @item "@@val_str_asc" -Order by element values in ascending order (rather than by indices). Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as strings. Subarrays, if present, come out last. @item "@@val_num_asc" -Order by element values in ascending order (rather than by indices). Scalar values are +Order by element values in ascending order (rather than by indices). Scalar values are compared as numbers. Subarrays, if present, come out last. When numeric values are equal, the string values are used to provide an ordering: this guarantees consistent results across different @@ -15434,11 +15544,11 @@ $ @kbd{gawk '} When sorting an array by element values, if a value happens to be a subarray then it is considered to be greater than any string or numeric value, regardless of what the subarray itself contains, -and all subarrays are treated as being equal to each other. Their +and all subarrays are treated as being equal to each other. Their order relative to each other is determined by their index strings. Here are some additional things to bear in mind about sorted -array traversal. +array traversal: @itemize @value{BULLET} @item @@ -15458,7 +15568,7 @@ if (save_sorted) @end example @item -As mentioned, the default array traversal order is represented by +As already mentioned, the default array traversal order is represented by @code{"@@unsorted"}. You can also get the default behavior by assigning the null string to @code{PROCINFO["sorted_in"]} or by just deleting the @code{"sorted_in"} element from the @code{PROCINFO} array with @@ -15503,7 +15613,7 @@ The program then changes the value of @code{CONVFMT}. The test @samp{(xyz in data)} generates a new string value from @code{xyz}---this time @code{"12.15"}---because the value of @code{CONVFMT} only allows two significant digits. This test fails, -since @code{"12.15"} is different from @code{"12.153"}. +because @code{"12.15"} is different from @code{"12.153"}. @cindex converting integer array subscripts @cindex integer array indices @@ -15521,19 +15631,19 @@ for (i = 1; i <= maxsub; i++) The ``integer values always convert to strings as integers'' rule has an additional consequence for array indexing. Octal and hexadecimal constants +@ifnotdocbook (@pxref{Nondecimal-numbers}) +@end ifnotdocbook +@ifdocbook +(covered in @ref{Nondecimal-numbers}) +@end ifdocbook are converted internally into numbers, and their original form -is forgotten. -This means, for example, that -@code{array[17]}, -@code{array[021]}, -and -@code{array[0x11]} -all refer to the same element! +is forgotten. This means, for example, that @code{array[17]}, +@code{array[021]}, and @code{array[0x11]} all refer to the same element! As with many things in @command{awk}, the majority of the time things work as you would expect them to. But it is useful to have a precise -knowledge of the actual rules since they can sometimes have a subtle +knowledge of the actual rules, as they can sometimes have a subtle effect on your programs. @node Uninitialized Subscripts @@ -15676,7 +15786,7 @@ by a number of other implementations. @cindex Brian Kernighan's @command{awk} @quotation NOTE For many years, using @code{delete} without a subscript was a common -extension. In September, 2012, it was accepted for inclusion into the +extension. In September 2012, it was accepted for inclusion into the POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=544, the Austin Group website}. @end quotation @@ -15718,7 +15828,7 @@ a = 3 @cindex subscripts in arrays, multidimensional @cindex arrays, multidimensional -A multidimensional array is an array in which an element is identified +A @dfn{multidimensional array} is an array in which an element is identified by a sequence of indices instead of a single index. For example, a two-dimensional array requires two indices. The usual way (in many languages, including @command{awk}) to refer to an element of a @@ -15760,7 +15870,7 @@ stored as @samp{foo["a@@b@@c"]}. @cindex @code{in} operator, index existence in multidimensional arrays To test whether a particular index sequence exists in a multidimensional array, use the same operator (@code{in}) that is -used for single dimensional arrays. Write the whole sequence of indices +used for single-dimensional arrays. Write the whole sequence of indices in parentheses, separated by commas, as the left operand: @example @@ -15884,7 +15994,7 @@ This simulates a true two-dimensional array. Each subarray element can contain another subarray as a value, which in turn can hold other arrays as well. In this way, you can create arrays of three or more dimensions. The indices can be any @command{awk} expression, including scalars -separated by commas (that is, a regular @command{awk} simulated +separated by commas (i.e., a regular @command{awk} simulated multidimensional subscript). So the following is valid in @command{gawk}: @@ -15902,8 +16012,8 @@ is itself an array and not a scalar: @example a[4] = "An element in a jagged array" @end example - -The terms @dfn{dimension}, @dfn{row} and @dfn{column} are + +The terms @dfn{dimension}, @dfn{row}, and @dfn{column} are meaningless when applied to such an array, but we will use ``dimension'' henceforth to imply the maximum number of indices needed to refer to an existing element. The @@ -15959,14 +16069,14 @@ The @samp{for (item in array)} statement (@pxref{Scanning an Array}) can be nested to scan all the elements of an array of arrays if it is rectangular in structure. In order to print the contents (scalar values) of a two-dimensional array of arrays -(i.e., in which each first-level element is itself an -array, not necessarily of the same length) +(i.e., in which each first-level element is itself an +array, not necessarily of the same length) you could use the following code: @example for (i in array) for (j in array[i]) - print array[i][j] + print array[i][j] @end example The @code{isarray()} function (@pxref{Type Functions}) @@ -15976,7 +16086,7 @@ lets you test if an array element is itself an array: for (i in array) @{ if (isarray(array[i]) @{ for (j in array[i]) @{ - print array[i][j] + print array[i][j] @} @} else @@ -15986,7 +16096,7 @@ for (i in array) @{ If the structure of a jagged array of arrays is known in advance, you can often devise workarounds using control statements. For example, -the following code prints the elements of our main array @code{a}: +the following code prints the elements of our main array @code{a}: @example for (i in a) @{ @@ -15996,13 +16106,13 @@ for (i in a) @{ print a[i][j][k] @} else print a[i][j] - @} + @} @} @end example @noindent -@xref{Walking Arrays}, for a user-defined function that ``walks'' an -arbitrarily-dimensioned array of arrays. +@DBXREF{Walking Arrays} for a user-defined function that ``walks'' an +arbitrarily dimensioned array of arrays. Recall that a reference to an uninitialized array element yields a value of @code{""}, the null string. This has one important implication when you @@ -16052,8 +16162,9 @@ special predefined values to @code{PROCINFO["sorted_in"]}. @item Use @samp{delete @var{array}[@var{indx}]} to delete an individual element. -You may also use @samp{delete @var{array}} to delete all of the elements -in the array. This latter feature has been a common extension for many +To delete all of the elements in an array, +use @samp{delete @var{array}}. +This latter feature has been a common extension for many years and is now standard, but may not be supported by all commercial versions of @command{awk}. @@ -16091,7 +16202,8 @@ This @value{CHAPTER} describes @command{awk}'s built-in functions, which fall into three categories: numeric, string, and I/O. @command{gawk} provides additional groups of functions to work with values that represent time, do -bit manipulation, sort arrays, and internationalize and localize programs. +bit manipulation, sort arrays, +provide type information, and internationalize and localize programs. Besides the built-in functions, @command{awk} has provisions for writing new functions that the rest of a program can use. @@ -16106,7 +16218,7 @@ The second half of this @value{CHAPTER} describes these @end menu @node Built-in -@section Built-in Functions +@section Built-In Functions @dfn{Built-in} functions are always available for your @command{awk} program to call. This @value{SECTION} defines all @@ -16129,7 +16241,7 @@ but are summarized here for your convenience. @end menu @node Calling Built-in -@subsection Calling Built-in Functions +@subsection Calling Built-In Functions To call one of @command{awk}'s built-in functions, write the name of the function followed @@ -16139,7 +16251,7 @@ is a call to the function @code{atan2()} and has two arguments. @cindex programming conventions, functions, calling @cindex whitespace, functions@comma{} calling Whitespace is ignored between the built-in function name and the -open parenthesis, but nonetheless it is good practice to avoid using whitespace +opening parenthesis, but nonetheless it is good practice to avoid using whitespace there. User-defined functions do not permit whitespace in this way, and it is easier to avoid mistakes by following a simple convention that always works---no whitespace after a function name. @@ -16176,7 +16288,7 @@ right to left. For example: @example i = 5 -j = atan2(i++, i *= 2) +j = atan2(++i, i *= 2) @end example If the order of evaluation is left to right, then @code{i} first becomes @@ -16236,7 +16348,6 @@ depends on your machine's floating-point representation. @cindex round to nearest integer Return the nearest integer to @var{x}, located between @var{x} and zero and truncated toward zero. - For example, @code{int(3)} is 3, @code{int(3.9)} is 3, @code{int(-3.9)} is @minus{}3, and @code{int(-3)} is @minus{}3 as well. @@ -16326,7 +16437,7 @@ for generating random numbers to the value @var{x}. Each seed value leads to a particular sequence of random numbers.@footnote{Computer-generated random numbers really are not truly random. They are technically known as ``pseudorandom.'' This means -that while the numbers in a sequence appear to be random, you can in +that although the numbers in a sequence appear to be random, you can in fact generate the same sequence of random numbers over and over again.} Thus, if the seed is set to the same value a second time, the same sequence of random numbers is produced again. @@ -16376,7 +16487,7 @@ doing index calculations, particularly if you are used to C. In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).} Several functions perform string substitution; the full discussion is provided in the description of the @code{sub()} function, which comes -towards the end since the list is presented alphabetically. +toward the end, because the list is presented alphabetically. Those functions that are specific to @command{gawk} are marked with a pound sign (@samp{#}). They are not available in compatibility mode @@ -16402,10 +16513,10 @@ These two functions are similar in behavior, so they are described together. @quotation NOTE -The following description ignores the third argument, @var{how}, since it +The following description ignores the third argument, @var{how}, as it requires understanding features that we have not discussed yet. Thus, the discussion here is a deliberate simplification. (We do provide all -the details later on: @xref{Array Sorting Functions}, for the full story.) +the details later on; see @DBREF{Array Sorting Functions} for the full story.) @end quotation Both functions return the number of elements in the array @var{source}. @@ -16652,7 +16763,7 @@ at which that substring begins (one, if it starts at the beginning of The @var{regexp} argument may be either a regexp constant (@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}). In the latter case, the string is treated as a regexp to be matched. -@xref{Computed Regexps}, for a +@DBXREF{Computed Regexps} for a discussion of the difference between the two forms, and the implications for writing your program correctly. @@ -16745,7 +16856,7 @@ $ @kbd{echo foooobazbarrrrr |} @end example There may not be subscripts for the start and index for every parenthesized -subexpression, since they may not all have matched text; thus they +subexpression, because they may not all have matched text; thus they should be tested for with the @code{in} operator (@pxref{Reference to Elements}). @@ -16792,15 +16903,15 @@ a regexp describing where to split @var{string} (much as @code{FS} can be a regexp describing where to split input records). If @var{fieldsep} is omitted, the value of @code{FS} is used. @code{split()} returns the number of elements created. -@var{seps} is a @command{gawk} extension with @code{@var{seps}[@var{i}]} +@var{seps} is a @command{gawk} extension with @code{@var{seps}[@var{i}]} being the separator string -between @code{@var{array}[@var{i}]} and @code{@var{array}[@var{i}+1]}. +between @code{@var{array}[@var{i}]} and @code{@var{array}[@var{i}+1]}. If @var{fieldsep} is a single -space then any leading whitespace goes into @code{@var{seps}[0]} and +space then any leading whitespace goes into @code{@var{seps}[0]} and any trailing -whitespace goes into @code{@var{seps}[@var{n}]} where @var{n} is the -return value of -@code{split()} (that is, the number of elements in @var{array}). +whitespace goes into @code{@var{seps}[@var{n}]} where @var{n} is the +return value of +@code{split()} (i.e., the number of elements in @var{array}). The @code{split()} function splits strings into pieces in a manner similar to the way input lines are split into fields. For example: @@ -16836,7 +16947,7 @@ As with input field-splitting, when the value of @var{fieldsep} is the elements of @var{array} but not in @var{seps}, and the elements are separated by runs of whitespace. -Also as with input field-splitting, if @var{fieldsep} is the null string, each +Also, as with input field-splitting, if @var{fieldsep} is the null string, each individual character in the string is split into its own array element. @value{COMMONEXT} @@ -16850,7 +16961,7 @@ the third argument to be a regexp constant (@code{/abc/}) as well as a string. @value{DARKCORNER} The POSIX standard allows this as well. -@xref{Computed Regexps}, for a +@DBXREF{Computed Regexps} for a discussion of the difference between using a string constant or a regexp constant, and the implications for writing your program correctly. @@ -16901,7 +17012,7 @@ Using the @code{strtonum()} function is @emph{not} the same as adding zero to a string value; the automatic coercion of strings to numbers works only for decimal data, not for octal or hexadecimal.@footnote{Unless you use the @option{--non-decimal-data} option, which isn't recommended. -@xref{Nondecimal Data}, for more information.} +@DBXREF{Nondecimal Data} for more information.} Note also that @code{strtonum()} uses the current locale's decimal point for recognizing numbers (@pxref{Locales}). @@ -16919,7 +17030,7 @@ Return the number of substitutions made (zero or one). The @var{regexp} argument may be either a regexp constant (@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}). In the latter case, the string is treated as a regexp to be matched. -@xref{Computed Regexps}, for a +@DBXREF{Computed Regexps} for a discussion of the difference between the two forms, and the implications for writing your program correctly. @@ -17105,7 +17216,7 @@ Although this makes a certain amount of sense, it can be surprising. @node Gory Details -@subsubsection More About @samp{\} and @samp{&} with @code{sub()}, @code{gsub()}, and @code{gensub()} +@subsubsection More about @samp{\} and @samp{&} with @code{sub()}, @code{gsub()}, and @code{gensub()} @cindex escape processing, @code{gsub()}/@code{gensub()}/@code{sub()} functions @cindex @code{sub()} function, escape processing @@ -17152,7 +17263,7 @@ through unchanged. This is illustrated in @ref{table-sub-escapes}. @c Thank to Karl Berry for help with the TeX stuff. @float Table,table-sub-escapes -@caption{Historical Escape Sequence Processing for @code{sub()} and @code{gsub()}} +@caption{Historical escape sequence processing for @code{sub()} and @code{gsub()}} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -17224,7 +17335,7 @@ This is shown in @ref{table-sub-proposed}. @float Table,table-sub-proposed -@caption{GNU @command{awk} Rules For @code{sub()} And Backslash} +@caption{GNU @command{awk} rules for @code{sub()} and backslash} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -17287,7 +17398,7 @@ by anything else is not special; the @samp{\} is placed straight into the output These rules are presented in @ref{table-posix-sub}. @float Table,table-posix-sub -@caption{POSIX Rules For @code{sub()} And @code{gsub()}} +@caption{POSIX rules for @code{sub()} and @code{gsub()}} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -17336,12 +17447,12 @@ is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, -it continued to follow the proposed rules, since +it continued to follow the proposed rules, as that had been its behavior for many years. When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer made the POSIX rules the default, breaking well over a decade's worth -of backwards compatibility.@footnote{This was rather naive of him, despite +of backward compatibility.@footnote{This was rather naive of him, despite there being a note in this section indicating that the next major version would move to the POSIX rules.} Needless to say, this was a bad idea, and as of @value{PVERSION} 4.0.1, @command{gawk} resumed its historical @@ -17356,7 +17467,7 @@ appears in the generated text and the @samp{\} does not, as shown in @ref{table-gensub-escapes}. @float Table,table-gensub-escapes -@caption{Escape Sequence Processing For @code{gensub()}} +@caption{Escape sequence processing for @code{gensub()}} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -17423,7 +17534,7 @@ Optional parameters are enclosed in square brackets ([ ]): Close the file @var{filename} for input or output. Alternatively, the argument may be a shell command that was used for creating a coprocess, or for redirecting to or from a pipe; then the coprocess or pipe is closed. -@xref{Close Files And Pipes}, +@DBXREF{Close Files And Pipes} for more information. When closing a coprocess, it is occasionally useful to first close @@ -17447,13 +17558,13 @@ a pipe or coprocess. @cindex buffers, flushing @cindex output, buffering -Many utility programs @dfn{buffer} their output; i.e., they save information +Many utility programs @dfn{buffer} their output (i.e., they save information to write to a disk file or the screen in memory until there is enough -for it to be worthwhile to send the data to the output device. +for it to be worthwhile to send the data to the output device). This is often more efficient than writing every little bit of information as soon as it is ready. However, sometimes -it is necessary to force a program to @dfn{flush} its buffers; that is, -write the information to its destination, even if a buffer is not full. +it is necessary to force a program to @dfn{flush} its buffers (i.e., +write the information to its destination, even if a buffer is not full). This is the purpose of the @code{fflush()} function---@command{gawk} also buffers its output and the @code{fflush()} function forces @command{gawk} to flush its buffers. @@ -17461,11 +17572,11 @@ buffers its output and the @code{fflush()} function forces @cindex extensions, common@comma{} @code{fflush()} function @cindex Brian Kernighan's @command{awk} Brian Kernighan added @code{fflush()} to his @command{awk} in April -of 1992. For two decades, it was a common extension. In December, +1992. For two decades, it was a common extension. In December 2012, it was accepted for inclusion into the POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=634, the Austin Group website}. -POSIX standardizes @code{fflush()} as follows: If there +POSIX standardizes @code{fflush()} as follows: if there is no argument, or if the argument is the null string (@w{@code{""}}), then @command{awk} flushes the buffers for @emph{all} open output files and pipes. @@ -17497,6 +17608,49 @@ a file or pipe that was opened for reading (such as with @code{getline}), or if @var{filename} is not an open file, pipe, or coprocess. In such a case, @code{fflush()} returns @minus{}1, as well. +@sidebar Interactive Versus Noninteractive Buffering +@cindex buffering, interactive vs.@: noninteractive + +As a side point, buffering issues can be even more confusing, depending +upon whether your program is @dfn{interactive} (i.e., communicating +with a user sitting at a keyboard).@footnote{A program is interactive +if the standard output is connected to a terminal device. On modern +systems, this means your keyboard and screen.} + +@c Thanks to Walter.Mecky@dresdnerbank.de for this example, and for +@c motivating me to write this section. +Interactive programs generally @dfn{line buffer} their output (i.e., they +write out every line). Noninteractive programs wait until they have +a full buffer, which may be many lines of output. +Here is an example of the difference: + +@example +$ @kbd{awk '@{ print $1 + $2 @}'} +@kbd{1 1} +@print{} 2 +@kbd{2 3} +@print{} 5 +@kbd{Ctrl-d} +@end example + +@noindent +Each line of output is printed immediately. Compare that behavior +with this example: + +@example +$ @kbd{awk '@{ print $1 + $2 @}' | cat} +@kbd{1 1} +@kbd{2 3} +@kbd{Ctrl-d} +@print{} 2 +@print{} 5 +@end example + +@noindent +Here, no output is printed until after the @kbd{Ctrl-d} is typed, because +it is all buffered and sent down the pipe to @command{cat} in one shot. +@end sidebar + @item @code{system(@var{command})} @cindexawkfunc{system} @cindex invoke shell command @@ -17544,49 +17698,6 @@ When @option{--sandbox} is specified, the @code{system()} function is disabled @end table -@sidebar Interactive Versus Noninteractive Buffering -@cindex buffering, interactive vs.@: noninteractive - -As a side point, buffering issues can be even more confusing, depending -upon whether your program is @dfn{interactive}, i.e., communicating -with a user sitting at a keyboard.@footnote{A program is interactive -if the standard output is connected to a terminal device. On modern -systems, this means your keyboard and screen.} - -@c Thanks to Walter.Mecky@dresdnerbank.de for this example, and for -@c motivating me to write this section. -Interactive programs generally @dfn{line buffer} their output; i.e., they -write out every line. Noninteractive programs wait until they have -a full buffer, which may be many lines of output. -Here is an example of the difference: - -@example -$ @kbd{awk '@{ print $1 + $2 @}'} -@kbd{1 1} -@print{} 2 -@kbd{2 3} -@print{} 5 -@kbd{Ctrl-d} -@end example - -@noindent -Each line of output is printed immediately. Compare that behavior -with this example: - -@example -$ @kbd{awk '@{ print $1 + $2 @}' | cat} -@kbd{1 1} -@kbd{2 3} -@kbd{Ctrl-d} -@print{} 2 -@print{} 5 -@end example - -@noindent -Here, no output is printed until after the @kbd{Ctrl-d} is typed, because -it is all buffered and sent down the pipe to @command{cat} in one shot. -@end sidebar - @sidebar Controlling Output Buffering with @code{system()} @cindex buffers, flushing @cindex buffering, input/output @@ -17605,7 +17716,7 @@ system("") # flush output @command{gawk} treats this use of the @code{system()} function as a special case and is smart enough not to run a shell (or other command interpreter) with the empty command. Therefore, with @command{gawk}, this -idiom is not only useful, it is also efficient. While this method should work +idiom is not only useful, it is also efficient. Although this method should work with other @command{awk} implementations, it does not necessarily avoid starting an unnecessary shell. (Other implementations may only flush the buffer associated with the standard output and not necessarily @@ -17744,14 +17855,14 @@ Mean Time). Otherwise, the value is formatted for the local time zone. The @var{timestamp} is in the same format as the value returned by the @code{systime()} function. If no @var{timestamp} argument is supplied, @command{gawk} uses the current time of day as the timestamp. -If no @var{format} argument is supplied, @code{strftime()} uses +Without a @var{format} argument, @code{strftime()} uses the value of @code{PROCINFO["strftime"]} as the format string (@pxref{Built-in Variables}). The default string value is @code{@w{"%a %b %e %H:%M:%S %Z %Y"}}. This format string produces output that is equivalent to that of the @command{date} utility. You can assign a new value to @code{PROCINFO["strftime"]} to -change the default format; see below for the various format directives. +change the default format; see the following list for the various format directives. @item @code{systime()} @cindexgawkfunc{systime} @@ -17828,16 +17939,16 @@ This is the ISO 8601 date format. @item %g The year modulo 100 of the ISO 8601 week number, as a decimal number (00--99). -For example, January 1, 2012 is in week 53 of 2011. Thus, the year +For example, January 1, 2012, is in week 53 of 2011. Thus, the year of its ISO 8601 week number is 2011, even though its year is 2012. -Similarly, December 31, 2012 is in week 1 of 2013. Thus, the year +Similarly, December 31, 2012, is in week 1 of 2013. Thus, the year of its ISO week number is 2013, even though its year is 2012. @item %G The full year of the ISO week number, as a decimal number. @item %h -Equivalent to @code{%b}. +Equivalent to @samp{%b}. @item %H The hour (24-hour clock) as a decimal number (00--23). @@ -17906,7 +18017,7 @@ The locale's ``appropriate'' date representation. @item %X The locale's ``appropriate'' time representation. -(This is @code{%T} in the @code{"C"} locale.) +(This is @samp{%T} in the @code{"C"} locale.) @item %y The year modulo 100 as a decimal number (00--99). @@ -17926,8 +18037,8 @@ no time zone is determinable. @item %Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH @itemx %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy -``Alternate representations'' for the specifications -that use only the second letter (@code{%c}, @code{%C}, +``Alternative representations'' for the specifications +that use only the second letter (@samp{%c}, @samp{%C}, and so on).@footnote{If you don't understand any of this, don't worry about it; these facilities are meant to make it easier to ``internationalize'' programs. @@ -17939,7 +18050,7 @@ Other internationalization features are described in A literal @samp{%}. @end table -If a conversion specifier is not one of the above, the behavior is +If a conversion specifier is not one of those just listed, the behavior is undefined.@footnote{This is because ISO C leaves the behavior of the C version of @code{strftime()} undefined and @command{gawk} uses the system's version of @code{strftime()} if it's there. @@ -17966,11 +18077,11 @@ Single-digit numbers are padded with a space. @ignore @item %N The ``Emperor/Era'' name. -Equivalent to @code{%C}. +Equivalent to @samp{%C}. @item %o The ``Emperor/Era'' year. -Equivalent to @code{%y}. +Equivalent to @samp{%y}. @end ignore @item %s @@ -17983,7 +18094,7 @@ The date in VMS format (e.g., @samp{20-JUN-1991}). @end table @c ENDOFRANGE strf -Additionally, the alternate representations are recognized but their +Additionally, the alternative representations are recognized but their normal representations are used. @cindex @code{date} utility, POSIX @@ -17997,7 +18108,7 @@ interprets the current time according to the format specifiers in the string. For example: @example -$ date '+Today is %A, %B %d, %Y.' +$ @kbd{date '+Today is %A, %B %d, %Y.'} @print{} Today is Monday, September 22, 2014. @end example @@ -18061,8 +18172,10 @@ each successive pair of bits in the operands. Three common operations are bitwise AND, OR, and XOR. The operations are described in @ref{table-bitwise-ops}. +@c 11/2014: Postprocessing turns the docbook informaltable +@c into a table. Hurray for scripting! @float Table,table-bitwise-ops -@caption{Bitwise Operations} +@caption{Bitwise operations} @ifnottex @ifnotdocbook @display @@ -18230,7 +18343,7 @@ Return the value of @var{val}, shifted right by @var{count} bits. Return the bitwise XOR of the arguments. There must be at least two. @end table -For all of these functions, first the double precision floating-point value is +For all of these functions, first the double-precision floating-point value is converted to the widest C unsigned integer type, then the bitwise operation is performed. If the result cannot be represented exactly as a C @code{double}, leading nonzero bits are removed one by one until it can be represented @@ -18329,7 +18442,7 @@ Otherwise, a @code{"0"} is added. The value is then shifted right by one bit and the loop continues until there are no more 1 bits. -If the initial value is zero it returns a simple @code{"0"}. +If the initial value is zero, it returns a simple @code{"0"}. Otherwise, at the end, it pads the value with zeros to represent multiples of 8-bit quantities. This is typical in modern computers. @@ -18366,8 +18479,8 @@ an array or not. The second is inside the body of a user-defined function array or not. @quotation NOTE -Using @code{isarray()} at the global level to test -variables makes no sense. Since you are the one writing the program, you +Using @code{isarray()} at the global level to test +variables makes no sense. Because you are the one writing the program, you are supposed to know if your variables are arrays or not. And in fact, due to the way @command{gawk} works, if you pass the name of a variable that has not been previously used to @code{isarray()}, @command{gawk} @@ -18435,7 +18548,7 @@ The default value for @var{category} is @code{"LC_MESSAGES"}. Complicated @command{awk} programs can often be simplified by defining your own functions. User-defined functions can be called just like built-in ones (@pxref{Function Calls}), but it is up to you to define -them, i.e., to tell @command{awk} what they should do. +them (i.e., to tell @command{awk} what they should do). @menu * Definition Syntax:: How to write definitions and what they mean. @@ -18574,13 +18687,13 @@ func foo() @{ a = sqrt($1) ; print a @} @end example @noindent -Instead it defines a rule that, for each record, concatenates the value +Instead, it defines a rule that, for each record, concatenates the value of the variable @samp{func} with the return value of the function @samp{foo}. If the resulting string is non-null, the action is executed. This is probably not what is desired. (@command{awk} accepts this input as syntactically valid, because functions may be used before they are defined in @command{awk} programs.@footnote{This program won't actually run, -since @code{foo()} is undefined.}) +because @code{foo()} is undefined.}) @cindex portability, functions@comma{} defining To ensure that your @command{awk} programs are portable, always use the @@ -18651,7 +18764,7 @@ The following is an example of a recursive function. It takes a string as an input parameter and returns the string in backwards order. Recursive functions must always have a test that stops the recursion. In this case, the recursion terminates when the input string is -already empty. +already empty: @c 8/2014: Thanks to Mike Brennan for the improved formulation @cindex @code{rev()} user-defined function @@ -18699,7 +18812,7 @@ function ctime(ts, format) @end example You might think that @code{ctime()} could use @code{PROCINFO["strftime"]} -for its format string. That would be a mistake, since @code{ctime()} is +for its format string. That would be a mistake, because @code{ctime()} is supposed to return the time formatted in a standard fashion, and user-level code could have changed @code{PROCINFO["strftime"]}. @c ENDOFRANGE fdef @@ -18720,7 +18833,7 @@ the function. @end menu @node Calling A Function -@subsubsection Writing A Function Call +@subsubsection Writing a Function Call A function call consists of the function name followed by the arguments in parentheses. @command{awk} expressions are what you write in the @@ -18735,7 +18848,7 @@ foo(x y, "lose", 4 * z) @quotation CAUTION Whitespace characters (spaces and TABs) are not allowed -between the function name and the open-parenthesis of the argument list. +between the function name and the opening parenthesis of the argument list. If you write whitespace by mistake, @command{awk} might think that you mean to concatenate a variable with an expression in parentheses. However, it notices that you used a function name and not a variable name, and reports @@ -18775,7 +18888,7 @@ function foo(j) print "foo's i=" i @} -BEGIN @{ +BEGIN @{ i = 10 print "top's i=" i foo(0) @@ -18798,13 +18911,13 @@ top's i=3 @end example If you want @code{i} to be local to both @code{foo()} and @code{bar()} do as -follows (the extra-space before @code{i} is a coding convention to +follows (the extra space before @code{i} is a coding convention to indicate that @code{i} is a local variable, not an argument): @example function bar( i) @{ - for (i = 0; i < 3; i++) + for (i = 0; i < 3; i++) print "bar's i=" i @} @@ -18816,10 +18929,10 @@ function foo(j, i) print "foo's i=" i @} -BEGIN @{ +BEGIN @{ i = 10 print "top's i=" i - foo(0) + foo(0) print "top's i=" i @} @end example @@ -18878,21 +18991,16 @@ At level 2, index 2 is found in a @end example @node Pass By Value/Reference -@subsubsection Passing Function Arguments By Value Or By Reference +@subsubsection Passing Function Arguments by Value Or by Reference In @command{awk}, when you declare a function, there is no way to declare explicitly whether the arguments are passed @dfn{by value} or @dfn{by reference}. -Instead the passing convention is determined at runtime when +Instead, the passing convention is determined at runtime when the function is called according to the following rule: - -@itemize -@item -If the argument is an array variable, then it is passed by reference, -@item -Otherwise the argument is passed by value. -@end itemize +if the argument is an array variable, then it is passed by reference. +Otherwise, the argument is passed by value. @cindex call by value Passing an argument by value means that when a function is called, it @@ -18995,7 +19103,13 @@ If @option{--lint} is specified Some @command{awk} implementations generate a runtime error if you use either the @code{next} statement or the @code{nextfile} statement -(@pxref{Next Statement}, also @pxref{Nextfile Statement}) +(@pxref{Next Statement}, and +@ifdocbook +@ref{Nextfile Statement}) +@end ifdocbook +@ifnotdocbook +@pxref{Nextfile Statement}) +@end ifnotdocbook inside a user-defined function. @command{gawk} does not have this limitation. @c ENDOFRANGE fudc @@ -19051,8 +19165,8 @@ function maxelt(vec, i, ret) @noindent You call @code{maxelt()} with one argument, which is an array name. The local variables @code{i} and @code{ret} are not intended to be arguments; -while there is nothing to stop you from passing more than one argument -to @code{maxelt()}, the results would be strange. The extra space before +there is nothing to stop you from passing more than one argument +to @code{maxelt()} but the results would be strange. The extra space before @code{i} in the function parameter list indicates that @code{i} and @code{ret} are local variables. You should follow this convention when defining functions. @@ -19189,8 +19303,8 @@ variable as the @emph{name} of the function to call. @cindex indirect function calls, @code{@@}-notation @cindex function calls, indirect, @code{@@}-notation for The syntax is similar to that of a regular function call: an identifier -immediately followed by a left parenthesis, any arguments, and then -a closing right parenthesis, with the addition of a leading @samp{@@} +immediately followed by an opening parenthesis, any arguments, and then +a closing parenthesis, with the addition of a leading @samp{@@} character: @example @@ -19199,7 +19313,7 @@ result = @@the_func() # calls the sum() function @end example Here is a full program that processes the previously shown data, -using indirect function calls. +using indirect function calls: @example @c file eg/prog/indirectcall.awk @@ -19240,7 +19354,7 @@ function sum(first, last, ret, i) These two functions expect to work on fields; thus the parameters @code{first} and @code{last} indicate where in the fields to start and end. -Otherwise they perform the expected computations and are not unusual. +Otherwise they perform the expected computations and are not unusual: @example @c file eg/prog/indirectcall.awk @@ -19273,7 +19387,7 @@ saving it in @code{start}. The last part of the code loops through each function name (from @code{$2} up to the marker, @samp{data:}), calling the function named by the field. The indirect function call itself occurs as a parameter in the call to @code{printf}. -(The @code{printf} format string uses @code{%s} as the format specifier so that we +(The @code{printf} format string uses @samp{%s} as the format specifier so that we can use functions that return strings, as well as numbers. Note that the result from the indirect call is concatenated with the empty string, in order to force it to be a string value.) @@ -19285,11 +19399,11 @@ $ @kbd{gawk -f indirectcall.awk class_data1} @print{} Biology 101: @print{} sum: <352.8> @print{} average: <88.2> -@print{} +@print{} @print{} Chemistry 305: @print{} sum: <356.4> @print{} average: <89.1> -@print{} +@print{} @print{} English 401: @print{} sum: <376.1> @print{} average: <94.025> @@ -19411,7 +19525,7 @@ function do_sort(first, last, compare, data, i, retval) retval = data[1] for (i = 2; i in data; i++) retval = retval " " data[i] - + return retval @} @c endfile @@ -19457,13 +19571,13 @@ $ @kbd{gawk -f quicksort.awk -f indirectcall.awk class_data2} @print{} average: <88.2> @print{} sort: <78.5 87.0 92.4 94.9> @print{} rsort: <94.9 92.4 87.0 78.5> -@print{} +@print{} @print{} Chemistry 305: @print{} sum: <356.4> @print{} average: <89.1> @print{} sort: <75.2 88.2 94.7 98.3> @print{} rsort: <98.3 94.7 88.2 75.2> -@print{} +@print{} @print{} English 401: @print{} sum: <376.1> @print{} average: <94.025> @@ -19566,7 +19680,7 @@ functions. POSIX @command{awk} provides three kinds of built-in functions: numeric, string, and I/O. @command{gawk} provides functions that sort arrays, work with values representing time, do bit manipulation, determine variable -type (array vs.@: scalar), and internationalize and localize programs. +type (array versus scalar), and internationalize and localize programs. @command{gawk} also provides several extensions to some of standard functions, typically in the form of additional arguments. @@ -19622,7 +19736,7 @@ program. This is equivalent to function pointers in C and C++. @c ENDOFRANGE funcud @ifnotinfo -@part @value{PART2}Problem Solving With @command{awk} +@part @value{PART2}Problem Solving with @command{awk} @end ifnotinfo @ifdocbook @@ -19632,10 +19746,10 @@ It contains the following chapters: @itemize @value{BULLET} @item -@ref{Library Functions}. +@ref{Library Functions} @item -@ref{Sample Programs}. +@ref{Sample Programs} @end itemize @end ifdocbook @@ -19696,9 +19810,9 @@ and would like to contribute them to the @command{awk} user community, see @cindex portability, example programs The programs in this @value{CHAPTER} and in @ref{Sample Programs}, -freely use features that are @command{gawk}-specific. +freely use @command{gawk}-specific features. Rewriting these programs for different implementations of @command{awk} -is pretty straightforward. +is pretty straightforward: @itemize @value{BULLET} @item @@ -19768,7 +19882,7 @@ Library functions often need to have global variables that they can use to preserve state information between calls to the function---for example, @code{getopt()}'s variable @code{_opti} (@pxref{Getopt Function}). -Such variables are called @dfn{private}, since the only functions that need to +Such variables are called @dfn{private}, as the only functions that need to use them are the ones in the library. When writing a library function, you should try to choose names for your @@ -19790,10 +19904,10 @@ In addition, several of the library functions use a prefix that helps indicate what function or set of functions use the variables---for example, @code{_pw_byname()} in the user database routines (@pxref{Passwd Functions}). -This convention is recommended, since it even further decreases the +This convention is recommended, as it even further decreases the chance of inadvertent conflict among variable names. Note that this convention is used equally well for variable names and for private -function names.@footnote{While all the library routines could have +function names.@footnote{Although all the library routines could have been rewritten to use this convention, this was not done, in order to show how our own @command{awk} programming style has evolved and to provide some basis for this discussion.} @@ -19866,7 +19980,7 @@ programming use. @end menu @node Strtonum Function -@subsection Converting Strings To Numbers +@subsection Converting Strings to Numbers The @code{strtonum()} function (@pxref{String Functions}) is a @command{gawk} extension. The following function @@ -19934,7 +20048,7 @@ function mystrtonum(str, ret, n, i, k, c) # a[6] = "1.e3" # a[7] = "1.32" # a[8] = "1.32E2" -# +# # for (i = 1; i in a; i++) # print a[i], strtonum(a[i]), mystrtonum(a[i]) # @} @@ -19948,7 +20062,7 @@ string. It sets @code{k} to the index in @code{"1234567"} of the current octal digit. The return value will either be the same number as the digit, or zero if the character is not there, which will be true for a @samp{0}. -This is safe, since the regexp test in the @code{if} ensures that +This is safe, because the regexp test in the @code{if} ensures that only octal values are converted. Similar logic applies to the code that checks for and converts a @@ -20295,7 +20409,7 @@ is always 1. This means that on those systems, characters have numeric values from 128 to 255. Finally, large mainframe systems use the EBCDIC character set, which uses all 256 values. -While there are other character sets in use on some older systems, +There are other character sets in use on some older systems, but they are not really worth worrying about: @example @@ -20349,7 +20463,7 @@ Good function design is important; this function needs to be general but it should also have a reasonable default behavior. It is called with an array as well as the beginning and ending indices of the elements in the array to be merged. This assumes that the array indices are numeric---a reasonable -assumption since the array was likely created with @code{split()} +assumption, as the array was likely created with @code{split()} (@pxref{String Functions}): @cindex @code{join()} user-defined function @@ -20402,7 +20516,7 @@ more difficult than they really need to be.} The @code{systime()} and @code{strftime()} functions described in @DBREF{Time Functions} provide the minimum functionality necessary for dealing with the time of day -in human readable form. While @code{strftime()} is extensive, the control +in human-readable form. Although @code{strftime()} is extensive, the control formats are not necessarily easy to remember or intuitively obvious when reading a program. @@ -20493,7 +20607,7 @@ allowed the user to supply an optional timestamp value to use instead of the current time. @node Readfile Function -@subsection Reading A Whole File At Once +@subsection Reading a Whole File At Once Often, it is convenient to have the entire contents of a file available in memory as a single string. A straightforward but naive way to @@ -20553,7 +20667,7 @@ will never match if the file has contents. @command{gawk} reads data from the file into @code{tmp} attempting to match @code{RS}. The match fails after each read, but fails quickly, such that @command{gawk} fills @code{tmp} with the entire contents of the file. -(@xref{Records}, for information on @code{RT} and @code{RS}.) +(@DBXREF{Records} for information on @code{RT} and @code{RS}.) In the case that @code{file} is empty, the return value is the null string. Thus calling code may use something like: @@ -20571,7 +20685,7 @@ test would be @samp{contents == ""}. also reads an entire file into memory. @node Shell Quoting -@subsection Quoting Strings to Pass to The Shell +@subsection Quoting Strings to Pass to the Shell @c included by permission @ignore @@ -20613,7 +20727,7 @@ chmod -w file.flac Note the need for shell quoting. The function @code{shell_quote()} does it. @code{SINGLE} is the one-character string @code{"'"} and -@code{QSINGLE} is the three-character string @code{"\"'\""}. +@code{QSINGLE} is the three-character string @code{"\"'\""}: @example @c file eg/lib/shellquote.awk @@ -20673,7 +20787,7 @@ command-line @value{DF}s. @cindex files, managing, data file boundaries @cindex files, initialization and cleanup -The @code{BEGIN} and @code{END} rules are each executed exactly once at +The @code{BEGIN} and @code{END} rules are each executed exactly once, at the beginning and end of your @command{awk} program, respectively (@pxref{BEGIN/END}). We (the @command{gawk} authors) once had a user who mistakenly thought that the @@ -20745,7 +20859,7 @@ The following version solves the problem: @example @c file eg/lib/ftrans.awk -# ftrans.awk --- handle data file transitions +# ftrans.awk --- handle datafile transitions # # user supplies beginfile() and endfile() functions @c endfile @@ -20773,7 +20887,7 @@ END @{ endfile(_filename_) @} shows how this library function can be used and how it simplifies writing the main program. -@sidebar So Why Does @command{gawk} have @code{BEGINFILE} and @code{ENDFILE}? +@sidebar So Why Does @command{gawk} Have @code{BEGINFILE} and @code{ENDFILE}? You are probably wondering, if @code{beginfile()} and @code{endfile()} functions can do the job, why does @command{gawk} have @@ -20781,7 +20895,7 @@ functions can do the job, why does @command{gawk} have Good question. Normally, if @command{awk} cannot open a file, this causes an immediate fatal error. In this case, there is no way for a -user-defined function to deal with the problem, since the mechanism for +user-defined function to deal with the problem, as the mechanism for calling it relies on the file being open and at the first record. Thus, the main reason for @code{BEGINFILE} is to give you a ``hook'' to catch files that cannot be processed. @code{ENDFILE} exists for symmetry, @@ -20839,8 +20953,8 @@ The @code{rewind()} function relies on the @code{ARGIND} variable (@pxref{Auto-set}), which is specific to @command{gawk}. It also relies on the @code{nextfile} keyword (@pxref{Nextfile Statement}). Because of this, you should not call it from an @code{ENDFILE} rule. -(This isn't necessary anyway, since as soon as an @code{ENDFILE} rule -finishes @command{gawk} goes to the next file!) +(This isn't necessary anyway, because @command{gawk} goes to the next +file as soon as an @code{ENDFILE} rule finishes!) @node File Checking @subsection Checking for Readable @value{DDF}s @@ -20888,19 +21002,19 @@ BEGIN @{ @cindex troubleshooting, @code{getline} function This works, because the @code{getline} won't be fatal. Removing the element from @code{ARGV} with @code{delete} -skips the file (since it's no longer in the list). +skips the file (because it's no longer in the list). See also @ref{ARGC and ARGV}. -The regular expression check purposely does not use character classes +Because @command{awk} variable names only allow the English letters, +the regular expression check purposely does not use character classes such as @samp{[:alpha:]} and @samp{[:alnum:]} (@pxref{Bracket Expressions}) -since @command{awk} variable names only allow the English letters. @node Empty Files @subsection Checking for Zero-length Files All known @command{awk} implementations silently skip over zero-length files. -This is a by-product of @command{awk}'s implicit +This is a by-product of @command{awk}'s implicit read-a-record-and-match-against-the-rules loop: when @command{awk} tries to read a record from an empty file, it immediately receives an end of file indication, closes the file, and proceeds on to the next @@ -21036,12 +21150,12 @@ are left alone. @c STARTOFRANGE clibf @cindex functions, library, C library @cindex arguments, processing -Most utilities on POSIX compatible systems take options on +Most utilities on POSIX-compatible systems take options on the command line that can be used to change the way a program behaves. @command{awk} is an example of such a program (@pxref{Options}). -Often, options take @dfn{arguments}; i.e., data that the program needs to -correctly obey the command-line option. For example, @command{awk}'s +Often, options take @dfn{arguments} (i.e., data that the program needs to +correctly obey the command-line option). For example, @command{awk}'s @option{-F} option requires a string to use as the field separator. The first occurrence on the command line of either @option{--} or a string that does not begin with @samp{-} ends the options. @@ -21145,7 +21259,7 @@ necessary for accessing individual characters (@pxref{String Functions}).@footnote{This function was written before @command{gawk} acquired the ability to split strings into single characters using @code{""} as the separator. -We have left it alone, since using @code{substr()} is more portable.} +We have left it alone, as using @code{substr()} is more portable.} The discussion that follows walks through the code a bit at a time: @@ -21313,9 +21427,9 @@ next element in @code{argv}. If neither condition is true, then only on the next call to @code{getopt()}. The @code{BEGIN} rule initializes both @code{Opterr} and @code{Optind} to one. -@code{Opterr} is set to one, since the default behavior is for @code{getopt()} +@code{Opterr} is set to one, because the default behavior is for @code{getopt()} to print a diagnostic message upon seeing an invalid option. @code{Optind} -is set to one, since there's no reason to look at the program name, which is +is set to one, because there's no reason to look at the program name, which is in @code{ARGV[0]}: @example @@ -21365,16 +21479,22 @@ etc., as its own options. @quotation NOTE After @code{getopt()} is through, -user level code must clear out all the elements of @code{ARGV} from 1 +user-level code must clear out all the elements of @code{ARGV} from 1 to @code{Optind}, so that @command{awk} does not try to process the command-line options as @value{FN}s. @end quotation Using @samp{#!} with the @option{-E} option may help avoid conflicts between your program's options and @command{gawk}'s options, -since @option{-E} causes @command{gawk} to abandon processing of +as @option{-E} causes @command{gawk} to abandon processing of further options -(@pxref{Executable Scripts}, and @pxref{Options}). +(@DBPXREF{Executable Scripts} and +@ifnotdocbook +@pxref{Options}). +@end ifnotdocbook +@ifdocbook +@ref{Options}). +@end ifdocbook Several of the sample programs presented in @ref{Sample Programs}, @@ -21404,7 +21524,7 @@ However, because these are numbers, they do not provide very useful information to the average user. There needs to be some way to find the user information associated with the user and group ID numbers. This @value{SECTION} presents a suite of functions for retrieving information from the -user database. @xref{Group Functions}, +user database. @DBXREF{Group Functions} for a similar suite that retrieves information from the group database. @cindex @code{getpwent()} function (C library) @@ -21423,7 +21543,7 @@ The ``password'' comes from the original user database file, encrypted passwords (hence the name). @cindex @command{pwcat} program -While an @command{awk} program could simply read @file{/etc/passwd} +Although an @command{awk} program could simply read @file{/etc/passwd} directly, this file may not contain complete information about the system's set of users.@footnote{It is often the case that password information is stored in a network database.} To be sure you are able to @@ -21518,12 +21638,12 @@ The user's encrypted password. This may not be available on some systems. @item User-ID The user's numeric user ID number. -(On some systems it's a C @code{long}, and not an @code{int}. Thus +(On some systems, it's a C @code{long}, and not an @code{int}. Thus we cast it to @code{long} for all cases.) @item Group-ID The user's numeric group ID number. -(Similar comments about @code{long} vs.@: @code{int} apply here.) +(Similar comments about @code{long} versus @code{int} apply here.) @item Full name The user's full name, and perhaps other information associated with the @@ -21545,7 +21665,7 @@ A few lines representative of @command{pwcat}'s output are as follows: @cindex Robbins, Miriam @example $ @kbd{pwcat} -@print{} root:3Ov02d5VaUPB6:0:1:Operator:/:/bin/sh +@print{} root:x:0:1:Operator:/:/bin/sh @print{} nobody:*:65534:65534::/: @print{} daemon:*:1:1::/: @print{} sys:*:2:2::/:/bin/csh @@ -21624,7 +21744,7 @@ The function @code{_pw_init()} fills three copies of the user information into three associative arrays. The arrays are indexed by username (@code{_pw_byname}), by user ID number (@code{_pw_byuid}), and by order of occurrence (@code{_pw_bycount}). -The variable @code{_pw_inited} is used for efficiency, since @code{_pw_init()} +The variable @code{_pw_inited} is used for efficiency, as @code{_pw_init()} needs to be called only once. @cindex @code{PROCINFO} array, testing the field splitting @@ -21633,7 +21753,7 @@ Because this function uses @code{getline} to read information from @command{pwcat}, it first saves the values of @code{FS}, @code{RS}, and @code{$0}. It notes in the variable @code{using_fw} whether field splitting with @code{FIELDWIDTHS} is in effect or not. -Doing so is necessary, since these functions could be called +Doing so is necessary, as these functions could be called from anywhere within a user's program, and the user may have his or her own way of splitting records and fields. This makes it possible to restore the correct @@ -21735,7 +21855,7 @@ In turn, calling @code{_pw_init()} is not too expensive, because the once. If you are worried about squeezing every last cycle out of your @command{awk} program, the check of @code{_pw_inited} could be moved out of @code{_pw_init()} and duplicated in all the other functions. In practice, -this is not necessary, since most @command{awk} programs are I/O-bound, +this is not necessary, as most @command{awk} programs are I/O-bound, and such a change would clutter up the code. The @command{id} program in @DBREF{Id Program} @@ -21874,7 +21994,7 @@ the association of name to number must be unique within the file. we cast it to @code{long} for all cases.) @item Group Member List -A comma-separated list of user names. These users are members of the group. +A comma-separated list of usernames. These users are members of the group. Modern Unix systems allow users to be members of several groups simultaneously. If your system does, then there are elements @code{"group1"} through @code{"group@var{N}"} in @code{PROCINFO} @@ -21989,7 +22109,7 @@ is being used, and to restore the appropriate field splitting mechanism. The group information is stored is several associative arrays. The arrays are indexed by group name (@code{@w{_gr_byname}}), by group ID number (@code{@w{_gr_bygid}}), and by position in the database (@code{@w{_gr_bycount}}). -There is an additional array indexed by user name (@code{@w{_gr_groupsbyuser}}), +There is an additional array indexed by username (@code{@w{_gr_groupsbyuser}}), which is a space-separated list of groups to which each user belongs. Unlike the user database, it is possible to have multiple records in the @@ -22002,7 +22122,7 @@ tvpeople:*:101:david,conan,tom,joan @end example For this reason, @code{_gr_init()} looks to see if a group name or -group ID number is already seen. If it is, then the user names are +group ID number is already seen. If it is, the usernames are simply concatenated onto the previous list of users.@footnote{There is actually a subtle problem with the code just presented. Suppose that the first time there were no names. This code adds the names with @@ -22048,7 +22168,7 @@ function getgrgid(gid) @cindex @code{getgruser()} function (C library) The @code{getgruser()} function does not have a C counterpart. It takes a -user name and returns the list of groups that have the user as a member: +username and returns the list of groups that have the user as a member: @cindex @code{getgruser()} function, user-defined @example @@ -22191,7 +22311,7 @@ The functions presented here fit into the following categories: @c nested list @table @asis @item General problems -Number to string conversion, assertions, rounding, random number +Number-to-string conversion, assertions, rounding, random number generation, converting characters to numbers, joining strings, getting easily usable time-of-day information, and reading a whole file in one shot. @@ -22251,7 +22371,7 @@ ARGIND != Argind @{ @} END @{ if (ARGIND < ARGC - 1) - ARGIND = ARGC - 1 + ARGIND = ARGC - 1 if (ARGIND > Argind) for (Argind++; Argind <= ARGIND; Argind++) zerofile(ARGV[Argind], Argind) @@ -22387,7 +22507,7 @@ The programs are presented in alphabetical order. @end menu @node Cut Program -@subsection Cutting out Fields and Columns +@subsection Cutting Out Fields and Columns @cindex @command{cut} utility @c STARTOFRANGE cut @@ -22664,7 +22784,7 @@ function set_charlist( field, i, j, f, g, n, m, t, @c endfile @end example -Next is the rule that actually processes the data. If the @option{-s} option +Next is the rule that processes the data. If the @option{-s} option is given, then @code{suppress} is true. The first @code{if} statement makes sure that the input record does have the field separator. If @command{cut} is processing fields, @code{suppress} is true, and the field @@ -22696,9 +22816,9 @@ written out between the fields: @end example This version of @command{cut} relies on @command{gawk}'s @code{FIELDWIDTHS} -variable to do the character-based cutting. While it is possible in +variable to do the character-based cutting. It is possible in other @command{awk} implementations to use @code{substr()} -(@pxref{String Functions}), +(@pxref{String Functions}), but it is also extremely painful. The @code{FIELDWIDTHS} variable supplies an elegant solution to the problem of picking the input line apart by characters. @@ -22843,7 +22963,7 @@ matched lines in the output: @c endfile @end example -The last two lines are commented out, since they are not needed in +The last two lines are commented out, as they are not needed in @command{gawk}. They should be uncommented if you have to use another version of @command{awk}. @@ -22853,7 +22973,7 @@ into lowercase if the @option{-i} option is specified.@footnote{It also introduces a subtle bug; if a match happens, we output the translated line, not the original.} The rule is -commented out since it is not necessary with @command{gawk}: +commented out as it is not necessary with @command{gawk}: @example @c file eg/prog/egrep.awk @@ -22990,7 +23110,7 @@ function usage() @c ENDOFRANGE egrep @node Id Program -@subsection Printing out User Information +@subsection Printing Out User Information @cindex printing, user information @cindex users, information about, printing @@ -23105,7 +23225,7 @@ function pr_first_field(str, a) The test in the @code{for} loop is worth noting. Any supplementary groups in the @code{PROCINFO} array have the indices @code{"group1"} through @code{"group@var{N}"} for some -@var{N}, i.e., the total number of supplementary groups. +@var{N} (i.e., the total number of supplementary groups). However, we don't know in advance how many of these groups there are. @@ -23145,10 +23265,10 @@ aims to demonstrate.} By default, the output files are named @file{xaa}, @file{xab}, and so on. Each file has -1000 lines in it, with the likely exception of the last file. To change the +1,000 lines in it, with the likely exception of the last file. To change the number of lines in each file, supply a number on the command line -preceded with a minus; e.g., @samp{-500} for files with 500 lines in them -instead of 1000. To change the name of the output files to something like +preceded with a minus (e.g., @samp{-500} for files with 500 lines in them +instead of 1,000). To change the name of the output files to something like @file{myfileaa}, @file{myfileab}, and so on, supply an additional argument that specifies the @value{FN} prefix. @@ -23196,7 +23316,7 @@ BEGIN @{ @} # test argv in case reading from stdin instead of file if (i in ARGV) - i++ # skip data file name + i++ # skip datafile name if (i in ARGV) @{ outfile = ARGV[i] ARGV[i] = "" @@ -23290,8 +23410,8 @@ truncating them and starting over. The @code{BEGIN} rule first makes a copy of all the command-line arguments into an array named @code{copy}. -@code{ARGV[0]} is not copied, since it is not needed. -@code{tee} cannot use @code{ARGV} directly, since @command{awk} attempts to +@code{ARGV[0]} is not needed, so it is not copied. +@code{tee} cannot use @code{ARGV} directly, because @command{awk} attempts to process each @value{FN} in @code{ARGV} as input data. @cindex flag variables @@ -23340,7 +23460,7 @@ BEGIN @{ @c endfile @end example -The following single rule does all the work. Since there is no pattern, it is +The following single rule does all the work. Because there is no pattern, it is executed for each line of input. The body of the rule simply prints the line into each file on the command line, and then to the standard output: @@ -23371,7 +23491,7 @@ for (i in copy) @end example @noindent -This is more concise but it is also less efficient. The @samp{if} is +This is more concise, but it is also less efficient. The @samp{if} is tested for each record and for each output file. By duplicating the loop body, the @samp{if} is only tested once for each input record. If there are @var{N} input records and @var{M} output files, the first method only @@ -23591,10 +23711,10 @@ The second rule does the work. The variable @code{equal} is one or zero, depending upon the results of @code{are_equal()}'s comparison. If @command{uniq} is counting repeated lines, and the lines are equal, then it increments the @code{count} variable. Otherwise, it prints the line and resets @code{count}, -since the two lines are not equal. +because the two lines are not equal. If @command{uniq} is not counting, and if the lines are equal, @code{count} is incremented. -Nothing is printed, since the point is to remove duplicates. +Nothing is printed, as the point is to remove duplicates. Otherwise, if @command{uniq} is counting repeated lines and more than one line is seen, or if @command{uniq} is counting nonrepeated lines and only one line is seen, then the line is printed, and @code{count} @@ -23663,7 +23783,7 @@ Brian Kernighan suggests that ``an alternative approach to state machines is to just read the input into an array, then use indexing. It's almost always easier code, and for most inputs where you would use this, just -as fast.'' Consider how to rewrite the logic to follow this +as fast.'' Consider how to rewrite the logic to follow this suggestion. @end ifset @@ -23715,7 +23835,7 @@ Count only characters. @end table Implementing @command{wc} in @command{awk} is particularly elegant, -since @command{awk} does a lot of the work for us; it splits lines into +because @command{awk} does a lot of the work for us; it splits lines into words (i.e., fields) and counts them, it counts lines (i.e., records), and it can easily tell us how long a line is. @@ -23820,7 +23940,7 @@ function endfile(file) @end example There is one rule that is executed for each line. It adds the length of -the record, plus one, to @code{chars}.@footnote{Since @command{gawk} +the record, plus one, to @code{chars}.@footnote{Because @command{gawk} understands multibyte locales, this code counts characters, not bytes.} Adding one plus the record length is needed because the newline character separating records (the value @@ -24168,8 +24288,8 @@ often used to map uppercase letters into lowercase for further processing: @command{tr} requires two lists of characters.@footnote{On some older systems, including Solaris, the system version of @command{tr} may require that the lists be written as range expressions enclosed in square brackets -(@samp{[a-z]}) and quoted, to prevent the shell from attempting a file -name expansion. This is not a feature.} When processing the input, the +(@samp{[a-z]}) and quoted, to prevent the shell from attempting a +@value{FN} expansion. This is not a feature.} When processing the input, the first character in the first list is replaced with the first character in the second list, the second character in the first list is replaced with the second character in the second list, and so on. If there are @@ -24284,9 +24404,9 @@ BEGIN @{ @c endfile @end example -While it is possible to do character transliteration in a user-level -function, it is not necessarily efficient, and we (the @command{gawk} -authors) started to consider adding a built-in function. However, +It is possible to do character transliteration in a user-level +function, but it is not necessarily efficient, and we (the @command{gawk} +developers) started to consider adding a built-in function. However, shortly after writing this program, we learned that Brian Kernighan had added the @code{toupper()} and @code{tolower()} functions to his @command{awk} (@pxref{String Functions}). These functions handle the @@ -24330,7 +24450,7 @@ the @code{line} array and printing the page when 20 labels have been read. The @code{BEGIN} rule simply sets @code{RS} to the empty string, so that @command{awk} splits records at blank lines (@pxref{Records}). -It sets @code{MAXLINES} to 100, since 100 is the maximum number +It sets @code{MAXLINES} to 100, because 100 is the maximum number of lines on the page @iftex (@math{20 @cdot 5 = 100}). @@ -24487,9 +24607,9 @@ useful on real text files: @item The @command{awk} language considers upper- and lowercase characters to be distinct. Therefore, ``bartender'' and ``Bartender'' are not treated -as the same word. This is undesirable, since in normal text, words -are capitalized if they begin sentences, and a frequency analyzer should not -be sensitive to capitalization. +as the same word. This is undesirable, because words are capitalized +if they begin sentences in normal text, and a frequency analyzer should +not be sensitive to capitalization. @item Words are detected using the @command{awk} convention that fields are @@ -24531,8 +24651,8 @@ END @{ @} @end example -The regexp @samp{/[^[:alnum:]_[:blank:]]/} might have been written -@samp{/[[:punct:]]/}, but then underscores would also be removed, +The regexp @code{/[^[:alnum:]_[:blank:]]/} might have been written +@code{/[[:punct:]]/}, but then underscores would also be removed, and we want to keep them. Assuming we have saved this program in a file named @file{wordfreq.awk}, @@ -24670,7 +24790,7 @@ The nodes and @ref{Sample Programs}, are the top level nodes for a large number of @command{awk} programs. @end ifinfo -If you want to experiment with these programs, it is tedious to have to type +If you want to experiment with these programs, it is tedious to type them in by hand. Here we present a program that can extract parts of a Texinfo input file into separate files. @@ -24748,7 +24868,7 @@ It also prints some final advice: @@example @@c file examples/messages.awk -END @@@{ print "Always avoid bored archeologists!" @@@} +END @@@{ print "Always avoid bored archaeologists!" @@@} @@c end file @@end example @dots{} @@ -24920,7 +25040,7 @@ The @command{sed} utility is a stream editor, a program that reads a stream of data, makes changes to it, and passes it on. It is often used to make global changes to a large file or to a stream of data generated by a pipeline of commands. -While @command{sed} is a complicated program in its own right, its most common +Although @command{sed} is a complicated program in its own right, its most common use is to perform global substitutions in the middle of a pipeline: @example @@ -24929,7 +25049,7 @@ use is to perform global substitutions in the middle of a pipeline: Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp @samp{old} on each input line and globally replace it with the text -@samp{new}, i.e., all the occurrences on a line. This is similar to +@samp{new} (i.e., all the occurrences on a line). This is similar to @command{awk}'s @code{gsub()} function (@pxref{String Functions}). @@ -25013,7 +25133,7 @@ not treated as @value{FN}s (@pxref{ARGC and ARGV}). The @code{usage()} function prints an error message and exits. -Finally, the single rule handles the printing scheme outlined above, +Finally, the single rule handles the printing scheme outlined earlier, using @code{print} or @code{printf} as appropriate, depending upon the value of @code{RT}. @c ENDOFRANGE awksed @@ -25057,8 +25177,8 @@ BEGIN @{ The following program, @file{igawk.sh}, provides this service. It simulates @command{gawk}'s searching of the @env{AWKPATH} variable -and also allows @dfn{nested} includes; i.e., a file that is included -with @code{@@include} can contain further @code{@@include} statements. +and also allows @dfn{nested} includes (i.e., a file that is included +with @code{@@include} can contain further @code{@@include} statements). @command{igawk} makes an effort to only include files once, so that nested includes don't accidentally include a library function twice. @@ -25088,10 +25208,10 @@ Literal text, provided with @option{-e} or @option{--source}. This text is just appended directly. @item -Source @value{FN}s, provided with @option{-f}. We use a neat trick and append -@samp{@@include @var{filename}} to the shell variable's contents. Since the file-inclusion -program works the way @command{gawk} does, this gets the text -of the file included into the program at the correct point. +Source @value{FN}s, provided with @option{-f}. We use a neat trick and +append @samp{@@include @var{filename}} to the shell variable's contents. +Because the file-inclusion program works the way @command{gawk} does, this +gets the text of the file included in the program at the correct point. @end enumerate @item @@ -25390,9 +25510,10 @@ EOF @c endfile @end example -The shell construct @samp{@var{command} << @var{marker}} is called a @dfn{here document}. -Everything in the shell script up to the @var{marker} is fed to @var{command} as input. -The shell processes the contents of the here document for variable and command substitution +The shell construct @samp{@var{command} << @var{marker}} is called +a @dfn{here document}. Everything in the shell script up to the +@var{marker} is fed to @var{command} as input. The shell processes +the contents of the here document for variable and command substitution (and possibly other things as well, depending upon the shell). The shell construct @samp{$(@dots{})} is called @dfn{command substitution}. @@ -25407,14 +25528,16 @@ It's done in these steps: @enumerate @item Run @command{gawk} with the @code{@@include}-processing program (the -value of the @code{expand_prog} shell variable) on standard input. +value of the @code{expand_prog} shell variable) reading standard input. @item -Standard input is the contents of the user's program, from the shell variable @code{program}. -Its contents are fed to @command{gawk} via a here document. +Standard input is the contents of the user's program, +from the shell variable @code{program}. +Feed its contents to @command{gawk} via a here document. @item -The results of this processing are saved in the shell variable @code{processed_program} by using command substitution. +Save the results of this processing in the shell variable +@code{processed_program} by using command substitution. @end enumerate The last step is to call @command{gawk} with the expanded program, @@ -25490,7 +25613,7 @@ of @command{awk} programs as Web CGI scripts.} @c ENDOFRANGE igawk @node Anagram Program -@subsection Finding Anagrams From A Dictionary +@subsection Finding Anagrams from a Dictionary @cindex anagrams, finding An interesting programming challenge is to @@ -25499,17 +25622,17 @@ word list (such as @file{/usr/share/dict/words} on many GNU/Linux systems). One word is an anagram of another if both words contain the same letters -(for example, ``babbling'' and ``blabbing''). +(e.g., ``babbling'' and ``blabbing''). -Column 2, Problem C of Jon Bentley's @cite{Programming Pearls}, second -edition, presents an elegant algorithm. The idea is to give words that +Column 2, Problem C, of Jon Bentley's @cite{Programming Pearls}, Second +Edition, presents an elegant algorithm. The idea is to give words that are anagrams a common signature, sort all the words together by their signature, and then print them. Dr.@: Bentley observes that taking the letters in each word and sorting them produces that common signature. The following program uses arrays of arrays to bring together words with the same signature and array sorting to print the words -in sorted order. +in sorted order: @c STARTOFRANGE anagram @cindex @code{anagram.awk} program @@ -25581,7 +25704,7 @@ function word2key(word, a, i, n, result) Finally, the @code{END} rule traverses the array and prints out the anagram lists. It sends the output -to the system @command{sort} command, since otherwise +to the system @command{sort} command because otherwise the anagrams would appear in arbitrary order: @example @@ -25609,21 +25732,21 @@ Here is some partial output when the program is run: @example $ @kbd{gawk -f anagram.awk /usr/share/dict/words | grep '^b'} @dots{} -babbled blabbed -babbler blabber brabble -babblers blabbers brabbles -babbling blabbing -babbly blabby -babel bable -babels beslab -babery yabber +babbled blabbed +babbler blabber brabble +babblers blabbers brabbles +babbling blabbing +babbly blabby +babel bable +babels beslab +babery yabber @dots{} @end example @c ENDOFRANGE anagram @node Signature Program -@subsection And Now For Something Completely Different +@subsection And Now for Something Completely Different @cindex signature program @cindex Brini, Davide @@ -25663,28 +25786,28 @@ Subject: The GNU Awk User's Guide, Section 13.3.11 From: "Chris Johansen" <johansen@main.nc.us> Message-ID: <op.v0iw6wlv7finx3@asusodin.thrudvang.lan> -Arnold, you don't know me, but we have a tenuous connection. My wife is +Arnold, you don't know me, but we have a tenuous connection. My wife is Barbara A. Field, FAIA, GIT '65 (B. Arch.). -I have had a couple of paper copies of "Effective Awk Programming" for -years, and now I'm going through a Kindle version of "The GNU Awk User's -Guide" again. When I got to section 13.3.11, I reformatted and lightly +I have had a couple of paper copies of "Effective Awk Programming" for +years, and now I'm going through a Kindle version of "The GNU Awk User's +Guide" again. When I got to section 13.3.11, I reformatted and lightly commented Davide Brin's signature script to understand its workings. -It occurs to me that this might have pedagogical value as an example -(although imperfect) of the value of whitespace and comments, and a -starting point for that discussion. It certainly helped _me_ understand -what's going on. You are welcome to it, as-is or modified (subject to +It occurs to me that this might have pedagogical value as an example +(although imperfect) of the value of whitespace and comments, and a +starting point for that discussion. It certainly helped _me_ understand +what's going on. You are welcome to it, as-is or modified (subject to Davide's constraints, of course, which I think I have met). -If I were to include it in a future edition, I would put it at some -distance from section 13.3.11, say, as a note or an appendix, so as not to +If I were to include it in a future edition, I would put it at some +distance from section 13.3.11, say, as a note or an appendix, so as not to be a "spoiler" to the puzzle. Best regards, --- +-- Chris Johansen {johansen at main dot nc dot us} - . . . collapsing the probability wave function, sending ripples of + . . . collapsing the probability wave function, sending ripples of certainty through the space-time continuum. @@ -25693,7 +25816,7 @@ certainty through the space-time continuum. # From "13.3.11 And Now For Something Completely Different" # http://www.gnu.org/software/gawk/manual/html_node/Signature-Program.html#Signature-Program -# Copyright © 2008 Davide Brini +# Copyright © 2008 Davide Brini # Copying and distribution of the code published in this page, with # or without modification, are permitted in any medium without @@ -25812,7 +25935,7 @@ Brian Kernighan suggests that ``an alternative approach to state machines is to just read the input into an array, then use indexing. It's almost always easier code, and for most inputs where you would use this, just -as fast.'' Rewrite the logic to follow this +as fast.'' Rewrite the logic to follow this suggestion. @@ -25913,7 +26036,7 @@ the use of the external @command{sort} utility. @c EXCLUDE END @ifnotinfo -@part @value{PART3}Moving Beyond Standard @command{awk} With @command{gawk} +@part @value{PART3}Moving Beyond Standard @command{awk} with @command{gawk} @end ifnotinfo @ifdocbook @@ -25922,19 +26045,19 @@ It contains the following chapters: @itemize @value{BULLET} @item -@ref{Advanced Features}. +@ref{Advanced Features} @item -@ref{Internationalization}. +@ref{Internationalization} @item -@ref{Debugger}. +@ref{Debugger} @item -@ref{Arbitrary Precision Arithmetic}. +@ref{Arbitrary Precision Arithmetic} @item -@ref{Dynamic Extensions}. +@ref{Dynamic Extensions} @end itemize @end ifdocbook @@ -26093,7 +26216,7 @@ in a particular order that you, the programmer, choose. @command{gawk} lets you do this. @DBREF{Controlling Scanning} describes how you can assign special, -pre-defined values to @code{PROCINFO["sorted_in"]} in order to +predefined values to @code{PROCINFO["sorted_in"]} in order to control the order in which @command{gawk} traverses an array during a @code{for} loop. @@ -26117,7 +26240,7 @@ Here, @var{i1} and @var{i2} are the indices, and @var{v1} and @var{v2} are the corresponding values of the two elements being compared. Either @var{v1} or @var{v2}, or both, can be arrays if the array being traversed contains subarrays as values. -(@xref{Arrays of Arrays}, for more information about subarrays.) +(@DBXREF{Arrays of Arrays} for more information about subarrays.) The three possible return values are interpreted as follows: @table @code @@ -26160,7 +26283,7 @@ function cmp_str_val(i1, v1, i2, v2) The third comparison function makes all numbers, and numeric strings without -any leading or trailing spaces, come out first during loop traversal: +any leading or trailing spaces, come out first during loop traversal: @example function cmp_num_str_val(i1, v1, i2, v2, n1, n2) @@ -26168,10 +26291,10 @@ function cmp_num_str_val(i1, v1, i2, v2, n1, n2) # numbers before string value comparison, ascending order n1 = v1 + 0 n2 = v2 + 0 - if (n1 == v1) + if (n1 == v1) return (n2 == v2) ? (n1 - n2) : -1 else if (n2 == v2) - return 1 + return 1 return (v1 < v2) ? -1 : (v1 != v2) @} @end example @@ -26186,7 +26309,7 @@ BEGIN @{ data[10] = "one" data[100] = 100 data[20] = "two" - + f[1] = "cmp_num_idx" f[2] = "cmp_str_val" f[3] = "cmp_num_str_val" @@ -26210,14 +26333,14 @@ $ @kbd{gawk -f compdemo.awk} @print{} data[10] = one @print{} data[20] = two @print{} data[100] = 100 -@print{} +@print{} @print{} Sort function: cmp_str_val @ii{Sort by element values as strings} @print{} data[one] = 10 @print{} data[100] = 100 @ii{String 100 is less than string 20} @print{} data[two] = 20 @print{} data[10] = one @print{} data[20] = two -@print{} +@print{} @print{} Sort function: cmp_num_str_val @ii{Sort all numeric values before all strings} @print{} data[one] = 10 @print{} data[two] = 20 @@ -26228,7 +26351,7 @@ $ @kbd{gawk -f compdemo.awk} Consider sorting the entries of a GNU/Linux system password file according to login name. The following program sorts records -by a specific field position and can be used for this purpose: +by a specific field position and can be used for this purpose: @example # passwd-sort.awk --- simple program to sort by field position @@ -26274,7 +26397,7 @@ $ @kbd{gawk -v POS=1 -F: -f sort.awk /etc/passwd} The comparison should normally always return the same value when given a specific pair of array elements as its arguments. If inconsistent -results are returned then the order is undefined. This behavior can be +results are returned, then the order is undefined. This behavior can be exploited to introduce random order into otherwise seemingly ordered data: @@ -26286,7 +26409,7 @@ function cmp_randomize(i1, v1, i2, v2) @} @end example -As mentioned above, the order of the indices is arbitrary if two +As already mentioned, the order of the indices is arbitrary if two elements compare equal. This is usually not a problem, but letting the tied elements come out in arbitrary order can be an issue, especially when comparing item values. The partial ordering of the equal elements @@ -26327,10 +26450,10 @@ When string comparisons are made during a sort, either for element values where one or both aren't numbers, or for element indices handled as strings, the value of @code{IGNORECASE} (@pxref{Built-in Variables}) controls whether -the comparisons treat corresponding uppercase and lowercase letters as +the comparisons treat corresponding upper- and lowercase letters as equivalent or distinct. -Another point to keep in mind is that in the case of subarrays +Another point to keep in mind is that in the case of subarrays, the element values can themselves be arrays; a production comparison function should use the @code{isarray()} function (@pxref{Type Functions}), @@ -26338,7 +26461,7 @@ to check for this, and choose a defined sorting order for subarrays. All sorting based on @code{PROCINFO["sorted_in"]} is disabled in POSIX mode, -since the @code{PROCINFO} array is not special in that case. +because the @code{PROCINFO} array is not special in that case. As a side note, sorting the array indices before traversing the array has been reported to add 15% to 20% overhead to the @@ -26359,8 +26482,8 @@ sorted array traversal is not the default. @cindex @code{asorti()} function (@command{gawk}), arrays@comma{} sorting @cindex sort function, arrays, sorting In most @command{awk} implementations, sorting an array requires writing -a @code{sort()} function. While this can be educational for exploring -different sorting algorithms, usually that's not the point of the program. +a @code{sort()} function. This can be educational for exploring +different sorting algorithms, but usually that's not the point of the program. @command{gawk} provides the built-in @code{asort()} and @code{asorti()} functions (@pxref{String Functions}) for sorting arrays. For example: @@ -26456,8 +26579,8 @@ Because @code{IGNORECASE} affects string comparisons, the value of @code{IGNORECASE} also affects sorting for both @code{asort()} and @code{asorti()}. Note also that the locale's sorting order does @emph{not} come into play; comparisons are based on character values only.@footnote{This -is true because locale-based comparison occurs only when in POSIX -compatibility mode, and since @code{asort()} and @code{asorti()} are +is true because locale-based comparison occurs only when in +POSIX-compatibility mode, and because @code{asort()} and @code{asorti()} are @command{gawk} extensions, they are not available in that case.} @node Two-way I/O @@ -26533,7 +26656,7 @@ remain more difficult to use than two-way pipes.} @c 8/2014 @cindex @command{csh} utility, @code{|&} operator, comparison with However, with @command{gawk}, it is possible to open a @emph{two-way} pipe to another process. The second process is -termed a @dfn{coprocess}, since it runs in parallel with @command{gawk}. +termed a @dfn{coprocess}, as it runs in parallel with @command{gawk}. The two-way connection is created using the @samp{|&} operator (borrowed from the Korn shell, @command{ksh}):@footnote{This is very different from the same operator in the C shell and in Bash.} @@ -26638,7 +26761,7 @@ like so: @example command = "sort -nr" # command, save in convenience variable PROCINFO[command, "pty"] = 1 # update PROCINFO -print @dots{} |& command # start two-way pipe +print @dots{} |& command # start two-way pipe @dots{} @end example @@ -26693,7 +26816,7 @@ You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is by recognizing special @value{FN}s that begin with one of @samp{/inet/}, -@samp{/inet4/} or @samp{/inet6/}. +@samp{/inet4/}, or @samp{/inet6/}. The full syntax of the special @value{FN} is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. @@ -26722,7 +26845,7 @@ or @samp{http}, in which case @command{gawk} attempts to determine the predefined port number using the C @code{getaddrinfo()} function. @item remote-host -The IP address or fully-qualified domain name of the Internet +The IP address or fully qualified domain name of the Internet host to which you want to connect. @item remote-port @@ -26796,12 +26919,12 @@ gawk --profile=myprog.prof -f myprog.awk data1 data2 @end example @noindent -In the above example, @command{gawk} places the profile in +In the preceding example, @command{gawk} places the profile in @file{myprog.prof} instead of in @file{awkprof.out}. -Here is a sample session showing a simple @command{awk} program, its input data, and the -results from running @command{gawk} with the @option{--profile} option. -First, the @command{awk} program: +Here is a sample session showing a simple @command{awk} program, +its input data, and the results from running @command{gawk} with the +@option{--profile} option. First, the @command{awk} program: @example BEGIN @{ print "First BEGIN rule" @} @@ -26959,7 +27082,7 @@ the body of an @code{if}, @code{else}, or loop is only a single statement. @item Parentheses are used only where needed, as indicated by the structure of the program and the precedence rules. -For example, @samp{(3 + 5) * 4} means add three plus five, then multiply +For example, @samp{(3 + 5) * 4} means add three and five, then multiply the total by four. However, @samp{3 + 5 * 4} has no parentheses, and means @samp{3 + (5 * 4)}. @@ -27234,8 +27357,7 @@ following steps, in this order: @enumerate @item -The programmer goes -through the source for all of @command{guide}'s components +The programmer reviews the source for all of @command{guide}'s components and marks each string that is a candidate for translation. For example, @code{"`-F': option required"} is a good candidate for translation. A table with strings of option names is not (e.g., @command{gawk}'s @@ -27355,8 +27477,8 @@ if necessary. (It is almost never necessary to supply a different category.) @cindex sorting characters in different languages @cindex @code{LC_COLLATE} locale category @item LC_COLLATE -Text-collation information; i.e., how different characters -and/or groups of characters sort in a given language. +Text-collation information (i.e., how different characters +and/or groups of characters sort in a given language). @cindex @code{LC_CTYPE} locale category @item LC_CTYPE @@ -27575,7 +27697,7 @@ BEGIN @{ @end enumerate -@xref{I18N Example}, +@DBXREF{I18N Example} for an example program showing the steps to create and use translations from @command{awk}. @@ -27636,7 +27758,7 @@ second argument to @code{dcngettext()}.@footnote{The You should distribute the generated @file{.pot} file with your @command{awk} program; translators will eventually use it to provide you translations that you can also then distribute. -@xref{I18N Example}, +@DBXREF{I18N Example} for the full list of steps to go through to create and test translations for @command{guide}. @c ENDOFRANGE portobfi @@ -27764,7 +27886,7 @@ change: @cindex @code{TEXTDOMAIN} variable, portability and @item Assignments to @code{TEXTDOMAIN} won't have any effect, -since @code{TEXTDOMAIN} is not special in other @command{awk} implementations. +because @code{TEXTDOMAIN} is not special in other @command{awk} implementations. @item Non-GNU versions of @command{awk} treat marked strings @@ -27812,8 +27934,8 @@ enough arguments are supplied in the function call. Many versions of underlying C library version of @code{sprintf()}, but only one format and argument at a time. What happens if a positional specification is used is anybody's guess. -However, since the positional specifications are primarily for use in -@emph{translated} format strings, and since non-GNU @command{awk}s never +However, because the positional specifications are primarily for use in +@emph{translated} format strings, and because non-GNU @command{awk}s never retrieve the translated string, this should not be a problem in practice. @end itemize @c ENDOFRANGE inap @@ -27876,7 +27998,7 @@ called ``Hippy.'' Ah, well.} @example @group -$ cp guide.pot guide-mellow.po +$ @kbd{cp guide.pot guide-mellow.po} @var{Add translations to} guide-mellow.po @dots{} @end group @end example @@ -27902,7 +28024,7 @@ msgstr "Like, the scoop is" The next step is to make the directory to hold the binary message object file and then to create the @file{guide.mo} file. We pretend that our file is to be used in the @code{en_US.UTF-8} locale, -since we have to use a locale name known to the C @command{gettext} routines. +because we have to use a locale name known to the C @command{gettext} routines. The directory layout shown here is standard for GNU @command{gettext} on GNU/Linux systems. Other versions of @command{gettext} may use a different layout: @@ -27939,7 +28061,7 @@ $ @kbd{gawk -f guide.awk} @print{} Pardon me, Zaphod who? @end example -If the three replacement functions for @code{dcgettext()}, @code{dcngettext()} +If the three replacement functions for @code{dcgettext()}, @code{dcngettext()}, and @code{bindtextdomain()} (@pxref{I18N Portability}) are in a file named @file{libintl.awk}, @@ -28041,7 +28163,7 @@ how to use @command{gawk} for debugging your program is easy. @end menu @node Debugging -@section Introduction to The @command{gawk} Debugger +@section Introduction to the @command{gawk} Debugger This @value{SECTION} introduces debugging in general and begins the discussion of debugging in @command{gawk}. @@ -28059,8 +28181,8 @@ the discussion of debugging in @command{gawk}. ahead to the next section on the specific features of the @command{gawk} debugger.) -Of course, a debugging program cannot remove bugs for you, since it has -no way of knowing what you or your users consider a ``bug'' and what is a +Of course, a debugging program cannot remove bugs for you, because it has +no way of knowing what you or your users consider a ``bug'' versus a ``feature.'' (Sometimes, we humans have a hard time with this ourselves.) In that case, what can you expect from such a tool? The answer to that depends on the language being debugged, but in general, you can expect at @@ -28081,7 +28203,7 @@ having to change your source files. @item The chance to see the values of data in the program at any point in execution, and also to change that data on the fly, to see how that -affects what happens afterwards. (This often includes the ability +affects what happens afterward. (This often includes the ability to look at internal data structures besides the variables you actually defined in your code.) @@ -28101,11 +28223,11 @@ functional program that you or someone else wrote). Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. The following list defines terms used throughout the rest of -this @value{CHAPTER}. +this @value{CHAPTER}: @table @dfn @cindex stack frame -@item Stack Frame +@item Stack frame Programs generally call functions during the course of their execution. One function can call another, or a function can call itself (recursion). You can view the chain of called functions (main program calls A, which @@ -28140,7 +28262,7 @@ as many breakpoints as you like. A watchpoint is similar to a breakpoint. The difference is that breakpoints are oriented around the code: stop when a certain point in the code is reached. A watchpoint, however, specifies that program execution -should stop when a @emph{data value} is changed. This is useful, since +should stop when a @emph{data value} is changed. This is useful, as sometimes it happens that a variable receives an erroneous value, and it's hard to track down where this happens just by looking at the code. By using a watchpoint, you can stop whenever a variable is assigned to, @@ -28154,13 +28276,13 @@ Debugging an @command{awk} program has some specific aspects that are not shared with other programming languages. First of all, the fact that @command{awk} programs usually take input -line-by-line from a file or files and operate on those lines using specific +line by line from a file or files and operate on those lines using specific rules makes it especially useful to organize viewing the execution of the program in terms of these rules. As we will see, each @command{awk} rule is treated almost like a function call, with its own specific block of instructions. -In addition, since @command{awk} is by design a very concise language, +In addition, because @command{awk} is by design a very concise language, it is easy to lose sight of everything that is going on ``inside'' each line of @command{awk} code. The debugger provides the opportunity to look at the individual primitive instructions carried out @@ -28287,7 +28409,7 @@ gawk> @kbd{bt} @end example This tells us that @code{are_equal()} was called by the main program at -line 88 of @file{uniq.awk}. (This is not a big surprise, since this +line 88 of @file{uniq.awk}. (This is not a big surprise, because this is the only call to @code{are_equal()} in the program, but in more complex programs, knowing who called a function and with what parameters can be the key to finding the source of the problem.) @@ -28304,7 +28426,7 @@ gawk> @kbd{p n} @end example @noindent -In this case, @code{n} is an uninitialized local variable, since the +In this case, @code{n} is an uninitialized local variable, because the function was called without arguments (@pxref{Function Calls}). A more useful variable to display might be the current record: @@ -28315,8 +28437,8 @@ gawk> @kbd{p $0} @end example @noindent -This might be a bit puzzling at first since this is the second line of -our test input above. Let's look at @code{NR}: +This might be a bit puzzling at first, as this is the second line of +our test input. Let's look at @code{NR}: @example gawk> @kbd{p NR} @@ -28356,7 +28478,7 @@ gawk> @kbd{n} This tells us that @command{gawk} is now ready to execute line 66, which decides whether to give the lines the special ``field skipping'' treatment indicated by the @option{-1} command-line option. (Notice that we skipped -from where we were before at line 63 to here, since the condition in line 63 +from where we were before at line 63 to here, because the condition in line 63 @samp{if (fcount == 0 && charcount == 0)} was false.) Continuing to step, we now get to the splitting of the current and @@ -28386,7 +28508,7 @@ gawk> @kbd{p n m alast aline} This is kind of disappointing, though. All we found out is that there are five elements in @code{alast}; @code{m} and @code{aline} don't have -values since we are at line 68 but haven't executed it yet. +values because we are at line 68 but haven't executed it yet. This information is useful enough (we now know that none of the words were accidentally left out), but what if we want to see inside the array? @@ -28495,8 +28617,9 @@ show the abbreviation on a second description line. A debugger command name may also be truncated if that partial name is unambiguous. The debugger has the built-in capability to automatically repeat the previous command just by hitting @key{Enter}. -This works for the commands @code{list}, @code{next}, @code{nexti}, @code{step}, @code{stepi} -and @code{continue} executed without any argument. +This works for the commands @code{list}, @code{next}, @code{nexti}, +@code{step}, @code{stepi}, and @code{continue} executed without any +argument. @menu * Breakpoint Control:: Control of Breakpoints. @@ -28511,9 +28634,9 @@ and @code{continue} executed without any argument. @node Breakpoint Control @subsection Control of Breakpoints -As we saw above, the first thing you probably want to do in a debugging -session is to get your breakpoints set up, since otherwise your program -will just run as if it was not under the debugger. The commands for +As we saw earlier, the first thing you probably want to do in a debugging +session is to get your breakpoints set up, because your program +will otherwise just run as if it was not under the debugger. The commands for controlling breakpoints are: @table @asis @@ -28584,8 +28707,8 @@ that the debugger evaluates whenever the breakpoint or watchpoint is reached. If the condition is true, then the debugger stops execution and prompts for a command. Otherwise, the debugger continues executing the program. If the condition expression is -not specified, any existing condition is removed; i.e., the breakpoint or -watchpoint is made unconditional. +not specified, any existing condition is removed (i.e., the breakpoint or +watchpoint is made unconditional). @cindex debugger commands, @code{d} (@code{delete}) @cindex debugger commands, @code{delete} @@ -28726,7 +28849,7 @@ Execute one (or @var{count}) instruction(s), stepping over function calls. @item @code{return} [@var{value}] Cancel execution of a function call. If @var{value} (either a string or a number) is specified, it is used as the function's return value. If used in a -frame other than the innermost one (the currently executing function, i.e., +frame other than the innermost one (the currently executing function; i.e., frame number 0), discard all inner frames in addition to the selected one, and the caller of that frame becomes the innermost frame. @@ -28792,7 +28915,7 @@ gawk> @kbd{display x} @end example @noindent -displays the assigned item number, the variable name and its current value. +This displays the assigned item number, the variable name, and its current value. If the display variable refers to a function parameter, it is silently deleted from the list as soon as the execution reaches a context where no such variable of the given name exists. @@ -28860,7 +28983,7 @@ or field. String values must be enclosed between double quotes (@code{"}@dots{}@code{"}). You can also set special @command{awk} variables, such as @code{FS}, -@code{NF}, @code{NR}, etc. +@code{NF}, @code{NR}, and son on. @cindex debugger commands, @code{w} (@code{watch}) @cindex debugger commands, @code{watch} @@ -28923,7 +29046,7 @@ Print a backtrace of all function calls (stack frames), or innermost @var{count} frames if @var{count} > 0. Print the outermost @var{count} frames if @var{count} < 0. The backtrace displays the name and arguments to each function, the source @value{FN}, and the line number. -The alias @code{where} for @code{backtrace} is provided for long-time +The alias @code{where} for @code{backtrace} is provided for longtime GDB users who may be used to that command. @cindex debugger commands, @code{down} @@ -28952,7 +29075,7 @@ Then select and print the frame. @end table @node Debugger Info -@subsection Obtaining Information about the Program and the Debugger State +@subsection Obtaining Information About the Program and the Debugger State Besides looking at the values of variables, there is often a need to get other sorts of information about the state of your program and of the @@ -29120,51 +29243,51 @@ partial dump of Davide Brini's obfuscated code @smallexample gawk> @kbd{dump} @print{} # BEGIN -@print{} -@print{} [ 1:0xfcd340] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] -@print{} [ 1:0xfcc240] Op_push_i : "~" [MALLOC|STRING|STRCUR] -@print{} [ 1:0xfcc2a0] Op_push_i : "~" [MALLOC|STRING|STRCUR] -@print{} [ 1:0xfcc280] Op_match : -@print{} [ 1:0xfcc1e0] Op_store_var : O -@print{} [ 1:0xfcc2e0] Op_push_i : "==" [MALLOC|STRING|STRCUR] -@print{} [ 1:0xfcc340] Op_push_i : "==" [MALLOC|STRING|STRCUR] -@print{} [ 1:0xfcc320] Op_equal : -@print{} [ 1:0xfcc200] Op_store_var : o -@print{} [ 1:0xfcc380] Op_push : o -@print{} [ 1:0xfcc360] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER] -@print{} [ 1:0xfcc220] Op_push_lhs : o [do_reference = true] -@print{} [ 1:0xfcc300] Op_assign_plus : -@print{} [ :0xfcc2c0] Op_pop : -@print{} [ 1:0xfcc400] Op_push : O -@print{} [ 1:0xfcc420] Op_push_i : "" [MALLOC|STRING|STRCUR] -@print{} [ :0xfcc4a0] Op_no_op : -@print{} [ 1:0xfcc480] Op_push : O -@print{} [ :0xfcc4c0] Op_concat : [expr_count = 3] [concat_flag = 0] -@print{} [ 1:0xfcc3c0] Op_store_var : x -@print{} [ 1:0xfcc440] Op_push_lhs : X [do_reference = true] -@print{} [ 1:0xfcc3a0] Op_postincrement : -@print{} [ 1:0xfcc4e0] Op_push : x -@print{} [ 1:0xfcc540] Op_push : o -@print{} [ 1:0xfcc500] Op_plus : -@print{} [ 1:0xfcc580] Op_push : o -@print{} [ 1:0xfcc560] Op_plus : -@print{} [ 1:0xfcc460] Op_leq : -@print{} [ :0xfcc5c0] Op_jmp_false : [target_jmp = 0xfcc5e0] -@print{} [ 1:0xfcc600] Op_push_i : "%c" [MALLOC|STRING|STRCUR] -@print{} [ :0xfcc660] Op_no_op : -@print{} [ 1:0xfcc520] Op_assign_concat : c -@print{} [ :0xfcc620] Op_jmp : [target_jmp = 0xfcc440] -@print{} -@dots{} -@print{} +@print{} +@print{} [ 1:0xfcd340] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] +@print{} [ 1:0xfcc240] Op_push_i : "~" [MALLOC|STRING|STRCUR] +@print{} [ 1:0xfcc2a0] Op_push_i : "~" [MALLOC|STRING|STRCUR] +@print{} [ 1:0xfcc280] Op_match : +@print{} [ 1:0xfcc1e0] Op_store_var : O +@print{} [ 1:0xfcc2e0] Op_push_i : "==" [MALLOC|STRING|STRCUR] +@print{} [ 1:0xfcc340] Op_push_i : "==" [MALLOC|STRING|STRCUR] +@print{} [ 1:0xfcc320] Op_equal : +@print{} [ 1:0xfcc200] Op_store_var : o +@print{} [ 1:0xfcc380] Op_push : o +@print{} [ 1:0xfcc360] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER] +@print{} [ 1:0xfcc220] Op_push_lhs : o [do_reference = true] +@print{} [ 1:0xfcc300] Op_assign_plus : +@print{} [ :0xfcc2c0] Op_pop : +@print{} [ 1:0xfcc400] Op_push : O +@print{} [ 1:0xfcc420] Op_push_i : "" [MALLOC|STRING|STRCUR] +@print{} [ :0xfcc4a0] Op_no_op : +@print{} [ 1:0xfcc480] Op_push : O +@print{} [ :0xfcc4c0] Op_concat : [expr_count = 3] [concat_flag = 0] +@print{} [ 1:0xfcc3c0] Op_store_var : x +@print{} [ 1:0xfcc440] Op_push_lhs : X [do_reference = true] +@print{} [ 1:0xfcc3a0] Op_postincrement : +@print{} [ 1:0xfcc4e0] Op_push : x +@print{} [ 1:0xfcc540] Op_push : o +@print{} [ 1:0xfcc500] Op_plus : +@print{} [ 1:0xfcc580] Op_push : o +@print{} [ 1:0xfcc560] Op_plus : +@print{} [ 1:0xfcc460] Op_leq : +@print{} [ :0xfcc5c0] Op_jmp_false : [target_jmp = 0xfcc5e0] +@print{} [ 1:0xfcc600] Op_push_i : "%c" [MALLOC|STRING|STRCUR] +@print{} [ :0xfcc660] Op_no_op : +@print{} [ 1:0xfcc520] Op_assign_concat : c +@print{} [ :0xfcc620] Op_jmp : [target_jmp = 0xfcc440] +@print{} +@dots{} +@print{} @print{} [ 2:0xfcc5a0] Op_K_printf : [expr_count = 17] [redir_type = ""] -@print{} [ :0xfcc140] Op_no_op : -@print{} [ :0xfcc1c0] Op_atexit : -@print{} [ :0xfcc640] Op_stop : -@print{} [ :0xfcc180] Op_no_op : -@print{} [ :0xfcd150] Op_after_beginfile : -@print{} [ :0xfcc160] Op_no_op : -@print{} [ :0xfcc1a0] Op_after_endfile : +@print{} [ :0xfcc140] Op_no_op : +@print{} [ :0xfcc1c0] Op_atexit : +@print{} [ :0xfcc640] Op_stop : +@print{} [ :0xfcc180] Op_no_op : +@print{} [ :0xfcd150] Op_after_beginfile : +@print{} [ :0xfcc160] Op_no_op : +@print{} [ :0xfcc1a0] Op_after_endfile : gawk> @end smallexample @@ -29221,7 +29344,7 @@ function @var{function}. This command may change the current source file. @itemx @code{q} Exit the debugger. Debugging is great fun, but sometimes we all have to tend to other obligations in life, and sometimes we find the bug, -and are free to go on to the next one! As we saw above, if you are +and are free to go on to the next one! As we saw earlier, if you are running a program, the debugger warns you if you accidentally type @samp{q} or @samp{quit}, to make sure you really want to quit. @@ -29298,7 +29421,7 @@ If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands} (or if you are already familiar with @command{gawk} internals), you will realize that much of the internal manipulation of data in @command{gawk}, as in many interpreters, is done on a stack. -@code{Op_push}, @code{Op_pop}, etc., are the ``bread and butter'' of +@code{Op_push}, @code{Op_pop}, and the like, are the ``bread and butter'' of most @command{gawk} code. Unfortunately, as of now, the @command{gawk} @@ -29312,8 +29435,8 @@ change back to obscure, perhaps more optimal code later. @item There is no way to look ``inside'' the process of compiling regular expressions to see if you got it right. As an @command{awk} -programmer, you are expected to know what @code{/[^[:alnum:][:blank:]]/} -means. +programmer, you are expected to know the meaning of +@code{/[^[:alnum:][:blank:]]/}. @item The @command{gawk} debugger is designed to be used by running a program (with all its @@ -29365,7 +29488,7 @@ and editing. @end itemize @node Arbitrary Precision Arithmetic -@chapter Arithmetic and Arbitrary Precision Arithmetic with @command{gawk} +@chapter Arithmetic and Arbitrary-Precision Arithmetic with @command{gawk} @cindex arbitrary precision @cindex multiple precision @cindex infinite precision @@ -29375,9 +29498,9 @@ This @value{CHAPTER} introduces some basic concepts relating to how computers do arithmetic and defines some important terms. It then proceeds to describe floating-point arithmetic, which is what @command{awk} uses for all its computations, including a -discussion of arbitrary precision floating point arithmetic, which is +discussion of arbitrary-precision floating-point arithmetic, which is a feature available only in @command{gawk}. It continues on to present -arbitrary precision integers, and concludes with a description of some +arbitrary-precision integers, and concludes with a description of some points where @command{gawk} and the POSIX standard are not quite in agreement. @@ -29440,51 +29563,51 @@ The disadvantage is that their range is limited. @cindex integers, unsigned In computers, integer values come in two flavors: @dfn{signed} and @dfn{unsigned}. Signed values may be negative or positive, whereas -unsigned values are always positive (that is, greater than or equal +unsigned values are always positive (i.e., greater than or equal to zero). In computer systems, integer arithmetic is exact, but the possible range of values is limited. Integer arithmetic is generally faster than -floating point arithmetic. +floating-point arithmetic. -@item Floating point arithmetic +@item Floating-point arithmetic Floating-point numbers represent what were called in school ``real'' -numbers; i.e., those that have a fractional part, such as 3.1415927. +numbers (i.e., those that have a fractional part, such as 3.1415927). The advantage to floating-point numbers is that they can represent a much larger range of values than can integers. The disadvantage is that there are numbers that they cannot represent exactly. -Modern systems support floating point arithmetic in hardware, with a +Modern systems support floating-point arithmetic in hardware, with a limited range of values. There are software libraries that allow -the use of arbitrary precision floating point calculations. +the use of arbitrary-precision floating-point calculations. -POSIX @command{awk} uses @dfn{double precision} floating-point numbers, which -can hold more digits than @dfn{single precision} floating-point numbers. -@command{gawk} has facilities for performing arbitrary precision floating -point arithmetic, which we describe in more detail shortly. +POSIX @command{awk} uses @dfn{double-precision} floating-point numbers, which +can hold more digits than @dfn{single-precision} floating-point numbers. +@command{gawk} has facilities for performing arbitrary-precision +floating-point arithmetic, which we describe in more detail shortly. @end table -Computers work with integer and floating point values of different -ranges. Integer values are usually either 32 or 64 bits in size. Single -precision floating point values occupy 32 bits, whereas double precision -floating point values occupy 64 bits. Floating point values are always +Computers work with integer and floating-point values of different +ranges. Integer values are usually either 32 or 64 bits in size. +Single-precision floating-point values occupy 32 bits, whereas double-precision +floating-point values occupy 64 bits. Floating-point values are always signed. The possible ranges of values are shown in @ref{table-numeric-ranges}. @float Table,table-numeric-ranges -@caption{Value Ranges for Different Numeric Representations} +@caption{Value ranges for different numeric representations} @multitable @columnfractions .34 .33 .33 @headitem Numeric representation @tab Minimum value @tab Maximum value @item 32-bit signed integer @tab @minus{}2,147,483,648 @tab 2,147,483,647 @item 32-bit unsigned integer @tab 0 @tab 4,294,967,295 @item 64-bit signed integer @tab @minus{}9,223,372,036,854,775,808 @tab 9,223,372,036,854,775,807 @item 64-bit unsigned integer @tab 0 @tab 18,446,744,073,709,551,615 -@item Single precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38} -@item Double precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308} +@item Single-precision floating point (approximate) @tab @code{1.175494e-38} @tab @code{3.402823e+38} +@item Double-precision floating point (approximate) @tab @code{2.225074e-308} @tab @code{1.797693e+308} @end multitable @end float @node Math Definitions -@section Other Stuff To Know +@section Other Stuff to Know The rest of this @value{CHAPTER} uses a number of terms. Here are some informal definitions that should help you work your way through the material @@ -29561,7 +29684,7 @@ How numbers are rounded up or down when necessary. More details are provided later. @item Significand -A floating point value consists the significand multiplied by 10 +A floating-point value consists the significand multiplied by 10 to the power of the exponent. For example, in @code{1.2345e67}, the significand is @code{1.2345}. @@ -29579,19 +29702,19 @@ on some of those terms. On modern systems, floating-point hardware uses the representation and operations defined by the IEEE 754 standard. Three of the standard IEEE 754 types are 32-bit single precision, -64-bit double precision and 128-bit quadruple precision. +64-bit double precision, and 128-bit quadruple precision. The standard also specifies extended precision formats to allow greater precisions and larger exponent ranges. -(@command{awk} uses only the 64-bit double precision format.) +(@command{awk} uses only the 64-bit double-precision format.) @ref{table-ieee-formats} lists the precision and exponent field values for the basic IEEE 754 binary formats: @float Table,table-ieee-formats -@caption{Basic IEEE Format Values} +@caption{Basic IEEE format values} @multitable @columnfractions .20 .20 .20 .20 .20 @headitem Name @tab Total bits @tab Precision @tab Minimum exponent @tab Maximum exponent -@item Single @tab 32 @tab 24 @tab @minus{}126 @tab +127 +@item Single @tab 32 @tab 24 @tab @minus{}126 @tab +127 @item Double @tab 64 @tab 53 @tab @minus{}1022 @tab +1023 @item Quadruple @tab 128 @tab 113 @tab @minus{}16382 @tab +16383 @end multitable @@ -29603,14 +29726,14 @@ one extra bit of significand. @end quotation @node MPFR features -@section Arbitrary Precision Arithmetic Features In @command{gawk} +@section Arbitrary-Precision Arithmetic Features in @command{gawk} -By default, @command{gawk} uses the double precision floating-point values +By default, @command{gawk} uses the double-precision floating-point values supplied by the hardware of the system it runs on. However, if it was -compiled to do so, @command{gawk} uses the @uref{http://www.mpfr.org -GNU MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for arbitrary -precision arithmetic on numbers. You can see if MPFR support is available -like so: +compiled to do so, @command{gawk} uses the @uref{http://www.mpfr.org, +GNU MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for +arbitrary-precision arithmetic on numbers. You can see if MPFR support +is available like so: @example $ @kbd{gawk --version} @@ -29638,11 +29761,11 @@ Two predefined variables, @code{PREC} and @code{ROUNDMODE}, provide control over the working precision and the rounding mode. The precision and the rounding mode are set globally for every operation to follow. -@xref{Setting precision}, and @ref{Setting the rounding mode}, +@DBXREF{Setting precision} and @DBREF{Setting the rounding mode} for more information. @node FP Math Caution -@section Floating Point Arithmetic: Caveat Emptor! +@section Floating-Point Arithmetic: Caveat Emptor! @quotation @i{Math class is tough!} @@ -29675,17 +29798,17 @@ rely just on what we tell you. @end menu @node Inexactness of computations -@subsection Floating Point Arithmetic Is Not Exact +@subsection Floating-Point Arithmetic Is Not Exact Binary floating-point representations and arithmetic are inexact. Simple values like 0.1 cannot be precisely represented using binary floating-point numbers, and the limited precision of floating-point numbers means that slight changes in the order of operations or the precision of intermediate storage -can change the result. To make matters worse, with arbitrary precision -floating-point, you can set the precision before starting a computation, -but then you cannot be sure of the number of significant decimal places -in the final result. +can change the result. To make matters worse, with arbitrary-precision +floating-point arithmetic, you can set the precision before starting a +computation, but then you cannot be sure of the number of significant +decimal places in the final result. @menu * Inexact representation:: Numbers are not exactly represented. @@ -29707,7 +29830,7 @@ y = 0.425 Unlike the number in @code{y}, the number stored in @code{x} is exactly representable -in binary since it can be written as a finite sum of one or +in binary because it can be written as a finite sum of one or more fractions whose denominators are all powers of two. When @command{gawk} reads a floating-point number from program source, it automatically rounds that number to whatever @@ -29733,7 +29856,7 @@ Because the underlying representation can be a little bit off from the exact val comparing floating-point values to see if they are exactly equal is generally a bad idea. Here is an example where it does not work like you would expect: -@example +@example $ @kbd{gawk 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'} @print{} 0 @end example @@ -29742,7 +29865,7 @@ The general wisdom when comparing floating-point values is to see if they are within some small range of each other (called a @dfn{delta}, or @dfn{tolerance}). You have to decide how small a delta is important to you. Code to do -this looks something like this: +this looks something like the following: @example delta = 0.00001 # for example @@ -29762,7 +29885,7 @@ else The loss of accuracy during a single computation with floating-point numbers usually isn't enough to worry about. However, if you compute a -value which is the result of a sequence of floating point operations, +value which is the result of a sequence of floating-point operations, the error can accumulate and greatly affect the computation itself. Here is an attempt to compute the value of @value{PI} using one of its many series representations: @@ -29808,9 +29931,9 @@ $ @kbd{gawk 'BEGIN @{} @end example @node Getting Accuracy -@subsection Getting The Accuracy You Need +@subsection Getting the Accuracy You Need -Can arbitrary precision arithmetic give exact results? There are +Can arbitrary-precision arithmetic give exact results? There are no easy answers. The standard rules of algebra often do not apply when using floating-point arithmetic. Among other things, the distributive and associative laws @@ -29819,12 +29942,12 @@ for your computation. Rounding error, cumulative precision loss and underflow are often troublesome. When @command{gawk} tests the expressions @samp{0.1 + 12.2} and -@samp{12.3} for equality using the machine double precision arithmetic, +@samp{12.3} for equality using the machine double-precision arithmetic, it decides that they are not equal! (@xref{Comparing FP Values}.) You can get the result you want by increasing the precision; 56 bits in this case does the job: -@example +@example $ @kbd{gawk -M -v PREC=56 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'} @print{} 1 @end example @@ -29833,7 +29956,7 @@ If adding more bits is good, perhaps adding even more bits of precision is better? Here is what happens if we use an even larger value of @code{PREC}: -@example +@example $ @kbd{gawk -M -v PREC=201 'BEGIN @{ print (0.1 + 12.2 == 12.3) @}'} @print{} 0 @end example @@ -29842,15 +29965,15 @@ This is not a bug in @command{gawk} or in the MPFR library. It is easy to forget that the finite number of bits used to store the value is often just an approximation after proper rounding. The test for equality succeeds if and only if @emph{all} bits in the two operands -are exactly the same. Since this is not necessarily true after floating-point +are exactly the same. Because this is not necessarily true after floating-point computations with a particular precision and effective rounding mode, a straight test for equality may not work. Instead, compare the two numbers to see if they are within the desirable delta of each other. In applications where 15 or fewer decimal places suffice, -hardware double precision arithmetic can be adequate, and is usually much faster. +hardware double-precision arithmetic can be adequate, and is usually much faster. But you need to keep in mind that every floating-point operation -can suffer a new rounding error with catastrophic consequences as illustrated +can suffer a new rounding error with catastrophic consequences, as illustrated by our earlier attempt to compute the value of @value{PI}. Extra precision can greatly enhance the stability and the accuracy of your computation in such cases. @@ -29874,9 +29997,9 @@ an arbitrarily large value for @code{PREC}. Reformulation of the problem at hand is often the correct approach in such situations. @node Try To Round -@subsection Try A Few Extra Bits of Precision and Rounding +@subsection Try a Few Extra Bits of Precision and Rounding -Instead of arbitrary precision floating-point arithmetic, +Instead of arbitrary-precision floating-point arithmetic, often all you need is an adjustment of your logic or a different order for the operations in your calculation. The stability and the accuracy of the computation of @value{PI} @@ -29888,7 +30011,7 @@ simple algebraic transformation: @end example @noindent -After making this, change the program converges to +After making this change, the program converges to @value{PI} in under 30 iterations: @example @@ -29904,7 +30027,7 @@ $ @kbd{gawk -f pi2.awk} @end example @node Setting precision -@subsection Setting The Precision +@subsection Setting the Precision @command{gawk} uses a global working precision; it does not keep track of the precision or accuracy of individual numbers. Performing an arithmetic @@ -29916,14 +30039,14 @@ shown in @ref{table-predefined-precision-strings}, to emulate an IEEE 754 binary format. @float Table,table-predefined-precision-strings -@caption{Predefined Precision Strings For @code{PREC}} +@caption{Predefined precision strings for @code{PREC}} @multitable {@code{"double"}} {12345678901234567890123456789012345} @headitem @code{PREC} @tab IEEE 754 Binary Format -@item @code{"half"} @tab 16-bit half-precision. -@item @code{"single"} @tab Basic 32-bit single precision. -@item @code{"double"} @tab Basic 64-bit double precision. -@item @code{"quad"} @tab Basic 128-bit quadruple precision. -@item @code{"oct"} @tab 256-bit octuple precision. +@item @code{"half"} @tab 16-bit half-precision +@item @code{"single"} @tab Basic 32-bit single precision +@item @code{"double"} @tab Basic 64-bit double precision +@item @code{"quad"} @tab Basic 128-bit quadruple precision +@item @code{"oct"} @tab 256-bit octuple precision @end multitable @end float @@ -29954,7 +30077,7 @@ differences among various ways to print a floating-point constant: @example $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 0.1) @}'} -@print{} 0.1000000000000000055511151 +@print{} 0.1000000000000000055511151 $ @kbd{gawk -M -v PREC=113 'BEGIN @{ printf("%0.25f\n", 0.1) @}'} @print{} 0.1000000000000000000000000 $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", "0.1") @}'} @@ -29964,7 +30087,7 @@ $ @kbd{gawk -M 'BEGIN @{ PREC = 113; printf("%0.25f\n", 1/10) @}'} @end example @node Setting the rounding mode -@subsection Setting The Rounding Mode +@subsection Setting the Rounding Mode The @code{ROUNDMODE} variable provides program level control over the rounding mode. @@ -29972,7 +30095,7 @@ The correspondence between @code{ROUNDMODE} and the IEEE rounding modes is shown in @ref{table-gawk-rounding-modes}. @float Table,table-gawk-rounding-modes -@caption{@command{gawk} Rounding Modes} +@caption{@command{gawk} rounding modes} @multitable @columnfractions .45 .30 .25 @headitem Rounding Mode @tab IEEE Name @tab @code{ROUNDMODE} @item Round to nearest, ties to even @tab @code{roundTiesToEven} @tab @code{"N"} or @code{"n"} @@ -29987,7 +30110,7 @@ rounding modes is shown in @ref{table-gawk-rounding-modes}. selects the IEEE 754 rounding mode @code{roundTiesToEven}. In @ref{table-gawk-rounding-modes}, the value @code{"A"} selects @code{roundTiesToAway}. This is only available if your version of the -MPFR library supports it; otherwise setting @code{ROUNDMODE} to @code{"A"} +MPFR library supports it; otherwise, setting @code{ROUNDMODE} to @code{"A"} has no effect. The default mode @code{roundTiesToEven} is the most preferred, @@ -30058,14 +30181,14 @@ accumulation of round-off error, look for a significant difference in output when you change the rounding mode to be sure. @node Arbitrary Precision Integers -@section Arbitrary Precision Integer Arithmetic with @command{gawk} +@section Arbitrary-Precision Integer Arithmetic with @command{gawk} @cindex integers, arbitrary precision @cindex arbitrary precision integers When given the @option{-M} option, -@command{gawk} performs all integer arithmetic using GMP arbitrary -precision integers. Any number that looks like an integer in a source -or @value{DF} is stored as an arbitrary precision integer. The size +@command{gawk} performs all integer arithmetic using GMP arbitrary-precision +integers. Any number that looks like an integer in a source +or @value{DF} is stored as an arbitrary-precision integer. The size of the integer is limited only by the available memory. For example, the following computes @iftex @@ -30080,7 +30203,7 @@ the following computes 5<superscript>4<superscript>3<superscript>2</superscript></superscript></superscript>, @c @end docbook the result of which is beyond the -limits of ordinary hardware double precision floating point values: +limits of ordinary hardware double-precision floating-point values: @example $ @kbd{gawk -M 'BEGIN @{} @@ -30092,7 +30215,7 @@ $ @kbd{gawk -M 'BEGIN @{} @print{} 62060698786608744707 ... 92256259918212890625 @end example -If instead you were to compute the same value using arbitrary precision +If instead you were to compute the same value using arbitrary-precision floating-point values, the precision needed for correct output (using the formula @iftex @@ -30137,10 +30260,10 @@ floating-point results exactly. You can either increase the precision @samp{2.0} with an integer, to perform all computations using integer arithmetic to get the correct output. -Sometimes @command{gawk} must implicitly convert an arbitrary precision -integer into an arbitrary precision floating-point value. This is +Sometimes @command{gawk} must implicitly convert an arbitrary-precision +integer into an arbitrary-precision floating-point value. This is primarily because the MPFR library does not always provide the relevant -interface to process arbitrary precision integers or mixed-mode numbers +interface to process arbitrary-precision integers or mixed-mode numbers as needed by an operation or function. In such a case, the precision is set to the minimum value necessary for exact conversion, and the working precision is not used for this purpose. If this is not what you need or @@ -30158,7 +30281,7 @@ to begin with: gawk -M 'BEGIN @{ n = 13.0; print n % 2.0 @}' @end example -Note that for the particular example above, it is likely best +Note that for this particular example, it is likely best to just use the following: @example @@ -30293,13 +30416,13 @@ should support additional features. These features are: @itemize @value{BULLET} @item -Interpretation of floating point data values specified in hexadecimal +Interpretation of floating-point data values specified in hexadecimal notation (e.g., @code{0xDEADBEEF}). (Note: data values, @emph{not} source code constants.) @item -Support for the special IEEE 754 floating point values ``Not A Number'' -(NaN), positive Infinity (``inf'') and negative Infinity (``@minus{}inf''). +Support for the special IEEE 754 floating-point values ``Not A Number'' +(NaN), positive Infinity (``inf''), and negative Infinity (``@minus{}inf''). In particular, the format for these values is as specified by the ISO 1999 C standard, which ignores case and can allow implementation-dependent additional characters after the @samp{nan} and allow either @samp{inf} or @samp{infinity}. @@ -30310,8 +30433,8 @@ practice: @itemize @value{BULLET} @item -The @command{gawk} maintainer feels that supporting hexadecimal floating -point values, in particular, is ugly, and was never intended by the +The @command{gawk} maintainer feels that supporting hexadecimal +floating-point values, in particular, is ugly, and was never intended by the original designers to be part of the language. @item @@ -30325,10 +30448,10 @@ interpretation of the standard, which requires a certain amount of intended by the standard developers. In other words, ``we see how you got where you are, but we don't think that that's where you want to be.'' -Recognizing the above issues, but attempting to provide compatibility +Recognizing these issues, but attempting to provide compatibility with the earlier versions of the standard, the 2008 POSIX standard added explicit wording to allow, but not require, -that @command{awk} support hexadecimal floating point values and +that @command{awk} support hexadecimal floating-point values and special values for ``Not A Number'' and infinity. Although the @command{gawk} maintainer continues to feel that @@ -30385,12 +30508,12 @@ Thus @samp{+nan} and @samp{+NaN} are the same. @itemize @value{BULLET} @item Most computer arithmetic is done using either integers or floating-point -values. Standard @command{awk} uses double precision +values. Standard @command{awk} uses double-precision floating-point values. @item -In the early 1990's, Barbie mistakenly said ``Math class is tough!'' -While math isn't tough, floating-point arithmetic isn't the same +In the early 1990s, Barbie mistakenly said ``Math class is tough!'' +Although math isn't tough, floating-point arithmetic isn't the same as pencil and paper math, and care must be taken: @c nested list @@ -30423,7 +30546,7 @@ arithmetic. Use @code{PREC} to set the precision in bits, and @item With @option{-M}, @command{gawk} performs -arbitrary precision integer arithmetic using the GMP library. +arbitrary-precision integer arithmetic using the GMP library. This is faster and more space efficient than using MPFR for the same calculations. @@ -30436,7 +30559,7 @@ It pays to be aware of them. Overall, there is no need to be unduly suspicious about the results from floating-point arithmetic. The lesson to remember is that floating-point arithmetic is always more complex than arithmetic using pencil and -paper. In order to take advantage of the power of computer floating-point, +paper. In order to take advantage of the power of computer floating point, you need to know its limitations and work within them. For most casual use of floating-point arithmetic, you will often get the expected result if you simply round the display of your final results to the correct number @@ -30500,8 +30623,8 @@ C library routines that could be of use. As with most software, ``the sky is the limit;'' if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! -Extensions are written in C or C++, using the @dfn{Application Programming -Interface} (API) defined for this purpose by the @command{gawk} +Extensions are written in C or C++, using the @dfn{application programming +interface} (API) defined for this purpose by the @command{gawk} developers. The rest of this @value{CHAPTER} explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents @@ -30538,7 +30661,7 @@ int plugin_is_GPL_compatible; @end example @node Extension Mechanism Outline -@section At A High Level How It Works +@section How It Works at a High Level Communication between @command{gawk} and an extension is two-way. First, when an extension @@ -30553,22 +30676,22 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-load-extension"/>}. @ifnotdocbook @float Figure,figure-load-extension -@caption{Loading The Extension} +@caption{Loading the extension} @c FIXME: One day, it should not be necessary to have two cases, @c but rather just the one without the "txt" final argument. @c This applies to the other figures as well. @ifinfo -@center @image{api-figure1, , , Loading The Extension, txt} +@center @image{api-figure1, , , Loading the extension, txt} @end ifinfo @ifnotinfo -@center @image{api-figure1, , , Loading The Extension} +@center @image{api-figure1, , , Loading the extension} @end ifnotinfo @end float @end ifnotdocbook @docbook <figure id="figure-load-extension" float="0"> -<title>Loading The Extension</title> +<title>Loading the extension</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure1.png" format="PNG"/></imageobject> </mediaobject> @@ -30588,19 +30711,19 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-register-new-function @ifnotdocbook @float Figure,figure-register-new-function -@caption{Registering A New Function} +@caption{Registering a new function} @ifinfo -@center @image{api-figure2, , , Registering A New Function, txt} +@center @image{api-figure2, , , Registering a new Function, txt} @end ifinfo @ifnotinfo -@center @image{api-figure2, , , Registering A New Function} +@center @image{api-figure2, , , Registering a new Function} @end ifnotinfo @end float @end ifnotdocbook @docbook <figure id="figure-register-new-function" float="0"> -<title>Registering A New Function</title> +<title>Registering a new function</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure2.png" format="PNG"/></imageobject> </mediaobject> @@ -30621,7 +30744,7 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-call-new-function"/>} @ifnotdocbook @float Figure,figure-call-new-function -@caption{Calling The New Function} +@caption{Calling the new function} @ifinfo @center @image{api-figure3, , , Calling the new function, txt} @end ifinfo @@ -30633,7 +30756,7 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-call-new-function"/>} @docbook <figure id="figure-call-new-function" float="0"> -<title>Calling The New Function</title> +<title>Calling the new function</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure3.png" format="PNG"/></imageobject> </mediaobject> @@ -30669,10 +30792,9 @@ The API also provides major and minor version numbers, so that an extension can check if the @command{gawk} it is loaded with supports the facilities it was compiled with. (Version mismatches ``shouldn't'' happen, but we all know how @emph{that} goes.) -@xref{Extension Versioning}, for details. +@DBXREF{Extension Versioning} for details. @end itemize - @node Extension API Description @section API Description @cindex extension API @@ -30714,20 +30836,23 @@ Allocating, reallocating, and releasing memory. @item Registration functions. You may register: + +@c nested list @itemize @value{MINUS} @item -extension functions, +Extension functions @item -exit callbacks, +Exit callbacks @item -a version string, +A version string @item -input parsers, +Input parsers @item -output wrappers, +Output wrappers @item -and two-way processors. +Two-way processors @end itemize + All of these are discussed in detail, later in this @value{CHAPTER}. @item @@ -30774,7 +30899,7 @@ Some points about using the API: @itemize @value{BULLET} @item -The following types and/or macros and/or functions are referenced +The following types, macros, and/or functions are referenced in @file{gawkapi.h}. For correct use, you must therefore include the corresponding standard header file @emph{before} including @file{gawkapi.h}: @@ -30788,7 +30913,7 @@ corresponding standard header file @emph{before} including @file{gawkapi.h}: @item @code{memset()} @tab @code{<string.h>} @item @code{size_t} @tab @code{<sys/types.h>} @item @code{struct stat} @tab @code{<sys/stat.h>} -@end multitable +@end multitable Due to portability concerns, especially to systems that are not fully standards-compliant, it is your responsibility @@ -30820,7 +30945,7 @@ and is managed by @command{gawk} from then on. The API defines several simple @code{struct}s that map values as seen from @command{awk}. A value can be a @code{double}, a string, or an array (as in multidimensional arrays, or when creating a new array). -String values maintain both pointer and length since embedded @sc{nul} +String values maintain both pointer and length, because embedded @sc{nul} characters are allowed. @quotation NOTE @@ -30845,14 +30970,14 @@ so that the extension can, e.g., print an error message @c The table there should be presented here @end itemize -While you may call the API functions by using the function pointers -directly, the interface is not so pretty. To make extension code look +You may call the API functions by using the function pointers +directly, but the interface is not so pretty. To make extension code look more like regular code, the @file{gawkapi.h} header file defines several macros that you should use in your code. This @value{SECTION} presents the macros as if they were functions. @node General Data Types -@subsection General Purpose Data Types +@subsection General-Purpose Data Types @cindex Robbins, Arnold @cindex Ramey, Chet @@ -30867,9 +30992,10 @@ can accommodate both love and hate.} @author Chet Ramey @end quotation -The extension API defines a number of simple types and structures for general -purpose use. Additional, more specialized, data structures are introduced -in subsequent @value{SECTION}s, together with the functions that use them. +The extension API defines a number of simple types and structures for +general-purpose use. Additional, more specialized, data structures are +introduced in subsequent @value{SECTION}s, together with the functions +that use them. @table @code @item typedef void *awk_ext_id_t; @@ -30896,8 +31022,9 @@ A simple boolean type. This represents a mutable string. @command{gawk} owns the memory pointed to if it supplied the value. Otherwise, it takes ownership of the memory pointed to. -@strong{Such memory must come from calling one of the -@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()} functions!} +@emph{Such memory must come from calling one of the +@code{gawk_malloc()}, @code{gawk_calloc()}, or +@code{gawk_realloc()} functions!} As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -30923,7 +31050,7 @@ It is used in the following @code{struct}. @itemx @ @ @ @ @ @ @ @ awk_value_cookie_t@ vc; @itemx @ @ @ @ @} u; @itemx @} awk_value_t; -An ``@command{awk} value.'' +An ``@command{awk} value.'' The @code{val_type} member indicates what kind of value the @code{union} holds, and each member is of the appropriate type. @@ -30936,13 +31063,14 @@ These macros make accessing the fields of the @code{awk_value_t} more readable. @item typedef void *awk_scalar_t; -Scalars can be represented as an opaque type. These values are obtained from -@command{gawk} and then passed back into it. This is discussed in a general fashion below, -and in more detail in @ref{Symbol table by cookie}. +Scalars can be represented as an opaque type. These values are obtained +from @command{gawk} and then passed back into it. This is discussed +in a general fashion in the text following this list, and in more detail in +@ref{Symbol table by cookie}. @item typedef void *awk_value_cookie_t; A ``value cookie'' is an opaque type representing a cached value. -This is also discussed in a general fashion below, +This is also discussed in a general fashion in the text following this list, and in more detail in @ref{Cached values}. @end table @@ -30952,7 +31080,7 @@ Scalar values in @command{awk} are either numbers or strings. The indicates what is in the @code{union}. Representing numbers is easy---the API uses a C @code{double}. Strings -require more work. Since @command{gawk} allows embedded @sc{nul} bytes +require more work. Because @command{gawk} allows embedded @sc{nul} bytes in string values, a string must be represented as a pair containing a data-pointer and length. This is the @code{awk_string_t} type. @@ -30965,13 +31093,13 @@ itself be an array. Discussion of arrays is delayed until The various macros listed earlier make it easier to use the elements of the @code{union} as if they were fields in a @code{struct}; this is a common coding practice in C. Such code is easier to write and to -read, however it remains @emph{your} responsibility to make sure that +read, but it remains @emph{your} responsibility to make sure that the @code{val_type} member correctly reflects the type of the value in the @code{awk_value_t}. Conceptually, the first three members of the @code{union} (number, string, and array) are all that is needed for working with @command{awk} values. -However, since the API provides routines for accessing and changing +However, because the API provides routines for accessing and changing the value of global scalar variables only by using the variable's name, there is a performance penalty: @command{gawk} must find the variable each time it is accessed and changed. This turns out to be a real issue, @@ -31011,7 +31139,7 @@ The API provides a number of @dfn{memory allocation} functions for allocating memory that can be passed to @command{gawk}, as well as a number of convenience macros. This @value{SUBSECTION} presents them all as function prototypes, in -the way that extension code would use them. +the way that extension code would use them: @table @code @item void *gawk_malloc(size_t size); @@ -31056,7 +31184,8 @@ The arguments to this macro are as follows: The pointer variable to point at the allocated storage. @item type -The type of the pointer variable, used to create a cast for the call to @code{gawk_malloc()}. +The type of the pointer variable. This is used to create a cast for +the call to @code{gawk_malloc()}. @item size The total number of bytes to be allocated. @@ -31091,7 +31220,7 @@ The arguments are the same as for the @code{emalloc()} macro. The API provides a number of @dfn{constructor} functions for creating string and numeric values, as well as a number of convenience macros. This @value{SUBSECTION} presents them all as function prototypes, in -the way that extension code would use them. +the way that extension code would use them: @table @code @item static inline awk_value_t * @@ -31170,8 +31299,8 @@ This is a pointer to the C function that provides the extension's functionality. The function must fill in @code{*result} with either a number or a string. @command{gawk} takes ownership of any string memory. -As mentioned earlier, string memory @strong{must} come from one of @code{gawk_malloc()}, -@code{gawk_calloc()} or @code{gawk_realloc()}. +As mentioned earlier, string memory @strong{must} come from one of +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}. The @code{num_actual_args} argument tells the C function how many actual parameters were passed from the calling @command{awk} code. @@ -31206,7 +31335,7 @@ Such functions are useful if you have general ``cleanup'' tasks that should be performed in your extension (such as closing database connections or other resource deallocations). You can register such -a function with @command{gawk} using the following function. +a function with @command{gawk} using the following function: @table @code @item void awk_atexit(void (*funcp)(void *data, int exit_status), @@ -31227,8 +31356,9 @@ the function pointed to by @code{funcp}. @end table @end table -Exit callback functions are called in Last-In-First-Out (LIFO) order---that is, in -the reverse order in which they are registered with @command{gawk}. +Exit callback functions are called in last-in-first-out (LIFO) +order---that is, in the reverse order in which they are registered with +@command{gawk}. @node Extension Version String @subsubsection Registering An Extension Version String @@ -31239,7 +31369,7 @@ version of your extension, with @command{gawk}, as follows: @table @code @item void register_ext_version(const char *version); Register the string pointed to by @code{version} with @command{gawk}. -@command{gawk} does @emph{not} copy the @code{version} string, so +Note that @command{gawk} does @emph{not} copy the @code{version} string, so it should not be changed. @end table @@ -31264,14 +31394,14 @@ To provide an input parser, you must first provide two functions (where @var{XXX} is a prefix name for your extension): @table @code -@item awk_bool_t @var{XXX}_can_take_file(const awk_input_buf_t *iobuf) +@item awk_bool_t @var{XXX}_can_take_file(const awk_input_buf_t *iobuf); This function examines the information available in @code{iobuf} (which we discuss shortly). Based on the information there, it decides if the input parser should be used for this file. If so, it should return true. Otherwise, it should return false. It should not change any state (variable values, etc.) within @command{gawk}. -@item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf) +@item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf); When @command{gawk} decides to hand control of the file over to the input parser, it calls this function. This function in turn must fill in certain fields in the @code{awk_input_buf_t} structure, and ensure @@ -31321,7 +31451,7 @@ appropriately. @item When your extension is loaded, register your input parser with @command{gawk} using the @code{register_input_parser()} API function -(described below). +(described next). @end enumerate An @code{awk_input_buf_t} looks like this: @@ -31351,7 +31481,7 @@ The name of the file. @item int fd; A file descriptor for the file. If @command{gawk} was able to -open the file, then @code{fd} will @emph{not} be equal to +open the file, then @code{fd} will @emph{not} be equal to @code{INVALID_HANDLE}. Otherwise, it will. @item struct stat sbuf; @@ -31365,15 +31495,15 @@ The decision can be made based upon @command{gawk} state (the value of a variable defined previously by the extension and set by @command{awk} code), the name of the file, whether or not the file descriptor is valid, the information -in the @code{struct stat}, or any combination of the above. +in the @code{struct stat}, or any combination of these factors. Once @code{@var{XXX}_can_take_file()} has returned true, and @command{gawk} has decided to use your input parser, it calls @code{@var{XXX}_take_control_of()}. That function then fills one of either the @code{get_record} field or the @code{read_func} field in the @code{awk_input_buf_t}. It must also ensure that @code{fd} is @emph{not} -set to @code{INVALID_HANDLE}. All of the fields that may be filled by -@code{@var{XXX}_take_control_of()} are as follows: +set to @code{INVALID_HANDLE}. The following list describes the fields that +may be filled by @code{@var{XXX}_take_control_of()}: @table @code @item void *opaque; @@ -31388,13 +31518,13 @@ is not required to use this pointer. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len); This function pointer should point to a function that creates the input records. Said function is the core of the input parser. Its behavior -is described below. +is described in the text following this list. @item ssize_t (*read_func)(); This function pointer should point to function that has the same behavior as the standard POSIX @code{read()} system call. It is an alternative to the @code{get_record} pointer. Its behavior -is also described below. +is also described in the text following this list. @item void (*close_func)(struct awk_input *iobuf); This function pointer should point to a function that does @@ -31532,7 +31662,7 @@ values, etc.) within @command{gawk}. The function pointed to by this field is called when @command{gawk} decides to let the output wrapper take control of the file. It should fill in appropriate members of the @code{awk_output_buf_t} structure, -as described below, and return true if successful, false otherwise. +as described next, and return true if successful, false otherwise. @item awk_const struct output_wrapper *awk_const next; This is for use by @command{gawk}; @@ -31675,9 +31805,9 @@ Register the two-way processor pointed to by @code{two_way_processor} with @cindex messages from extensions You can print different kinds of warning messages from your -extension, as described below. Note that for these functions, +extension, as described here. Note that for these functions, you must pass in the extension id received from @command{gawk} -when the extension was loaded.@footnote{Because the API uses only ISO C 90 +when the extension was loaded:@footnote{Because the API uses only ISO C 90 features, it cannot make use of the ISO C 99 variadic macro feature to hide that parameter. More's the pity.} @@ -31734,7 +31864,7 @@ value type, as appropriate. This behavior is summarized in @ref{table-value-types-returned}. @float Table,table-value-types-returned -@caption{API Value Types Returned} +@caption{API value types returned} @docbook <informaltable> <tgroup cols="6"> @@ -31746,7 +31876,7 @@ value type, as appropriate. This behavior is summarized in <colspec colwidth="16.6*" colname="c6"/> <spanspec spanname="hspan" namest="c3" nameend="c6" align="center"/> <thead> - <row><entry></entry><entry spanname="hspan"><para>Type of Actual Value:</para></entry></row> + <row><entry></entry><entry spanname="hspan"><para>Type of Actual Value</para></entry></row> <row> <entry></entry> <entry></entry> @@ -31782,7 +31912,7 @@ value type, as appropriate. This behavior is summarized in <entry><para>false</para></entry> </row> <row> - <entry><para><emphasis role="bold">Requested:</emphasis></para></entry> + <entry><para><emphasis role="bold">Requested</emphasis></para></entry> <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> <entry><para>Scalar</para></entry> <entry><para>Scalar</para></entry> @@ -31813,7 +31943,7 @@ value type, as appropriate. This behavior is summarized in @ifnotplaintext @ifnotdocbook @multitable @columnfractions .50 .50 -@headitem @tab Type of Actual Value: +@headitem @tab Type of Actual Value @end multitable @c 10/2014: Thanks to Karl Berry for this bit to reduce the space: @tex @@ -31824,7 +31954,7 @@ value type, as appropriate. This behavior is summarized in @item @tab @b{String} @tab String @tab String @tab false @tab false @item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false @item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false -@item @b{Requested:} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false +@item @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false @item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined @item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false @end multitable @@ -31878,7 +32008,7 @@ indicates the type of value expected. @item awk_bool_t set_argument(size_t count, awk_array_t array); Convert a parameter that was undefined into an array; this provides call-by-reference for arrays. Return false if @code{count} is too big, -or if the argument's type is not undefined. @xref{Array Manipulation}, +or if the argument's type is not undefined. @DBXREF{Array Manipulation} for more information on creating arrays. @end table @@ -31933,7 +32063,7 @@ cannot change any of those variables. @quotation CAUTION It is possible for the lookup of @code{PROCINFO} to fail. This happens if the @command{awk} program being run does not reference @code{PROCINFO}; -in this case @command{gawk} doesn't bother to create the array and +in this case, @command{gawk} doesn't bother to create the array and populate it. @end quotation @@ -31943,9 +32073,9 @@ populate it. A @dfn{scalar cookie} is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up variables in @command{gawk}'s symbol table every time -access is needed. This was discussed earlier, in @ref{General Data Types}. +access is needed. This was discussed earlier in @ref{General Data Types}. -The following functions let you work with scalar cookies. +The following functions let you work with scalar cookies: @table @code @item awk_bool_t sym_lookup_scalar(awk_scalar_t cookie, @@ -31990,18 +32120,21 @@ do_magic(int nargs, awk_value_t *result) @noindent This code looks (and is) simple and straightforward. So what's the problem? -Consider what happens if @command{awk}-level code associated with your -extension calls the @code{magic()} function (implemented in C by @code{do_magic()}), -once per record, while processing hundreds of thousands or millions of records. -The @code{MAGIC_VAR} variable is looked up in the symbol table once or twice per function call! +Well, consider what happens if @command{awk}-level code associated +with your extension calls the @code{magic()} function (implemented in +C by @code{do_magic()}), once per record, while processing hundreds +of thousands or millions of records. The @code{MAGIC_VAR} variable is +looked up in the symbol table once or twice per function call! -The symbol table lookup is really pure overhead; it is considerably more efficient -to get a cookie that represents the variable, and use that to get the variable's -value and update it as needed.@footnote{The difference is measurable and quite real. Trust us.} +The symbol table lookup is really pure overhead; it is considerably +more efficient to get a cookie that represents the variable, and use +that to get the variable's value and update it as needed.@footnote{The +difference is measurable and quite real. Trust us.} -Thus, the way to use cookies is as follows. First, install your extension's variable -in @command{gawk}'s symbol table using @code{sym_update()}, as usual. Then get a -scalar cookie for the variable using @code{sym_lookup()}: +Thus, the way to use cookies is as follows. First, install +your extension's variable in @command{gawk}'s symbol table using +@code{sym_update()}, as usual. Then get a scalar cookie for the variable +using @code{sym_lookup()}: @example static awk_scalar_t magic_var_cookie; /* cookie for MAGIC_VAR */ @@ -32064,7 +32197,7 @@ or @code{sym_update_scalar()}, as you like. However, you can understand the point of cached values if you remember that @emph{every} string value's storage @emph{must} come from @code{gawk_malloc()}, -@code{gawk_calloc()} or @code{gawk_realloc()}. +@code{gawk_calloc()}, or @code{gawk_realloc()}. If you have 20 variables, all of which have the same string value, you must create 20 identical copies of the string.@footnote{Numeric values are clearly less problematic, requiring only a C @code{double} to store.} @@ -32075,11 +32208,11 @@ is what the routines in this section let you do. The functions are as follows: @table @code @item awk_bool_t create_value(awk_value_t *value, awk_value_cookie_t *result); -Create a cached string or numeric value from @code{value} for efficient later -assignment. -Only values of type @code{AWK_NUMBER} and @code{AWK_STRING} are allowed. Any other type -is rejected. While @code{AWK_UNDEFINED} could be allowed, doing so would -result in inferior performance. +Create a cached string or numeric value from @code{value} for +efficient later assignment. Only values of type @code{AWK_NUMBER} +and @code{AWK_STRING} are allowed. Any other type is rejected. +@code{AWK_UNDEFINED} could be allowed, but doing so would result in +inferior performance. @item awk_bool_t release_value(awk_value_cookie_t vc); Release the memory associated with a value cookie obtained @@ -32100,7 +32233,7 @@ my_extension_init() size_t long_string_len; /* code from earlier */ - @dots{} + @dots{} /* @dots{} fill in long_string and long_string_len @dots{} */ make_malloced_string(long_string, long_string_len, & value); create_value(& value, & answer_cookie); /* create cookie */ @@ -32130,7 +32263,7 @@ do_magic(int nargs, awk_value_t *result) @end example @noindent -Using value cookies in this way saves considerable storage, since all of +Using value cookies in this way saves considerable storage, as all of @code{VAR1} through @code{VAR100} share the same value. You might be wondering, ``Is this sharing problematic? @@ -32152,7 +32285,7 @@ you should release any cached values that you created, using @subsection Array Manipulation @cindex array manipulation in extensions -The primary data structure@footnote{Okay, the only data structure.} in @command{awk} +The primary data structure@footnote{OK, the only data structure.} in @command{awk} is the associative array (@pxref{Arrays}). Extensions need to be able to manipulate @command{awk} arrays. The API provides a number of data structures for working with arrays, @@ -32173,7 +32306,7 @@ both work with and create true arrays of arrays (@pxref{General Data Types}). @node Array Data Types @subsubsection Array Data Types -The data types associated with arrays are listed below. +The data types associated with arrays are as follows: @table @code @item typedef void *awk_array_t; @@ -32292,7 +32425,7 @@ The following functions relate to arrays as a whole: @table @code @item awk_array_t create_array(void); Create a new array to which elements may be added. -@xref{Creating Arrays}, for a discussion of how to +@DBXREF{Creating Arrays} for a discussion of how to create a new array and add elements to it. @item awk_bool_t clear_array(awk_array_t a_cookie); @@ -32327,7 +32460,7 @@ The function returns true upon success, false otherwise. @node Flattening Arrays @subsubsection Working With All The Elements of an Array -To @dfn{flatten} an array is create a structure that +To @dfn{flatten} an array is to create a structure that represents the full array in a fashion that makes it easy for C code to traverse the entire array. Test code in @file{extension/testext.c} does this, and also serves @@ -32495,7 +32628,7 @@ code) once you have called @code{release_flattened_array()}: @} @end example -Finally, since everything was successful, the function sets the +Finally, because everything was successful, the function sets the return value to success, and returns: @example @@ -32530,7 +32663,7 @@ code can access them and manipulate them. There are two important points about creating arrays from extension code: -@enumerate 1 +@itemize @value{BULLET} @item You must install a new array into @command{gawk}'s symbol table immediately upon creating it. Once you have done so, @@ -32552,7 +32685,7 @@ using @code{sym_update()}, or install it as an element in a previously existing array using @code{set_array_element()}. We show example code shortly. @item -Due to gawk internals, after using @code{sym_update()} to install an array +Due to @command{gawk} internals, after using @code{sym_update()} to install an array into @command{gawk}, you have to retrieve the array cookie from the value passed in to @command{sym_update()} before doing anything else with it, like so: @@ -32572,7 +32705,7 @@ new_array = val.array_cookie; /* YOU MUST DO THIS */ If installing an array as a subarray, you must also retrieve the value of the array cookie after the call to @code{set_element()}. -@end enumerate +@end itemize The following C code is a simple test extension to create an array with two regular elements and with a subarray. The leading @code{#include} @@ -32691,7 +32824,7 @@ dl_load_func(func_table, testarray, "") @end ignore @end example -Here is sample script that loads the extension +Here is a sample script that loads the extension and then dumps the array: @example @@ -32721,7 +32854,7 @@ $ @kbd{AWKLIBPATH=$PWD ./gawk -f subarray.awk} @end example @noindent -(@xref{Finding Extensions}, for more information on the +(@DBXREF{Finding Extensions} for more information on the @env{AWKLIBPATH} environment variable.) @node Extension API Variables @@ -32807,8 +32940,7 @@ whether the corresponding command-line options were enabled when This variable is true if @command{gawk} was invoked with @option{--debug} option. @item do_lint -This variable is true if @command{gawk} was invoked with @option{--lint} option -(@pxref{Options}). +This variable is true if @command{gawk} was invoked with @option{--lint} option. @item do_mpfr This variable is true if @command{gawk} was invoked with @option{--bignum} option. @@ -32833,8 +32965,8 @@ The others should not change during execution. As mentioned earlier (@pxref{Extension Mechanism Outline}), the function definitions as presented are really macros. To use these macros, your extension must provide a small amount of boilerplate code (variables and -functions) towards the top of your source file, using pre-defined names -as described below. The boilerplate needed is also provided in comments +functions) toward the top of your source file, using predefined names +as described here. The boilerplate needed is also provided in comments in the @file{gawkapi.h} header file: @example @@ -32922,7 +33054,7 @@ This macro expands to a @code{dl_load()} function that performs all the necessary initializations. @end table -The point of the all the variables and arrays is to let the +The point of all the variables and arrays is to let the @code{dl_load()} function (from the @code{dl_load_func()} macro) do all the standard work. It does the following: @@ -32957,7 +33089,7 @@ Compiled extensions have to be installed in a directory where built in the default fashion, the directory in which to find extensions is @file{/usr/local/lib/gawk}. You can also specify a search path with a list of directories to search for compiled extensions. -@xref{AWKLIBPATH Variable}, for more information. +@DBXREF{AWKLIBPATH Variable} for more information. @node Extension Example @section Example: Some File Functions @@ -32965,7 +33097,7 @@ path with a list of directories to search for compiled extensions. @quotation @i{No matter where you go, there you are.} -@author Buckaroo Bonzai +@author Buckaroo Banzai @end quotation @c It's enough to show chdir and stat, no need for fts @@ -33138,9 +33270,9 @@ in the @command{gawk} distribution for the complete version.} The file includes a number of standard header files, and then includes the @file{gawkapi.h} header file which provides the API definitions. -Those are followed by the necessary variable declarations +Those are followed by the necessary variable declarations to make use of the API macros and boilerplate code -(@pxref{Extension API Boilerplate}). +(@pxref{Extension API Boilerplate}): @example #ifdef HAVE_CONFIG_H @@ -33181,7 +33313,7 @@ that implements it is called @code{do_foo()}. The function should have two arguments: the first is an @code{int} usually called @code{nargs}, that represents the number of actual arguments for the function. The second is a pointer to an @code{awk_value_t}, usually named -@code{result}. +@code{result}: @example /* do_chdir --- provide dynamically loaded chdir() function for gawk */ @@ -33201,13 +33333,13 @@ do_chdir(int nargs, awk_value_t *result) @end example The @code{newdir} -variable represents the new directory to change to, retrieved +variable represents the new directory to change to, which is retrieved with @code{get_argument()}. Note that the first argument is numbered zero. If the argument is retrieved successfully, the function calls the @code{chdir()} system call. If the @code{chdir()} fails, @code{ERRNO} -is updated. +is updated: @example if (get_argument(0, AWK_STRING, & newdir)) @{ @@ -33408,7 +33540,7 @@ of @code{stat()}) to get the file information, in case the file is a symbolic link. However, if there were three arguments, @code{statfunc} is set point to @code{stat()}, instead. -Here is the @code{do_stat()} function. It starts with +Here is the @code{do_stat()} function, which starts with variable declarations and argument checking: @ignore @@ -33523,7 +33655,7 @@ dl_load_func(func_table, filefuncs, "") And that's it! @node Using Internal File Ops -@subsection Integrating The Extensions +@subsection Integrating the Extensions @cindex @command{gawk}, interpreter@comma{} adding code to Now that the code is written, it must be possible to add it at @@ -33532,9 +33664,9 @@ code must be compiled. Assuming that the functions are in a file named @file{filefuncs.c}, and @var{idir} is the location of the @file{gawkapi.h} header file, the following steps@footnote{In practice, you would probably want to -use the GNU Autotools---Automake, Autoconf, Libtool, and @command{gettext}---to +use the GNU Autotools (Automake, Autoconf, Libtool, and @command{gettext}) to configure and build your libraries. Instructions for doing so are beyond -the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for Internet links to +the scope of this @value{DOCUMENT}. @DBXREF{gawkextlib} for Internet links to the tools.} create a GNU/Linux shared library: @example @@ -33542,7 +33674,7 @@ $ @kbd{gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g -I@var{idir} filefuncs.c} $ @kbd{gcc -o filefuncs.so -shared filefuncs.o} @end example -Once the library exists, it is loaded by using the @code{@@load} keyword. +Once the library exists, it is loaded by using the @code{@@load} keyword: @example # file testff.awk @@ -33606,13 +33738,14 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @end example @node Extension Samples -@section The Sample Extensions In The @command{gawk} Distribution +@section The Sample Extensions in the @command{gawk} Distribution @cindex extensions distributed with @command{gawk} This @value{SECTION} provides brief overviews of the sample extensions that come in the @command{gawk} distribution. Some of them are intended -for production use, such the @code{filefuncs}, @code{readdir} and @code{inplace} extensions. -Others mainly provide example code that shows how to use the extension API. +for production use (e.g., the @code{filefuncs}, @code{readdir} and +@code{inplace} extensions). Others mainly provide example code that +shows how to use the extension API. @menu * Extension Sample File Functions:: The file functions sample. @@ -33633,9 +33766,9 @@ Others mainly provide example code that shows how to use the extension API. @end menu @node Extension Sample File Functions -@subsection File Related Functions +@subsection File-Related Functions -The @code{filefuncs} extension provides three different functions, as follows: +The @code{filefuncs} extension provides three different functions, as follows. The usage is: @table @asis @@ -33646,7 +33779,7 @@ This is how you load the extension. @item @code{result = chdir("/some/directory")} The @code{chdir()} function is a direct hook to the @code{chdir()} system call to change the current directory. It returns zero -upon success or less than zero upon error. In the latter case it updates +upon success or less than zero upon error. In the latter case, it updates @code{ERRNO}. @cindex @code{stat()} extension function @@ -33654,7 +33787,7 @@ upon success or less than zero upon error. In the latter case it updates The @code{stat()} function provides a hook into the @code{stat()} system call. It returns zero upon success or less than zero upon error. -In the latter case it updates @code{ERRNO}. +In the latter case, it updates @code{ERRNO}. By default, it uses the @code{lstat()} system call. However, if passed a third argument, it uses @code{stat()} instead. @@ -33701,8 +33834,8 @@ Not all systems support all file types. @tab All @item @code{flags = or(FTS_PHYSICAL, ...)} @itemx @code{result = fts(pathlist, flags, filedata)} Walk the file trees provided in @code{pathlist} and fill in the -@code{filedata} array as described below. @code{flags} is the bitwise -OR of several predefined values, also described below. +@code{filedata} array as described next. @code{flags} is the bitwise +OR of several predefined values, also described in a moment. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -33750,7 +33883,7 @@ whether or not @code{FTS_LOGICAL} is set. By default, the C library @code{fts()} routines do not return entries for @file{.} (dot) and @file{..} (dot-dot). This option causes entries for dot-dot to also be included. (The extension always includes an entry -for dot, see below.) +for dot; more on this in a moment.) @item FTS_XDEV During a traversal, do not cross onto a different mounted filesystem. @@ -33760,7 +33893,7 @@ During a traversal, do not cross onto a different mounted filesystem. The @code{filedata} array is first cleared. Then, @code{fts()} creates an element in @code{filedata} for every element in @code{pathlist}. The index is the name of the directory or file given in @code{pathlist}. -The element for this index is itself an array. There are two cases. +The element for this index is itself an array. There are two cases: @c nested table @table @emph @@ -33786,8 +33919,8 @@ contain an element named @code{"error"}, which is a string describing the error. @item The path is a directory In this case, the array contains one element for each entry in the -directory. If an entry is a file, that element is as for files, just -described. If the entry is a directory, that element is (recursively), +directory. If an entry is a file, that element is the same as for files, just +described. If the entry is a directory, that element is (recursively) an array describing the subdirectory. If @code{FTS_SEEDOT} was provided in the flags, then there will also be an element named @code{".."}. This element will be an array containing the data as provided by @code{stat()}. @@ -33806,8 +33939,8 @@ The @code{fts()} extension does not exactly mimic the interface of the C library @code{fts()} routines, choosing instead to provide an interface that is based on associative arrays, which is more comfortable to use from an @command{awk} program. This includes the -lack of a comparison function, since @command{gawk} already provides -powerful array sorting facilities. While an @code{fts_read()}-like +lack of a comparison function, because @command{gawk} already provides +powerful array sorting facilities. Although an @code{fts_read()}-like interface could have been provided, this felt less natural than simply creating a multidimensional array to represent the file hierarchy and its information. @@ -33817,7 +33950,7 @@ See @file{test/fts.awk} in the @command{gawk} distribution for an example use of the @code{fts()} extension function. @node Extension Sample Fnmatch -@subsection Interface To @code{fnmatch()} +@subsection Interface to @code{fnmatch()} This extension provides an interface to the C library @code{fnmatch()} function. The usage is: @@ -33830,10 +33963,10 @@ This is how you load the extension. @item result = fnmatch(pattern, string, flags) The return value is zero on success, @code{FNM_NOMATCH} if the string did not match the pattern, or -a different non-zero value if an error occurred. +a different nonzero value if an error occurred. @end table -Besides the @code{fnmatch()} function, the @code{fnmatch} extension +In addition to the @code{fnmatch()} function, the @code{fnmatch} extension adds one constant (@code{FNM_NOMATCH}), and an array of flag values named @code{FNM}. @@ -33851,7 +33984,7 @@ Either zero, or the bitwise OR of one or more of the flags in the @code{FNM} array. @end table -The flags are follows: +The flags are as follows: @multitable @columnfractions .25 .75 @headitem Array element @tab Corresponding flag defined by @code{fnmatch()} @@ -33874,9 +34007,9 @@ if (fnmatch("*.a", "foo.c", flags) == FNM_NOMATCH) @end example @node Extension Sample Fork -@subsection Interface To @code{fork()}, @code{wait()} and @code{waitpid()} +@subsection Interface to @code{fork()}, @code{wait()}, and @code{waitpid()} -The @code{fork} extension adds three functions, as follows. +The @code{fork} extension adds three functions, as follows: @table @code @item @@load "fork" @@ -33974,7 +34107,7 @@ $ @kbd{gawk -i inplace -v INPLACE_SUFFIX=.bak '@{ gsub(/foo/, "bar") @}} @subsection Character and Numeric values: @code{ord()} and @code{chr()} The @code{ordchr} extension adds two functions, named -@code{ord()} and @code{chr()}, as follows. +@code{ord()} and @code{chr()}, as follows: @table @code @item @@load "ordchr" @@ -34022,7 +34155,7 @@ indicating the type of the file. The letters and their corresponding file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types -@caption{File Types Returned By The @code{readdir} Extension} +@caption{File types returned by the @code{readdir} extension} @multitable @columnfractions .1 .9 @headitem Letter @tab File Type @item @code{b} @tab Block device @@ -34059,7 +34192,7 @@ BEGIN @{ FS = "/" @} @subsection Reversing Output The @code{revoutput} extension adds a simple output wrapper that reverses -the characters in each output line. It's main purpose is to show how to +the characters in each output line. Its main purpose is to show how to write an output wrapper, although it may be mildly amusing for the unwary. Here is an example: @@ -34081,7 +34214,7 @@ The output from this program is: The @code{revtwoway} extension adds a simple two-way processor that reverses the characters in each line sent to it for reading back by -the @command{awk} program. It's main purpose is to show how to write +the @command{awk} program. Its main purpose is to show how to write a two-way processor, although it may also be mildly amusing. The following example shows how to use it: @@ -34108,7 +34241,7 @@ is: @samp{cinap t'nod}. @node Extension Sample Read write array -@subsection Dumping and Restoring An Array +@subsection Dumping and Restoring an Array The @code{rwarray} extension adds two functions, named @code{writea()} and @code{reada()}, as follows: @@ -34134,7 +34267,7 @@ Here too, the return value is one on success and zero upon failure. The array created by @code{reada()} is identical to that written by @code{writea()} in the sense that the contents are the same. However, -due to implementation issues, the array traversal order of the recreated +due to implementation issues, the array traversal order of the re-created array is likely to be different from that of the original array. As array traversal order in @command{awk} is by default undefined, this is (technically) not a problem. If you need to guarantee a particular traversal @@ -34142,7 +34275,7 @@ order, use the array sorting features in @command{gawk} to do so (@pxref{Array Sorting}). The file contains binary data. All integral values are written in network -byte order. However, double precision floating-point values are written +byte order. However, double-precision floating-point values are written as native binary data. Thus, arrays containing only string data can theoretically be dumped on systems with one byte order and restored on systems with a different one, but this has not been tried. @@ -34158,7 +34291,7 @@ ret = reada("arraydump.bin", array) @end example @node Extension Sample Readfile -@subsection Reading An Entire File +@subsection Reading an Entire File The @code{readfile} extension adds a single function named @code{readfile()}, and an input parser: @@ -34205,7 +34338,7 @@ This is how you load the extension. @cindex @code{gettimeofday()} extension function @item the_time = gettimeofday() Return the time in seconds that has elapsed since 1970-01-01 UTC as a -floating point value. If the time is unavailable on this platform, return +floating-point value. If the time is unavailable on this platform, return @minus{}1 and set @code{ERRNO}. The returned time should have sub-second precision, but the actual precision may vary based on the platform. If the standard C @code{gettimeofday()} system call is available on this @@ -34244,26 +34377,29 @@ project provides a number of @command{gawk} extensions, including one for processing XML files. This is the evolution of the original @command{xgawk} (XML @command{gawk}) project. -As of this writing, there are five extensions: +As of this writing, there are six extensions: @itemize @value{BULLET} @item -GD graphics library extension. +GD graphics library extension + +@item +PDF extension @item -PDF extension. +PostgreSQL extension @item -PostgreSQL extension. +MPFR library extension +(this provides access to a number of MPFR functions which @command{gawk}'s +native MPFR support does not) @item -MPFR library extension. -This provides access to a number of MPFR functions which @command{gawk}'s -native MPFR support does not. +Redis extension @item XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} -XML parsing library. +XML parsing library @end itemize @cindex @command{git} utility @@ -34314,9 +34450,9 @@ to install both @command{gawk} and @code{gawkextlib}, depending upon how your system works. If you write an extension that you wish to share with other -@command{gawk} users, please consider doing so through the +@command{gawk} users, consider doing so through the @code{gawkextlib} project. -See the project's web site for more information. +See the project's website for more information. @node Extension summary @section Summary @@ -34324,7 +34460,7 @@ See the project's web site for more information. @itemize @value{BULLET} @item You can write extensions (sometimes called plug-ins) for @command{gawk} -in C or C++ using the Application Programming Interface (API) defined +in C or C++ using the application programming interface (API) defined by the @command{gawk} developers. @item @@ -34355,44 +34491,44 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item -Allocating, reallocating, and releasing memory. +Allocating, reallocating, and releasing memory @item -Registration functions. You may register +Registration functions (you may register extension functions, exit callbacks, a version string, input parsers, output wrappers, -and two-way processors. +and two-way processors) @item -Printing fatal, warning, and ``lint'' warning messages. +Printing fatal, warning, and ``lint'' warning messages @item -Updating @code{ERRNO}, or unsetting it. +Updating @code{ERRNO}, or unsetting it @item Accessing parameters, including converting an undefined parameter into -an array. +an array @item -Symbol table access: retrieving a global variable, creating one, -or changing one. +Symbol table access (retrieving a global variable, creating one, +or changing one) @item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and -can be a big performance win. +can be a big performance win @item -Manipulating arrays: -retrieving, adding, deleting, and modifying elements; +Manipulating arrays +(retrieving, adding, deleting, and modifying elements; getting the count of elements in an array; creating a new array; clearing an array; and -flattening an array for easy C style looping over all its indices and elements. +flattening an array for easy C style looping over all its indices and elements) @end itemize @item @@ -34421,8 +34557,8 @@ that loaded it. @item It is easiest to start a new extension by copying the boilerplate code -described in this @value{CHAPTER}. Macros in the @file{gawkapi.h} make -this easier to do. +described in this @value{CHAPTER}. Macros in the @file{gawkapi.h} header +file make this easier to do. @item The @command{gawk} distribution includes a number of small but useful @@ -34471,34 +34607,34 @@ and the Glossary: @end ifclear @ifset FOR_PRINT -Part IV contains two appendices and the license that +Part IV contains three appendices, the last of which is the license that covers the @command{gawk} source code: @end ifset @itemize @value{BULLET} @item -@ref{Language History}. +@ref{Language History} @item -@ref{Installation}. +@ref{Installation} @ifclear FOR_PRINT @item -@ref{Notes}. +@ref{Notes} @item -@ref{Basic Concepts}. +@ref{Basic Concepts} @item -@ref{Glossary}. +@ref{Glossary} @end ifclear @item -@ref{Copying}. +@ref{Copying} @ifclear FOR_PRINT @item -@ref{GNU Free Documentation License}. +@ref{GNU Free Documentation License} @end ifclear @end itemize @end ifdocbook @@ -34507,7 +34643,7 @@ covers the @command{gawk} source code: @appendix The Evolution of the @command{awk} Language This @value{DOCUMENT} describes the GNU implementation of @command{awk}, -which follows the POSIX specification. Many long-time @command{awk} +which follows the POSIX specification. Many longtime @command{awk} users learned @command{awk} programming with the original @command{awk} implementation in Version 7 Unix. (This implementation was the basis for @command{awk} in Berkeley Unix, through 4.3-Reno. Subsequent versions @@ -34675,7 +34811,7 @@ for case translation (@pxref{String Functions}). @item -A cleaner specification for the @code{%c} format-control letter in the +A cleaner specification for the @samp{%c} format-control letter in the @code{printf} function (@pxref{Control Letters}). @@ -34742,7 +34878,7 @@ The ability to delete all of an array at once with @samp{delete @var{array}} @end itemize -@xref{Common Extensions}, for a list of common extensions +@DBXREF{Common Extensions} for a list of common extensions not permitted by the POSIX standard. The 2008 POSIX standard can be found online at @@ -34762,7 +34898,7 @@ has made his version available via his home page (@pxref{Other Versions}). This @value{SECTION} describes common extensions that -originally appeared in his version of @command{awk}. +originally appeared in his version of @command{awk}: @itemize @value{BULLET} @item @@ -34788,7 +34924,7 @@ or array elements through it. @end ignore @end itemize -@xref{Common Extensions}, for a full list of the extensions +@DBXREF{Common Extensions} for a full list of the extensions available in his @command{awk}. @node POSIX/GNU @@ -34844,7 +34980,7 @@ The @file{/dev/stdin}, @file{/dev/stdout}, @file{/dev/stderr} and @item The @file{/inet}, @file{/inet4}, and @samp{/inet6} special files for TCP/IP networking using @samp{|&} to specify which version of the -IP protocol to use. +IP protocol to use (@pxref{TCP/IP Networking}). @end itemize @@ -34892,7 +35028,7 @@ New keywords: @itemize @value{MINUS} @item -The @code{BEGINFILE} and @code{ENDFILE} special patterns. +The @code{BEGINFILE} and @code{ENDFILE} special patterns (@pxref{BEGINFILE/ENDFILE}). @item @@ -34929,7 +35065,7 @@ making translations easier @item The @code{split()} function's additional optional fourth -argument which is an array to hold the text of the field separators. +argument which is an array to hold the text of the field separators (@pxref{String Functions}). @end itemize @@ -35696,7 +35832,7 @@ load @command{awk} library files. @item The @option{-l} and @option{--load} options load compiled dynamic extensions. -@item +@item The @option{-M} and @option{--bignum} options enable MPFR. @item @@ -35735,7 +35871,7 @@ The dynamic extension interface was completely redone @cindex extensions, @command{mawk} The following table summarizes the common extensions supported by @command{gawk}, Brian Kernighan's @command{awk}, and @command{mawk}, -the three most widely-used freely available versions of @command{awk} +the three most widely used freely available versions of @command{awk} (@pxref{Other Versions}). @multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} {Now standard} @@ -35753,7 +35889,7 @@ the three most widely-used freely available versions of @command{awk} @item @code{func} keyword @tab X @tab @tab X @tab @item @code{BINMODE} variable @tab @tab X @tab X @tab @item @code{RS} as regexp @tab @tab X @tab X @tab -@item Time related functions @tab @tab X @tab X @tab +@item Time-related functions @tab @tab X @tab X @tab @end multitable @node Ranges and Locales @@ -35769,7 +35905,7 @@ the first character in the range and the last character in the range, inclusive. Ordering was based on the numeric value of each character in the machine's native character set. Thus, on ASCII-based systems, @samp{[a-z]} matched all the lowercase letters, and only the lowercase -letters, since the numeric values for the letters from @samp{a} through +letters, as the numeric values for the letters from @samp{a} through @samp{z} were contiguous. (On an EBCDIC system, the range @samp{[a-z]} includes additional, non-alphabetic characters as well.) @@ -35780,8 +35916,8 @@ that @samp{[A-Z]} was the ``correct'' way to match uppercase letters. And indeed, this was true.@footnote{And Life was good.} The 1992 POSIX standard introduced the idea of locales (@pxref{Locales}). -Since many locales include other letters besides the plain twenty-six -letters of the American English alphabet, the POSIX standard added +Because many locales include other letters besides the plain 26 +letters of the English alphabet, the POSIX standard added character classes (@pxref{Bracket Expressions}) as a way to match different kinds of characters besides the traditional ones in the ASCII character set. @@ -35798,7 +35934,7 @@ In other words, these locales sort characters in dictionary order, and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; instead it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. -This point needs to be emphasized: Much literature teaches that you should +This point needs to be emphasized: much literature teaches that you should use @samp{[a-z]} to match a lowercase character. But on systems with non-ASCII locales, this also matches all of the uppercase characters except @samp{A} or @samp{Z}! This was a continuous cause of confusion, even well @@ -35814,7 +35950,7 @@ $ @kbd{echo something1234abc | gawk-3.1.8 '@{ sub("[A-Z]*$", ""); print @}'} @end example @noindent -This output is unexpected, since the @samp{bc} at the end of +This output is unexpected, as the @samp{bc} at the end of @samp{something1234abc} should not normally match @samp{[A-Z]*}. This result is due to the locale setting (and thus you may not see it on your system). @@ -35836,7 +35972,7 @@ like ``why does @samp{[A-Z]} match lowercase letters?!?'' @cindex Berry, Karl This situation existed for close to 10 years, if not more, and the @command{gawk} maintainer grew weary of trying to explain that -@command{gawk} was being nicely standards-compliant, and that the issue +@command{gawk} was being nicely standards compliant, and that the issue was in the user's locale. During the development of @value{PVERSION} 4.0, he modified @command{gawk} to always treat ranges in the original, pre-POSIX fashion, unless @option{--posix} was used (@pxref{Options}).@footnote{And @@ -36049,7 +36185,7 @@ Michael Benzinger contributed the initial code for @code{switch} statements. @cindex McPhee, Patrick Patrick T.J.@: McPhee contributed the code for dynamic loading in Windows32 environments. -(This is no longer supported) +(This is no longer supported.) @item @cindex Wallin, Anders @@ -36073,7 +36209,7 @@ into a byte-code interpreter, including the debugger. The addition of true arrays of arrays. @item -The additional modifications for support of arbitrary precision arithmetic. +The additional modifications for support of arbitrary-precision arithmetic. @item The initial text of @@ -36129,7 +36265,7 @@ helping David Trueman, and as the primary maintainer since around 1994. @itemize @value{BULLET} @item The @command{awk} language has evolved over time. The first release -was with V7 Unix circa 1978. In 1987 for System V Release 3.1, +was with V7 Unix circa 1978. In 1987, for System V Release 3.1, major additions, including user-defined functions, were made to the language. Additional changes were made for System V Release 4, in 1989. Since then, further minor changes happen under the auspices of the @@ -36171,8 +36307,8 @@ This appendix provides instructions for installing @command{gawk} on the various platforms that are supported by the developers. The primary developer supports GNU/Linux (and Unix), whereas the other ports are contributed. -@xref{Bugs}, -for the electronic mail addresses of the people who maintain +@DBXREF{Bugs} +for the email addresses of the people who maintain the respective ports. @menu @@ -36226,7 +36362,7 @@ wget http://ftp.gnu.org/gnu/gawk/gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz The GNU software archive is mirrored around the world. The up-to-date list of mirror sites is available from -@uref{http://www.gnu.org/order/ftp.html, the main FSF web site}. +@uref{http://www.gnu.org/order/ftp.html, the main FSF website}. Try to use one of the mirrors; they will be less busy, and you can usually find one closer to your site. @@ -36237,7 +36373,7 @@ different compression programs: @command{gzip}, @command{bzip2}, and @command{xz}. For simplicity, the rest of these instructions assume you are using the one compressed with the GNU Zip program, @code{gzip}. -Once you have the distribution (for example, +Once you have the distribution (e.g., @file{gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz}), use @code{gzip} to expand the file and then use @code{tar} to extract it. You can use the following @@ -36330,7 +36466,7 @@ as a list of things that the POSIX standard should describe but does not. @item doc/awkforai.txt Pointers to the original draft of a short article describing why @command{gawk} is a good language for -Artificial Intelligence (AI) programming. +artificial intelligence (AI) programming. @item doc/bc_notes A brief description of @command{gawk}'s ``byte code'' internals. @@ -36461,11 +36597,11 @@ Files needed for building @command{gawk} under MS-Windows @ifclear FOR_PRINT and OS/2 @end ifclear -(@pxref{PC Installation}, for details). +(@DBPXREF{PC Installation} for details). @item vms/* Files needed for building @command{gawk} under Vax/VMS and OpenVMS -(@pxref{VMS Installation}, for details). +(@DBPXREF{VMS Installation} for details). @item test/* A test suite for @@ -36477,7 +36613,7 @@ be confident of a successful port. @c ENDOFRANGE gawdis @node Unix Installation -@appendixsec Compiling and Installing @command{gawk} on Unix-like Systems +@appendixsec Compiling and Installing @command{gawk} on Unix-Like Systems Usually, you can compile and install @command{gawk} by typing only two commands. However, if you use an unusual system, you may need @@ -36491,7 +36627,7 @@ to configure @command{gawk} for your system yourself. @end menu @node Quick Installation -@appendixsubsec Compiling @command{gawk} for Unix-like Systems +@appendixsubsec Compiling @command{gawk} for Unix-Like Systems The normal installation steps should work on all modern commercial Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin @@ -36508,7 +36644,7 @@ described fully in @cite{Autoconf---Generating Automatic Configuration Scripts}, which can be found online at @uref{http://www.gnu.org/software/autoconf/manual/index.html, -the Free Software Foundation's web site}.) +the Free Software Foundation's website}.) @end ifnotinfo @ifinfo (The Autoconf software is described fully starting with @@ -36555,7 +36691,7 @@ run @samp{make check}. All of the tests should succeed. If these steps do not work, or if any of the tests fail, check the files in the @file{README_d} directory to see if you've found a known problem. If the failure is not described there, -please send in a bug report (@pxref{Bugs}). +send in a bug report (@pxref{Bugs}). Of course, once you've built @command{gawk}, it is likely that you will wish to install it. To do so, you need to run the command @samp{make @@ -36657,7 +36793,7 @@ function for deficient systems. @end table Use the command @samp{./configure --help} to see the full list of -options that @command{configure} supplies. +options supplied by @command{configure}. @node Configuration Philosophy @appendixsubsec The Configuration Process @@ -36691,19 +36827,19 @@ facts about your operating system. For example, there may not be an @cindex @code{custom.h} file It is possible for your C compiler to lie to @command{configure}. It may do so by not exiting with an error when a library function is not -available. To get around this, edit the file @file{custom.h}. +available. To get around this, edit the @file{custom.h} file. Use an @samp{#ifdef} that is appropriate for your system, and either @code{#define} any constants that @command{configure} should have defined but didn't, or @code{#undef} any constants that @command{configure} defined and -should not have. @file{custom.h} is automatically included by -@file{config.h}. +should not have. The @file{custom.h} file is automatically included by +the @file{config.h} file. It is also possible that the @command{configure} program generated by Autoconf will not work on your system in some other fashion. -If you do have a problem, the file @file{configure.ac} is the input for +If you do have a problem, the @file{configure.ac} file is the input for Autoconf. You may be able to change this file and generate a new version of @command{configure} that works on your system -(@pxref{Bugs}, +(@DBPXREF{Bugs} for information on how to report problems in configuring @command{gawk}). The same mechanism may be used to send in updates to @file{configure.ac} and/or @file{custom.h}. @@ -36743,7 +36879,7 @@ The limitations of MS-DOS (and MS-DOS shells under the other operating systems) has meant that various ``DOS extenders'' are often used with programs such as @command{gawk}. The varying capabilities of Microsoft Windows 3.1 and Windows32 can add to the confusion. For an overview -of the considerations, please refer to @file{README_d/README.pc} in +of the considerations, refer to @file{README_d/README.pc} in the distribution. @menu @@ -36906,7 +37042,7 @@ Ancient OS/2 ports of GNU @command{make} are not able to handle the Makefiles of this package. If you encounter any problems with @command{make}, try GNU Make 3.79.1 or later versions. You should find the latest version on -@uref{ftp://hobbes.nmsu.edu/pub/os2/}.@footnote{As of May, 2014, +@uref{ftp://hobbes.nmsu.edu/pub/os2/}.@footnote{As of November 2014, this site is still there, but the author could not find a package for GNU Make.} @end quotation @@ -37116,7 +37252,7 @@ need to use the @code{BINMODE} variable. This can cause problems with other Unix-like components that have been ported to MS-Windows that expect @command{gawk} to do automatic -translation of @code{"\r\n"}, since it won't. +translation of @code{"\r\n"}, because it won't. @node VMS Installation @appendixsubsec Compiling and Installing @command{gawk} on Vax/VMS and OpenVMS @@ -37180,14 +37316,14 @@ The most recent builds used HP C V7.3 on Alpha VMS 8.3 and both Alpha and IA64 VMS 8.4 used HP C 7.3.@footnote{The IA64 architecture is also known as ``Itanium.''} -@xref{VMS GNV}, for information on building +@DBXREF{VMS GNV} for information on building @command{gawk} as a PCSI kit that is compatible with the GNV product. @node VMS Dynamic Extensions @appendixsubsubsec Compiling @command{gawk} Dynamic Extensions on VMS The extensions that have been ported to VMS can be built using one of -the following commands. +the following commands: @example $ @kbd{MMS/DESCRIPTION=[.vms]descrip.mms extensions} @@ -37204,7 +37340,7 @@ $ @kbd{MMK/DESCRIPTION=[.vms]descrip.mms extensions} or a logical name to find the dynamic extensions. Dynamic extensions need to be compiled with the same compiler options for -floating point, pointer size, and symbol name handling as were used +floating-point, pointer size, and symbol name handling as were used to compile @command{gawk} itself. Alpha and Itanium should use IEEE floating point. The pointer size is 32 bits, and the symbol name handling should be exact case with CRC shortening for @@ -37334,7 +37470,7 @@ Note that uppercase and mixed-case text must be quoted. The VMS port of @command{gawk} includes a @code{DCL}-style interface in addition to the original shell-style interface (see the help entry for details). One side effect of dual command-line parsing is that if there is only a -single parameter (as in the quoted string program above), the command +single parameter (as in the quoted string program), the command becomes ambiguous. To work around this, the normally optional @option{--} flag is required to force Unix-style parsing rather than @code{DCL} parsing. If any other dash-type options (or multiple parameters such as @value{DF}s to @@ -37454,10 +37590,10 @@ recommend compiling and using the current version. @node Bugs @appendixsec Reporting Problems and Bugs -@cindex archeologists +@cindex archaeologists @quotation -@i{There is nothing more dangerous than a bored archeologist.} -@author The Hitchhiker's Guide to the Galaxy +@i{There is nothing more dangerous than a bored archaeologist.} +@author Douglas Adams, @cite{The Hitchhiker's Guide to the Galaxy} @end quotation @c the radio show, not the book. :-) @@ -37466,10 +37602,10 @@ recommend compiling and using the current version. @c STARTOFRANGE tblgawb @cindex troubleshooting, @command{gawk}, bug reports If you have problems with @command{gawk} or think that you have found a bug, -please report it to the developers; we cannot promise to do anything +report it to the developers; we cannot promise to do anything but we might well want to fix it. -Before reporting a bug, please make sure you have really found a genuine bug. +Before reporting a bug, make sure you have really found a genuine bug. Carefully reread the documentation and see if it says you can do what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation! @@ -37482,7 +37618,7 @@ the compiler you used to compile @command{gawk}, and the exact results @command{gawk} gave you. Also say what you expected to occur; this helps us decide whether the problem is really in the documentation. -Please include the version number of @command{gawk} you are using. +Make sure to include the version number of @command{gawk} you are using. You can get this information with the command @samp{gawk --version}. @cindex @code{bug-gawk@@gnu.org} bug reporting address @@ -37494,7 +37630,7 @@ Once you have a precise problem description, send email to The @command{gawk} maintainers subscribe to this address and thus they will receive your bug report. Although you can send mail to the maintainers directly, -the bug reporting address is preferred since the +the bug reporting address is preferred because the email list is archived at the GNU Project. @emph{All email must be in English. This is the only language understood in common by all the maintainers.} @@ -37503,19 +37639,19 @@ understood in common by all the maintainers.} @quotation CAUTION Do @emph{not} try to report bugs in @command{gawk} by posting to the Usenet/Internet newsgroup @code{comp.lang.awk}. -While the @command{gawk} developers do occasionally read this newsgroup, -there is no guarantee that we will see your posting. The steps described -above are the only official recognized way for reporting bugs. +The @command{gawk} developers do occasionally read this newsgroup, +but there is no guarantee that we will see your posting. The steps described +here are the only officially recognized way for reporting bugs. Really. @end quotation @quotation NOTE Many distributions of GNU/Linux and the various BSD-based operating systems have their own bug reporting systems. If you report a bug using your distribution's -bug reporting system, @emph{please} also send a copy to +bug reporting system, you should also send a copy to @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. -This is for two reasons. First, while some distributions forward +This is for two reasons. First, although some distributions forward bug reports ``upstream'' to the GNU mailing list, many don't, so there is a good chance that the @command{gawk} maintainers won't even see the bug report! Second, mail to the GNU list is archived, and having everything at the GNU project @@ -37526,8 +37662,8 @@ Non-bug suggestions are always welcome as well. If you have questions about things that are unclear in the documentation or are just obscure features, ask on the bug list; we will try to help you out if we can. -If you find bugs in one of the non-Unix ports of @command{gawk}, please -send an electronic mail message to the bug list, with a copy to the +If you find bugs in one of the non-Unix ports of @command{gawk}, +send an email to the bug list, with a copy to the person who maintains that port. They are named in the following list, as well as in the @file{README} file in the @command{gawk} distribution. Information in the @file{README} file should be considered authoritative @@ -37558,9 +37694,8 @@ The people maintaining the various @command{gawk} ports are: @item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. @end multitable -If your bug is also reproducible under Unix, please send a copy of your -report to the @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org} email -list as well. +If your bug is also reproducible under Unix, send a copy of your +report to the @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org} email list as well. @c ENDOFRANGE dbugg @c ENDOFRANGE tblgawb @@ -37603,7 +37738,7 @@ This @value{SECTION} briefly describes where to get them: Brian Kernighan, one of the original designers of Unix @command{awk}, has made his implementation of @command{awk} freely available. -You can retrieve this version via the World Wide Web from +You can retrieve this version via @uref{http://www.cs.princeton.edu/~bwk, his home page}. It is available in several archive formats: @@ -37626,7 +37761,7 @@ git clone git://github.com/onetrueawk/awk bwkawk @end example @noindent -The above command creates a copy of the @uref{http://www.git-scm.com, Git} +This command creates a copy of the @uref{http://www.git-scm.com, Git} repository in a directory named @file{bwkawk}. If you leave that argument off the @command{git} command line, the repository copy is created in a directory named @file{awk}. @@ -37634,9 +37769,13 @@ directory named @file{awk}. This version requires an ISO C (1990 standard) compiler; the C compiler from GCC (the GNU Compiler Collection) works quite nicely. -@xref{Common Extensions}, +@DBXREF{Common Extensions} for a list of extensions in this @command{awk} that are not in POSIX @command{awk}. +As a side note, Dan Bornstein has created a Git repository tracking +all the versions of BWK @command{awk} that he could find. It's +available at @uref{git://github.com/danfuzz/one-true-awk}. + @cindex Brennan, Michael @cindex @command{mawk} utility @cindex source code, @command{mawk} @@ -37666,7 +37805,7 @@ Once you have it, is similar to @command{gawk}'s (@pxref{Unix Installation}). -@xref{Common Extensions}, +@DBXREF{Common Extensions} for a list of extensions in @command{mawk} that are not in POSIX @command{awk}. @cindex Sumner, Andrew @@ -37728,8 +37867,8 @@ has not been done, at least to our knowledge. @cindex Illumos @cindex Illumos, POSIX-compliant @command{awk} @cindex source code, Illumos @command{awk} -The source code used to be available from the OpenSolaris web site. -However, that project was ended and the web site shut down. Fortunately, the +The source code used to be available from the OpenSolaris website. +However, that project was ended and the website shut down. Fortunately, the @uref{http://wiki.illumos.org/display/illumos/illumos+Home, Illumos project} makes this implementation available. You can view the files one at a time from @uref{https://github.com/joyent/illumos-joyent/blob/master/usr/src/cmd/awk_xpg4}. @@ -37748,7 +37887,7 @@ from POSIX @command{awk}. More information is available on the @cindex libmawk @cindex source code, libmawk This is an embeddable @command{awk} interpreter derived from -@command{mawk}. For more information see +@command{mawk}. For more information, see @uref{http://repo.hu/projects/libmawk/}. @item @code{pawk} @@ -37762,7 +37901,7 @@ modified version of BWK @command{awk}, described earlier.) @item @w{QSE Awk} @cindex QSE Awk @cindex source code, QSE Awk -This is an embeddable @command{awk} interpreter. For more information +This is an embeddable @command{awk} interpreter. For more information, see @uref{http://code.google.com/p/qse/} and @uref{http://awk.info/?tools/qse}. @item @command{QTawk} @@ -37777,9 +37916,10 @@ including the manual and a download link. The project may also be frozen; no new code changes have been made since approximately 2008. -@item Other Versions -See also the @uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations, -Wikipedia article}, for information on additional versions. +@item Other versions +See also the ``Versions and implementations'' section of the +@uref{http://en.wikipedia.org/wiki/Awk_language#Versions_and_implementations, +Wikipedia article} for information on additional versions. @end table @c ENDOFRANGE awkim @@ -37981,7 +38121,7 @@ This document describes how GNU software should be written. If you haven't read it, please do so, preferably @emph{before} starting to modify @command{gawk}. (The @cite{GNU Coding Standards} are available from the GNU Project's -@uref{http://www.gnu.org/prep/standards_toc.html, web site}. +@uref{http://www.gnu.org/prep/standards_toc.html, website}. Texinfo, Info, and DVI versions are also available.) @cindex @command{gawk}, coding style in @@ -39066,6 +39206,13 @@ pattern matches an input record, @command{awk} executes the rule's action. Actions are always enclosed in braces. (@xref{Action Overview}.) +@cindex Ada programming language +@cindex programming languages, Ada +@item Ada +A programming language originally defined by the U.S.@: Department of +Defense for embedded programming. It was designed to enforce good +Software Engineering practices. + @cindex Spencer, Henry @cindex @command{sed} utility @cindex amazing @command{awk} assembler (@command{aaa}) @@ -39077,13 +39224,6 @@ microcomputers. It is a good example of a program that would have been better written in another language. You can get it from @uref{http://awk.info/?awk100/aaa}. -@cindex Ada programming language -@cindex programming languages, Ada -@item Ada -A programming language originally defined by the U.S.@: Department of -Defense for embedded programming. It was designed to enforce good -Software Engineering practices. - @cindex amazingly workable formatter (@command{awf}) @cindex @command{awf} (amazingly workable formatter) program @item Amazingly Workable Formatter (@command{awf}) @@ -39847,7 +39987,7 @@ record or a string. @end docbook @c This file is intended to be included within another document, -@c hence no sectioning command or @node. +@c hence no sectioning command or @node. @display Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} @@ -40069,7 +40209,7 @@ terms of section 4, provided that you also meet all of these conditions: @enumerate a -@item +@item The work must carry prominent notices stating that you modified it, and giving a relevant date. @@ -40519,7 +40659,7 @@ state the exclusion of warranty; and each file should have at least the ``copyright'' line and a pointer to where the full notice is found. @smallexample -@var{one line to give the program's name and a brief idea of what it does.} +@var{one line to give the program's name and a brief idea of what it does.} Copyright (C) @var{year} @var{name of author} This program is free software: you can redistribute it and/or modify @@ -40542,7 +40682,7 @@ If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: @smallexample -@var{program} Copyright (C) @var{year} @var{name of author} +@var{program} Copyright (C) @var{year} @var{name of author} This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. This is free software, and you are welcome to redistribute it under certain conditions; type @samp{show c} for details. @@ -530,7 +530,7 @@ posix_compare(NODE *s1, NODE *s2) * In either case, ret will be the right thing to return. */ } -#if MBS_SUPPORT +#if ! defined(__DJGPP__) else { /* Similar logic, using wide characters */ (void) force_wstring(s1); @@ -610,15 +610,14 @@ cmp_nodes(NODE *t1, NODE *t2) const unsigned char *cp1 = (const unsigned char *) t1->stptr; const unsigned char *cp2 = (const unsigned char *) t2->stptr; -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { ret = strncasecmpmbs((const unsigned char *) cp1, (const unsigned char *) cp2, l); - } else -#endif - /* Could use tolower() here; see discussion above. */ - for (ret = 0; l-- > 0 && ret == 0; cp1++, cp2++) - ret = casetable[*cp1] - casetable[*cp2]; + } else { + /* Could use tolower() here; see discussion above. */ + for (ret = 0; l-- > 0 && ret == 0; cp1++, cp2++) + ret = casetable[*cp1] - casetable[*cp2]; + } } else ret = memcmp(t1->stptr, t2->stptr, l); diff --git a/extension/ChangeLog b/extension/ChangeLog index ba0d3bfa..1561adfb 100644 --- a/extension/ChangeLog +++ b/extension/ChangeLog @@ -1,3 +1,8 @@ +2014-11-23 Arnold D. Robbins <arnold@skeeve.com> + + * inplace.c (do_inplace_begin): Jump through hoops to silence + GCC warnings about return value of chown. + 2014-11-09 Andrew J. Schorr <aschorr@telemetry-investments.com> * select.c (do_input_fd): New function to return the input file @@ -27,6 +32,17 @@ descriptor, call the set_retry function to configure PROCINFO to tell io.c to retry I/O for temporary failures. +2014-10-12 Arnold D. Robbins <arnold@skeeve.com> + + * Makefile.am (uninstall-so): Remove *.lib too, per suggestion + from Andreas Buening. + +2014-10-12 KO Myung-Hun <komh78@gmail.com> + + Fixes for OS/2: + + * Makefile.am (uninstall-so): Remove *.dll and *.a, also. + 2014-10-08 Arnold D. Robbins <arnold@skeeve.com> * inplace.c (do_inplace_begin): Use a cast to void in front diff --git a/extension/Makefile.am b/extension/Makefile.am index c8b1f53c..32603734 100644 --- a/extension/Makefile.am +++ b/extension/Makefile.am @@ -119,6 +119,9 @@ install-data-hook: # Keep the uninstall check working: uninstall-so: $(RM) $(DESTDIR)$(pkgextensiondir)/*.so + $(RM) $(DESTDIR)$(pkgextensiondir)/*.dll + $(RM) $(DESTDIR)$(pkgextensiondir)/*.a + $(RM) $(DESTDIR)$(pkgextensiondir)/*.lib uninstall-recursive: uninstall-so diff --git a/extension/Makefile.in b/extension/Makefile.in index 821d6112..02ac379f 100644 --- a/extension/Makefile.in +++ b/extension/Makefile.in @@ -107,9 +107,9 @@ DIST_COMMON = INSTALL NEWS README AUTHORS ChangeLog \ $(top_srcdir)/configure $(am__configure_deps) \ $(srcdir)/configh.in ABOUT-NLS $(top_srcdir)/build-aux/depcomp \ $(dist_man_MANS) COPYING build-aux/ChangeLog build-aux/ar-lib \ - build-aux/config.guess build-aux/config.rpath \ - build-aux/config.sub build-aux/depcomp build-aux/install-sh \ - build-aux/missing build-aux/ltmain.sh \ + build-aux/compile build-aux/config.guess \ + build-aux/config.rpath build-aux/config.sub build-aux/depcomp \ + build-aux/install-sh build-aux/missing build-aux/ltmain.sh \ $(top_srcdir)/build-aux/ar-lib \ $(top_srcdir)/build-aux/config.guess \ $(top_srcdir)/build-aux/config.rpath \ @@ -1272,6 +1272,9 @@ install-data-hook: # Keep the uninstall check working: uninstall-so: $(RM) $(DESTDIR)$(pkgextensiondir)/*.so + $(RM) $(DESTDIR)$(pkgextensiondir)/*.dll + $(RM) $(DESTDIR)$(pkgextensiondir)/*.a + $(RM) $(DESTDIR)$(pkgextensiondir)/*.lib uninstall-recursive: uninstall-so diff --git a/extension/build-aux/compile b/extension/build-aux/compile new file mode 100755 index 00000000..531136b0 --- /dev/null +++ b/extension/build-aux/compile @@ -0,0 +1,347 @@ +#! /bin/sh +# Wrapper for compilers which do not understand '-c -o'. + +scriptversion=2012-10-14.11; # UTC + +# Copyright (C) 1999-2013 Free Software Foundation, Inc. +# Written by Tom Tromey <tromey@cygnus.com>. +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. + +# As a special exception to the GNU General Public License, if you +# distribute this file as part of a program that contains a +# configuration script generated by Autoconf, you may include it under +# the same distribution terms that you use for the rest of that program. + +# This file is maintained in Automake, please report +# bugs to <bug-automake@gnu.org> or send patches to +# <automake-patches@gnu.org>. + +nl=' +' + +# We need space, tab and new line, in precisely that order. Quoting is +# there to prevent tools from complaining about whitespace usage. +IFS=" "" $nl" + +file_conv= + +# func_file_conv build_file lazy +# Convert a $build file to $host form and store it in $file +# Currently only supports Windows hosts. If the determined conversion +# type is listed in (the comma separated) LAZY, no conversion will +# take place. +func_file_conv () +{ + file=$1 + case $file in + / | /[!/]*) # absolute file, and not a UNC file + if test -z "$file_conv"; then + # lazily determine how to convert abs files + case `uname -s` in + MINGW*) + file_conv=mingw + ;; + CYGWIN*) + file_conv=cygwin + ;; + *) + file_conv=wine + ;; + esac + fi + case $file_conv/,$2, in + *,$file_conv,*) + ;; + mingw/*) + file=`cmd //C echo "$file " | sed -e 's/"\(.*\) " *$/\1/'` + ;; + cygwin/*) + file=`cygpath -m "$file" || echo "$file"` + ;; + wine/*) + file=`winepath -w "$file" || echo "$file"` + ;; + esac + ;; + esac +} + +# func_cl_dashL linkdir +# Make cl look for libraries in LINKDIR +func_cl_dashL () +{ + func_file_conv "$1" + if test -z "$lib_path"; then + lib_path=$file + else + lib_path="$lib_path;$file" + fi + linker_opts="$linker_opts -LIBPATH:$file" +} + +# func_cl_dashl library +# Do a library search-path lookup for cl +func_cl_dashl () +{ + lib=$1 + found=no + save_IFS=$IFS + IFS=';' + for dir in $lib_path $LIB + do + IFS=$save_IFS + if $shared && test -f "$dir/$lib.dll.lib"; then + found=yes + lib=$dir/$lib.dll.lib + break + fi + if test -f "$dir/$lib.lib"; then + found=yes + lib=$dir/$lib.lib + break + fi + if test -f "$dir/lib$lib.a"; then + found=yes + lib=$dir/lib$lib.a + break + fi + done + IFS=$save_IFS + + if test "$found" != yes; then + lib=$lib.lib + fi +} + +# func_cl_wrapper cl arg... +# Adjust compile command to suit cl +func_cl_wrapper () +{ + # Assume a capable shell + lib_path= + shared=: + linker_opts= + for arg + do + if test -n "$eat"; then + eat= + else + case $1 in + -o) + # configure might choose to run compile as 'compile cc -o foo foo.c'. + eat=1 + case $2 in + *.o | *.[oO][bB][jJ]) + func_file_conv "$2" + set x "$@" -Fo"$file" + shift + ;; + *) + func_file_conv "$2" + set x "$@" -Fe"$file" + shift + ;; + esac + ;; + -I) + eat=1 + func_file_conv "$2" mingw + set x "$@" -I"$file" + shift + ;; + -I*) + func_file_conv "${1#-I}" mingw + set x "$@" -I"$file" + shift + ;; + -l) + eat=1 + func_cl_dashl "$2" + set x "$@" "$lib" + shift + ;; + -l*) + func_cl_dashl "${1#-l}" + set x "$@" "$lib" + shift + ;; + -L) + eat=1 + func_cl_dashL "$2" + ;; + -L*) + func_cl_dashL "${1#-L}" + ;; + -static) + shared=false + ;; + -Wl,*) + arg=${1#-Wl,} + save_ifs="$IFS"; IFS=',' + for flag in $arg; do + IFS="$save_ifs" + linker_opts="$linker_opts $flag" + done + IFS="$save_ifs" + ;; + -Xlinker) + eat=1 + linker_opts="$linker_opts $2" + ;; + -*) + set x "$@" "$1" + shift + ;; + *.cc | *.CC | *.cxx | *.CXX | *.[cC]++) + func_file_conv "$1" + set x "$@" -Tp"$file" + shift + ;; + *.c | *.cpp | *.CPP | *.lib | *.LIB | *.Lib | *.OBJ | *.obj | *.[oO]) + func_file_conv "$1" mingw + set x "$@" "$file" + shift + ;; + *) + set x "$@" "$1" + shift + ;; + esac + fi + shift + done + if test -n "$linker_opts"; then + linker_opts="-link$linker_opts" + fi + exec "$@" $linker_opts + exit 1 +} + +eat= + +case $1 in + '') + echo "$0: No command. Try '$0 --help' for more information." 1>&2 + exit 1; + ;; + -h | --h*) + cat <<\EOF +Usage: compile [--help] [--version] PROGRAM [ARGS] + +Wrapper for compilers which do not understand '-c -o'. +Remove '-o dest.o' from ARGS, run PROGRAM with the remaining +arguments, and rename the output as expected. + +If you are trying to build a whole package this is not the +right script to run: please start by reading the file 'INSTALL'. + +Report bugs to <bug-automake@gnu.org>. +EOF + exit $? + ;; + -v | --v*) + echo "compile $scriptversion" + exit $? + ;; + cl | *[/\\]cl | cl.exe | *[/\\]cl.exe ) + func_cl_wrapper "$@" # Doesn't return... + ;; +esac + +ofile= +cfile= + +for arg +do + if test -n "$eat"; then + eat= + else + case $1 in + -o) + # configure might choose to run compile as 'compile cc -o foo foo.c'. + # So we strip '-o arg' only if arg is an object. + eat=1 + case $2 in + *.o | *.obj) + ofile=$2 + ;; + *) + set x "$@" -o "$2" + shift + ;; + esac + ;; + *.c) + cfile=$1 + set x "$@" "$1" + shift + ;; + *) + set x "$@" "$1" + shift + ;; + esac + fi + shift +done + +if test -z "$ofile" || test -z "$cfile"; then + # If no '-o' option was seen then we might have been invoked from a + # pattern rule where we don't need one. That is ok -- this is a + # normal compilation that the losing compiler can handle. If no + # '.c' file was seen then we are probably linking. That is also + # ok. + exec "$@" +fi + +# Name of file we expect compiler to create. +cofile=`echo "$cfile" | sed 's|^.*[\\/]||; s|^[a-zA-Z]:||; s/\.c$/.o/'` + +# Create the lock directory. +# Note: use '[/\\:.-]' here to ensure that we don't use the same name +# that we are using for the .o file. Also, base the name on the expected +# object file name, since that is what matters with a parallel build. +lockdir=`echo "$cofile" | sed -e 's|[/\\:.-]|_|g'`.d +while true; do + if mkdir "$lockdir" >/dev/null 2>&1; then + break + fi + sleep 1 +done +# FIXME: race condition here if user kills between mkdir and trap. +trap "rmdir '$lockdir'; exit 1" 1 2 15 + +# Run the compile. +"$@" +ret=$? + +if test -f "$cofile"; then + test "$cofile" = "$ofile" || mv "$cofile" "$ofile" +elif test -f "${cofile}bj"; then + test "${cofile}bj" = "$ofile" || mv "${cofile}bj" "$ofile" +fi + +rmdir "$lockdir" +exit $ret + +# Local Variables: +# mode: shell-script +# sh-indentation: 2 +# eval: (add-hook 'write-file-hooks 'time-stamp) +# time-stamp-start: "scriptversion=" +# time-stamp-format: "%:y-%02m-%02d.%02H" +# time-stamp-time-zone: "UTC" +# time-stamp-end: "; # UTC" +# End: diff --git a/extension/build-aux/ltmain.sh b/extension/build-aux/ltmain.sh index a50a21a6..555b7637 100644 --- a/extension/build-aux/ltmain.sh +++ b/extension/build-aux/ltmain.sh @@ -1,10 +1,12 @@ #! /bin/sh +## DO NOT EDIT - This file generated from ./build-aux/ltmain.in +## by inline-source v2014-01-03.01 -# libtool (GNU libtool) 2.4.2.418 +# libtool (GNU libtool) 2.4.3 # Provide generalized library-building support services. # Written by Gordon Matzigkeit <gord@gnu.ai.mit.edu>, 1996 -# Copyright (C) 1996-2013 Free Software Foundation, Inc. +# Copyright (C) 1996-2014 Free Software Foundation, Inc. # This is free software; see the source for copying conditions. There is NO # warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. @@ -29,8 +31,8 @@ PROGRAM=libtool PACKAGE=libtool -VERSION=2.4.2.418 -package_revision=2.4.2.418 +VERSION=2.4.3 +package_revision=2.4.3 ## ------ ## @@ -62,12 +64,12 @@ package_revision=2.4.2.418 # libraries, which are installed to $pkgauxdir. # Set a version string for this script. -scriptversion=2013-08-23.20; # UTC +scriptversion=2014-01-03.01; # UTC # General shell script boiler plate, and helper functions. # Written by Gary V. Vaughan, 2004 -# Copyright (C) 2004-2013 Free Software Foundation, Inc. +# Copyright (C) 2004-2014 Free Software Foundation, Inc. # This is free software; see the source for copying conditions. There is NO # warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. @@ -147,47 +149,157 @@ nl=' ' IFS="$sp $nl" -# There are still modern systems that have problems with 'echo' mis- -# handling backslashes, among others, so make sure $bs_echo is set to a -# command that correctly interprets backslashes. -# (this code from Autoconf 2.68) - -# Printing a long string crashes Solaris 7 /usr/bin/printf. -bs_echo='\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\' -bs_echo=$bs_echo$bs_echo$bs_echo$bs_echo$bs_echo -bs_echo=$bs_echo$bs_echo$bs_echo$bs_echo$bs_echo$bs_echo -# Prefer a ksh shell builtin over an external printf program on Solaris, -# but without wasting forks for bash or zsh. -if test -z "$BASH_VERSION$ZSH_VERSION" \ - && (test "X`print -r -- $bs_echo`" = "X$bs_echo") 2>/dev/null; then - bs_echo='print -r --' - bs_echo_n='print -rn --' -elif (test "X`printf %s $bs_echo`" = "X$bs_echo") 2>/dev/null; then - bs_echo='printf %s\n' - bs_echo_n='printf %s' -else - if test "X`(/usr/ucb/echo -n -n $bs_echo) 2>/dev/null`" = "X-n $bs_echo"; then - bs_echo_body='eval /usr/ucb/echo -n "$1$nl"' - bs_echo_n='/usr/ucb/echo -n' - else - bs_echo_body='eval expr "X$1" : "X\\(.*\\)"' - bs_echo_n_body='eval - arg=$1; - case $arg in #( - *"$nl"*) - expr "X$arg" : "X\\(.*\\)$nl"; - arg=`expr "X$arg" : ".*$nl\\(.*\\)"`;; - esac; - expr "X$arg" : "X\\(.*\\)" | tr -d "$nl" - ' - export bs_echo_n_body - bs_echo_n='sh -c $bs_echo_n_body bs_echo' - fi - export bs_echo_body - bs_echo='sh -c $bs_echo_body bs_echo' +# There are apparently some retarded systems that use ';' as a PATH separator! +if test "${PATH_SEPARATOR+set}" != set; then + PATH_SEPARATOR=: + (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 && { + (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 || + PATH_SEPARATOR=';' + } fi + +## ------------------------- ## +## Locate command utilities. ## +## ------------------------- ## + + +# func_executable_p FILE +# ---------------------- +# Check that FILE is an executable regular file. +func_executable_p () +{ + test -f "$1" && test -x "$1" +} + + +# func_path_progs PROGS_LIST CHECK_FUNC [PATH] +# -------------------------------------------- +# Search for either a program that responds to --version with output +# containing "GNU", or else returned by CHECK_FUNC otherwise, by +# trying all the directories in PATH with each of the elements of +# PROGS_LIST. +# +# CHECK_FUNC should accept the path to a candidate program, and +# set $func_check_prog_result if it truncates its output less than +# $_G_path_prog_max characters. +func_path_progs () +{ + _G_progs_list=$1 + _G_check_func=$2 + _G_PATH=${3-"$PATH"} + + _G_path_prog_max=0 + _G_path_prog_found=false + _G_save_IFS=$IFS; IFS=$PATH_SEPARATOR + for _G_dir in $_G_PATH; do + IFS=$_G_save_IFS + test -z "$_G_dir" && _G_dir=. + for _G_prog_name in $_G_progs_list; do + for _exeext in '' .EXE; do + _G_path_prog=$_G_dir/$_G_prog_name$_exeext + func_executable_p "$_G_path_prog" || continue + case `"$_G_path_prog" --version 2>&1` in + *GNU*) func_path_progs_result=$_G_path_prog _G_path_prog_found=: ;; + *) $_G_check_func $_G_path_prog + func_path_progs_result=$func_check_prog_result + ;; + esac + $_G_path_prog_found && break 3 + done + done + done + IFS=$_G_save_IFS + test -z "$func_path_progs_result" && { + echo "no acceptable sed could be found in \$PATH" >&2 + exit 1 + } +} + + +# We want to be able to use the functions in this file before configure +# has figured out where the best binaries are kept, which means we have +# to search for them ourselves - except when the results are already set +# where we skip the searches. + +# Unless the user overrides by setting SED, search the path for either GNU +# sed, or the sed that truncates its output the least. +test -z "$SED" && { + _G_sed_script=s/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb/ + for _G_i in 1 2 3 4 5 6 7; do + _G_sed_script=$_G_sed_script$nl$_G_sed_script + done + echo "$_G_sed_script" 2>/dev/null | sed 99q >conftest.sed + _G_sed_script= + + func_check_prog_sed () + { + _G_path_prog=$1 + + _G_count=0 + printf 0123456789 >conftest.in + while : + do + cat conftest.in conftest.in >conftest.tmp + mv conftest.tmp conftest.in + cp conftest.in conftest.nl + echo '' >> conftest.nl + "$_G_path_prog" -f conftest.sed <conftest.nl >conftest.out 2>/dev/null || break + diff conftest.out conftest.nl >/dev/null 2>&1 || break + _G_count=`expr $_G_count + 1` + if test "$_G_count" -gt "$_G_path_prog_max"; then + # Best one so far, save it but keep looking for a better one + func_check_prog_result=$_G_path_prog + _G_path_prog_max=$_G_count + fi + # 10*(2^10) chars as input seems more than enough + test 10 -lt "$_G_count" && break + done + rm -f conftest.in conftest.tmp conftest.nl conftest.out + } + + func_path_progs "sed gsed" func_check_prog_sed $PATH:/usr/xpg4/bin + rm -f conftest.sed + SED=$func_path_progs_result +} + + +# Unless the user overrides by setting GREP, search the path for either GNU +# grep, or the grep that truncates its output the least. +test -z "$GREP" && { + func_check_prog_grep () + { + _G_path_prog=$1 + + _G_count=0 + _G_path_prog_max=0 + printf 0123456789 >conftest.in + while : + do + cat conftest.in conftest.in >conftest.tmp + mv conftest.tmp conftest.in + cp conftest.in conftest.nl + echo 'GREP' >> conftest.nl + "$_G_path_prog" -e 'GREP$' -e '-(cannot match)-' <conftest.nl >conftest.out 2>/dev/null || break + diff conftest.out conftest.nl >/dev/null 2>&1 || break + _G_count=`expr $_G_count + 1` + if test "$_G_count" -gt "$_G_path_prog_max"; then + # Best one so far, save it but keep looking for a better one + func_check_prog_result=$_G_path_prog + _G_path_prog_max=$_G_count + fi + # 10*(2^10) chars as input seems more than enough + test 10 -lt "$_G_count" && break + done + rm -f conftest.in conftest.tmp conftest.nl conftest.out + } + + func_path_progs "grep ggrep" func_check_prog_grep $PATH:/usr/xpg4/bin + GREP=$func_path_progs_result +} + + ## ------------------------------- ## ## User overridable command paths. ## ## ------------------------------- ## @@ -198,16 +310,14 @@ fi # in the command search PATH. : ${CP="cp -f"} -: ${ECHO="$bs_echo"} -: ${EGREP="grep -E"} -: ${FGREP="grep -F"} -: ${GREP="grep"} +: ${ECHO="printf %s\n"} +: ${EGREP="$GREP -E"} +: ${FGREP="$GREP -F"} : ${LN_S="ln -s"} : ${MAKE="make"} : ${MKDIR="mkdir"} : ${MV="mv -f"} : ${RM="rm -f"} -: ${SED="sed"} : ${SHELL="${CONFIG_SHELL-/bin/sh}"} @@ -298,13 +408,13 @@ exit_status=$EXIT_SUCCESS progpath=$0 # The name of this program. -progname=`$bs_echo "$progpath" |$SED "$sed_basename"` +progname=`$ECHO "$progpath" |$SED "$sed_basename"` # Make sure we have an absolute progpath for reexecution: case $progpath in [\\/]*|[A-Za-z]:\\*) ;; *[\\/]*) - progdir=`$bs_echo "$progpath" |$SED "$sed_dirname"` + progdir=`$ECHO "$progpath" |$SED "$sed_dirname"` progdir=`cd "$progdir" && pwd` progpath=$progdir/$progname ;; @@ -498,7 +608,7 @@ func_append_uniq () { $debug_cmd - eval _G_current_value='`$bs_echo $'$1'`' + eval _G_current_value='`$ECHO $'$1'`' _G_delim=`expr "$2" : '\(.\)'` case $_G_delim$_G_current_value$_G_delim in @@ -611,7 +721,7 @@ func_echo () IFS=$nl for _G_line in $_G_message; do IFS=$func_echo_IFS - $bs_echo "$progname: $_G_line" + $ECHO "$progname: $_G_line" done IFS=$func_echo_IFS } @@ -645,17 +755,17 @@ func_echo_infix_1 () for _G_tc in "$tc_reset" "$tc_bold" "$tc_standout" "$tc_red" "$tc_green" "$tc_blue" "$tc_cyan" do test -n "$_G_tc" && { - _G_esc_tc=`$bs_echo "$_G_tc" | sed "$sed_make_literal_regex"` - _G_indent=`$bs_echo "$_G_indent" | sed "s|$_G_esc_tc||g"` + _G_esc_tc=`$ECHO "$_G_tc" | $SED "$sed_make_literal_regex"` + _G_indent=`$ECHO "$_G_indent" | $SED "s|$_G_esc_tc||g"` } done - _G_indent="$progname: "`echo "$_G_indent" | sed 's|.| |g'`" " ## exclude from sc_prohibit_nested_quotes + _G_indent="$progname: "`echo "$_G_indent" | $SED 's|.| |g'`" " ## exclude from sc_prohibit_nested_quotes func_echo_infix_1_IFS=$IFS IFS=$nl for _G_line in $_G_message; do IFS=$func_echo_infix_1_IFS - $bs_echo "$_G_prefix$tc_bold$_G_line$tc_reset" >&2 + $ECHO "$_G_prefix$tc_bold$_G_line$tc_reset" >&2 _G_prefix=$_G_indent done IFS=$func_echo_infix_1_IFS @@ -1232,56 +1342,40 @@ func_sort_ver () { $debug_cmd - ver1=$1 - ver2=$2 + printf '%s\n%s\n' "$1" "$2" \ + | sort -t. -k 1,1n -k 2,2n -k 3,3n -k 4,4n -k 5,5n -k 6,6n -k 7,7n -k 8,8n -k 9,9n +} - # Split on '.' and compare each component. - i=1 - while :; do - p1=`echo "$ver1" |cut -d. -f$i` - p2=`echo "$ver2" |cut -d. -f$i` - if test ! "$p1"; then - echo "$1 $2" - break - elif test ! "$p2"; then - echo "$2 $1" - break - elif test ! "$p1" = "$p2"; then - if test "$p1" -gt "$p2" 2>/dev/null; then # numeric comparison - echo "$2 $1" - elif test "$p2" -gt "$p1" 2>/dev/null; then # numeric comparison - echo "$1 $2" - else # numeric, then lexicographic comparison - lp=`printf "$p1\n$p2\n" |sort -n |tail -n1` - if test "$lp" = "$p2"; then - echo "$1 $2" - else - echo "$2 $1" - fi - fi - break - fi - i=`expr $i + 1` - done +# func_lt_ver PREV CURR +# --------------------- +# Return true if PREV and CURR are in the correct order according to +# func_sort_ver, otherwise false. Use it like this: +# +# func_lt_ver "$prev_ver" "$proposed_ver" || func_fatal_error "..." +func_lt_ver () +{ + $debug_cmd + + test "x$1" = x`func_sort_ver "$1" "$2" | $SED 1q` } # Local variables: # mode: shell-script # sh-indentation: 2 -# eval: (add-hook 'write-file-hooks 'time-stamp) +# eval: (add-hook 'before-save-hook 'time-stamp) # time-stamp-pattern: "10/scriptversion=%:y-%02m-%02d.%02H; # UTC" # time-stamp-time-zone: "UTC" # End: #! /bin/sh # Set a version string for this script. -scriptversion=2012-10-21.11; # UTC +scriptversion=2014-01-07.03; # UTC # A portable, pluggable option parser for Bourne shell. # Written by Gary V. Vaughan, 2010 -# Copyright (C) 2010-2013 Free Software Foundation, Inc. +# Copyright (C) 2010-2014 Free Software Foundation, Inc. # This is free software; see the source for copying conditions. There is NO # warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. @@ -1421,7 +1515,7 @@ func_remove_hook () { $debug_cmd - eval ${1}_hooks='`$bs_echo "\$'$1'_hooks" |$SED "s| '$2'||"`' + eval ${1}_hooks='`$ECHO "\$'$1'_hooks" |$SED "s| '$2'||"`' } @@ -1698,9 +1792,9 @@ func_validate_options () -## ------------------## +## ----------------- ## ## Helper functions. ## -## ------------------## +## ----------------- ## # This section contains the helper functions used by the rest of the # hookable option parser framework in ascii-betical order. @@ -1714,8 +1808,8 @@ func_fatal_help () { $debug_cmd - eval \$bs_echo \""Usage: $usage"\" - eval \$bs_echo \""$fatal_help"\" + eval \$ECHO \""Usage: $usage"\" + eval \$ECHO \""$fatal_help"\" func_error ${1+"$@"} exit $EXIT_FAILURE } @@ -1729,7 +1823,7 @@ func_help () $debug_cmd func_usage_message - $bs_echo "$long_help_message" + $ECHO "$long_help_message" exit 0 } @@ -1816,7 +1910,7 @@ func_usage () $debug_cmd func_usage_message - $bs_echo "Run '$progname --help |${PAGER-more}' for full usage" + $ECHO "Run '$progname --help |${PAGER-more}' for full usage" exit 0 } @@ -1828,7 +1922,7 @@ func_usage_message () { $debug_cmd - eval \$bs_echo \""Usage: $usage"\" + eval \$ECHO \""Usage: $usage"\" echo $SED -n 's|^# || /^Written by/{ @@ -1837,7 +1931,7 @@ func_usage_message () h /^Written by/q' < "$progpath" echo - eval \$bs_echo \""$usage_message"\" + eval \$ECHO \""$usage_message"\" } @@ -1849,7 +1943,7 @@ func_version () $debug_cmd printf '%s\n' "$progname $scriptversion" - $SED -n '/^##/q + $SED -n ' /(C)/!b go :more /\./!{ @@ -1877,13 +1971,13 @@ func_version () # Local variables: # mode: shell-script # sh-indentation: 2 -# eval: (add-hook 'write-file-hooks 'time-stamp) +# eval: (add-hook 'before-save-hook 'time-stamp) # time-stamp-pattern: "10/scriptversion=%:y-%02m-%02d.%02H; # UTC" # time-stamp-time-zone: "UTC" # End: # Set a version string. -scriptversion='(GNU libtool) 2.4.2.418' +scriptversion='(GNU libtool) 2.4.3' # func_echo ARG... @@ -1900,7 +1994,7 @@ func_echo () IFS=$nl for _G_line in $_G_message; do IFS=$func_echo_IFS - $bs_echo "$progname${opt_mode+: $opt_mode}: $_G_line" + $ECHO "$progname${opt_mode+: $opt_mode}: $_G_line" done IFS=$func_echo_IFS } @@ -1969,7 +2063,7 @@ include the following information: compiler: $LTCC compiler flags: $LTCFLAGS linker: $LD (gnu? $with_gnu_ld) - version: $progname (GNU libtool) 2.4.2.418 + version: $progname (GNU libtool) 2.4.3 automake: `($AUTOMAKE --version) 2>/dev/null |$SED 1q` autoconf: `($AUTOCONF --version) 2>/dev/null |$SED 1q` @@ -2315,7 +2409,9 @@ libtool_validate_options () test : = "$debug_cmd" || func_append preserve_args " --debug" case $host in - *cygwin* | *mingw* | *pw32* | *cegcc*) + # Solaris2 added to fix http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16452 + # see also: http://gcc.gnu.org/bugzilla/show_bug.cgi?id=59788 + *cygwin* | *mingw* | *pw32* | *cegcc* | *solaris2*) # don't eliminate duplications in $postdeps and $predeps opt_duplicate_compiler_generated_deps=: ;; @@ -2386,6 +2482,14 @@ $1 _LTECHO_EOF' } +# func_generated_by_libtool +# True iff stdin has been generated by Libtool. This function is only +# a basic sanity check; it will hardly flush out determined imposters. +func_generated_by_libtool_p () +{ + $GREP "^# Generated by .*$PACKAGE" > /dev/null 2>&1 +} + # func_lalib_p file # True iff FILE is a libtool '.la' library or '.lo' object file. # This function is only a basic sanity check; it will hardly flush out @@ -2393,8 +2497,7 @@ _LTECHO_EOF' func_lalib_p () { test -f "$1" && - $SED -e 4q "$1" 2>/dev/null \ - | $GREP "^# Generated by .*$PACKAGE" > /dev/null 2>&1 + $SED -e 4q "$1" 2>/dev/null | func_generated_by_libtool_p } # func_lalib_unsafe_p file @@ -2426,7 +2529,8 @@ func_lalib_unsafe_p () # determined imposters. func_ltwrapper_script_p () { - func_lalib_p "$1" + test -f "$1" && + $lt_truncate_bin < "$1" 2>/dev/null | func_generated_by_libtool_p } # func_ltwrapper_executable_p file @@ -3696,7 +3800,7 @@ if $opt_help; then for opt_mode in compile link execute install finish uninstall clean; do func_mode_help done - } | sed -n '1p; 2,$s/^Usage:/ or: /p' + } | $SED -n '1p; 2,$s/^Usage:/ or: /p' { func_help noexit for opt_mode in compile link execute install finish uninstall clean; do @@ -3704,7 +3808,7 @@ if $opt_help; then func_mode_help done } | - sed '1d + $SED '1d /^When reporting/,/^Report/{ H d @@ -3894,7 +3998,7 @@ func_mode_finish () else tmpdir=`func_mktempdir` for lib in $libs; do - sed -e "$sysroot_cmd s/\([ ']-[LR]\)=/\1/g; s/\([ ']\)=/\1/g" $lib \ + $SED -e "$sysroot_cmd s/\([ ']-[LR]\)=/\1/g; s/\([ ']\)=/\1/g" $lib \ > $tmpdir/tmp-la mv -f $tmpdir/tmp-la $lib done @@ -4449,7 +4553,7 @@ func_generate_dlsyms () my_outputname=$1 my_originator=$2 my_pic_p=${3-false} - my_prefix=`$ECHO "$my_originator" | sed 's%[^a-zA-Z0-9]%_%g'` + my_prefix=`$ECHO "$my_originator" | $SED 's%[^a-zA-Z0-9]%_%g'` my_dlsyms= if test -n "$dlfiles$dlprefiles" || test no != "$dlself"; then @@ -5322,7 +5426,7 @@ func_exec_program () if test -n \"\$relink_command\"; then if relink_command_output=\`eval \$relink_command 2>&1\`; then : else - $ECHO \"\$relink_command_output\" >&2 + \$ECHO \"\$relink_command_output\" >&2 $RM \"\$progdir/\$file\" exit 1 fi @@ -5554,7 +5658,12 @@ void lt_dump_script (FILE *f); EOF cat <<EOF -volatile const char * MAGIC_EXE = "$magic_exe"; +#if __GNUC__ < 4 || (__GNUC__ == 4 && __GNUC_MINOR__ < 5) +# define externally_visible volatile +#else +# define externally_visible __attribute__((externally_visible)) volatile +#endif +externally_visible const char * MAGIC_EXE = "$magic_exe"; const char * LIB_PATH_VARNAME = "$shlibpath_var"; EOF @@ -7114,6 +7223,7 @@ func_mode_link () # -m*, -t[45]*, -txscale* architecture-specific flags for GCC # -F/path path to uninstalled frameworks, gcc on darwin # -p, -pg, --coverage, -fprofile-* profiling flags for GCC + # -fstack-protector* stack protector flags for GCC # @file GCC response files # -tp=* Portland pgcc target processor selection # --sysroot=* for sysroot support @@ -7121,7 +7231,7 @@ func_mode_link () # -stdlib=* select c++ std lib with clang -64|-mips[0-9]|-r[0-9][0-9]*|-xarch=*|-xtarget=*|+DA*|+DD*|-q*|-m*| \ -t[45]*|-txscale*|-p|-pg|--coverage|-fprofile-*|-F*|@*|-tp=*|--sysroot=*| \ - -O*|-g*|-flto*|-fwhopr*|-fuse-linker-plugin|-stdlib=*) + -O*|-g*|-flto*|-fwhopr*|-fuse-linker-plugin|-fstack-protector*|-stdlib=*) func_quote_for_eval "$arg" arg=$func_quote_for_eval_result func_append compile_command " $arg" @@ -9906,15 +10016,17 @@ EOF # the extraction. reload_conv_objs= gentop= - # reload_cmds runs $LD directly, so let us get rid of - # -Wl from whole_archive_flag_spec and hope we can get by with - # turning comma into space.. - wl= - + # if reload_cmds runs $LD directly, get rid of -Wl from + # whole_archive_flag_spec and hope we can get by with turning comma + # into space. + case $reload_cmds in + *\$LD[\ \$]*) wl= ;; + esac if test -n "$convenience"; then if test -n "$whole_archive_flag_spec"; then eval tmp_whole_archive_flags=\"$whole_archive_flag_spec\" - reload_conv_objs=$reload_objs\ `$ECHO "$tmp_whole_archive_flags" | $SED 's|,| |g'` + test -n "$wl" || tmp_whole_archive_flags=`$ECHO "$tmp_whole_archive_flags" | $SED 's|,| |g'` + reload_conv_objs=$reload_objs\ $tmp_whole_archive_flags else gentop=$output_objdir/${obj}x func_append generated " $gentop" diff --git a/extension/configure b/extension/configure index 006c9d79..6e92b054 100755 --- a/extension/configure +++ b/extension/configure @@ -6854,8 +6854,8 @@ esac -macro_version='2.4.2.418' -macro_revision='2.4.2.418' +macro_version='2.4.2.458.26-92994' +macro_revision='2.4.3' @@ -7244,8 +7244,13 @@ else # Adding the 'sed 1q' prevents false positives on HP-UX, which says: # nm: unknown option "B" ignored # Tru64's nm complains that /dev/null is an invalid object file - case `"$tmp_nm" -B /dev/null 2>&1 | sed '1q'` in - */dev/null* | *'Invalid file or object type'*) + # MSYS converts /dev/null to NUL, MinGW nm treats NUL as empty + case $build_os in + mingw*) lt_bad_file=conftest.nm/nofile ;; + *) lt_bad_file=/dev/null ;; + esac + case `"$tmp_nm" -B $lt_bad_file 2>&1 | sed '1q'` in + *$lt_bad_file* | *'Invalid file or object type'*) lt_cv_path_NM="$tmp_nm -B" break 2 ;; @@ -9003,6 +9008,71 @@ $as_echo "${lt_sysroot:-no}" >&6; } +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for a working dd" >&5 +$as_echo_n "checking for a working dd... " >&6; } +if ${ac_cv_path_lt_DD+:} false; then : + $as_echo_n "(cached) " >&6 +else + printf 0123456789abcdef0123456789abcdef >conftest.i +cat conftest.i conftest.i >conftest2.i +: ${lt_DD:=$DD} +if test -z "$lt_DD"; then + ac_path_lt_DD_found=false + # Loop through the user's path and test for each of PROGNAME-LIST + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + test -z "$as_dir" && as_dir=. + for ac_prog in dd; do + for ac_exec_ext in '' $ac_executable_extensions; do + ac_path_lt_DD="$as_dir/$ac_prog$ac_exec_ext" + as_fn_executable_p "$ac_path_lt_DD" || continue +if "$ac_path_lt_DD" bs=32 count=1 <conftest2.i >conftest.out 2>/dev/null; then + cmp -s conftest.i conftest.out \ + && ac_cv_path_lt_DD="$ac_path_lt_DD" ac_path_lt_DD_found=: +fi + $ac_path_lt_DD_found && break 3 + done + done + done +IFS=$as_save_IFS + if test -z "$ac_cv_path_lt_DD"; then + : + fi +else + ac_cv_path_lt_DD=$lt_DD +fi + +rm -f conftest.i conftest2.i conftest.out +fi +{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $ac_cv_path_lt_DD" >&5 +$as_echo "$ac_cv_path_lt_DD" >&6; } + + +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking how to truncate binary pipes" >&5 +$as_echo_n "checking how to truncate binary pipes... " >&6; } +if ${lt_cv_truncate_bin+:} false; then : + $as_echo_n "(cached) " >&6 +else + printf 0123456789abcdef0123456789abcdef >conftest.i +cat conftest.i conftest.i >conftest2.i +lt_cv_truncate_bin= +if "$ac_cv_path_lt_DD" bs=32 count=1 <conftest2.i >conftest.out 2>/dev/null; then + cmp -s conftest.i conftest.out \ + && lt_cv_truncate_bin="$ac_cv_path_lt_DD bs=4096 count=1" +fi +rm -f conftest.i conftest2.i conftest.out +test -z "$lt_cv_truncate_bin" && lt_cv_truncate_bin="$SED -e 4q" +fi +{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $lt_cv_truncate_bin" >&5 +$as_echo "$lt_cv_truncate_bin" >&6; } + + + + + + # Check whether --enable-libtool-lock was given. if test "${enable_libtool_lock+set}" = set; then : enableval=$enable_libtool_lock; @@ -9987,7 +10057,7 @@ $as_echo "$lt_cv_ld_force_load" >&6; } case ${MACOSX_DEPLOYMENT_TARGET-10.0},$host in 10.0,*86*-darwin8*|10.0,*-darwin[91]*) _lt_dar_allow_undefined='$wl-undefined ${wl}dynamic_lookup' ;; - 10.[012]*) + 10.[012][,.]*) _lt_dar_allow_undefined='$wl-flat_namespace $wl-undefined ${wl}suppress' ;; 10.*) _lt_dar_allow_undefined='$wl-undefined ${wl}dynamic_lookup' ;; @@ -15283,6 +15353,7 @@ lt_cv_sys_global_symbol_to_c_name_address_lib_prefix='`$ECHO "$lt_cv_sys_global_ lt_cv_nm_interface='`$ECHO "$lt_cv_nm_interface" | $SED "$delay_single_quote_subst"`' nm_file_list_spec='`$ECHO "$nm_file_list_spec" | $SED "$delay_single_quote_subst"`' lt_sysroot='`$ECHO "$lt_sysroot" | $SED "$delay_single_quote_subst"`' +lt_cv_truncate_bin='`$ECHO "$lt_cv_truncate_bin" | $SED "$delay_single_quote_subst"`' objdir='`$ECHO "$objdir" | $SED "$delay_single_quote_subst"`' MAGIC_CMD='`$ECHO "$MAGIC_CMD" | $SED "$delay_single_quote_subst"`' lt_prog_compiler_no_builtin_flag='`$ECHO "$lt_prog_compiler_no_builtin_flag" | $SED "$delay_single_quote_subst"`' @@ -15403,6 +15474,7 @@ lt_cv_sys_global_symbol_to_c_name_address \ lt_cv_sys_global_symbol_to_c_name_address_lib_prefix \ lt_cv_nm_interface \ nm_file_list_spec \ +lt_cv_truncate_bin \ lt_prog_compiler_no_builtin_flag \ lt_prog_compiler_pic \ lt_prog_compiler_wl \ @@ -16320,39 +16392,34 @@ $as_echo X"$file" | cat <<_LT_EOF >> "$cfgfile" #! $SHELL - -# `$ECHO "$ofile" | sed 's%^.*/%%'` - Provide generalized library-building support services. # Generated automatically by $as_me ($PACKAGE) $VERSION # Libtool was configured on host `(hostname || uname -n) 2>/dev/null | sed 1q`: # NOTE: Changes made to this file will be lost: look at ltmain.sh. + +# Provide generalized library-building support services. +# Written by Gordon Matzigkeit, 1996 + +# Copyright (C) 2014 Free Software Foundation, Inc. +# This is free software; see the source for copying conditions. There is NO +# warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +# GNU Libtool is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of of the License, or +# (at your option) any later version. # -# Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2003, 2004, 2005, -# 2006, 2007, 2008, 2009, 2010, 2011 Free Software -# Foundation, Inc. -# Written by Gordon Matzigkeit, 1996 -# -# This file is part of GNU Libtool. -# -# GNU Libtool is free software; you can redistribute it and/or -# modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of -# the License, or (at your option) any later version. -# -# As a special exception to the GNU General Public License, -# if you distribute this file as part of a program or library that -# is built using GNU Libtool, you may include this file under the -# same distribution terms that you use for the rest of that program. +# As a special exception to the GNU General Public License, if you +# distribute this file as part of a program or library that is built +# using GNU Libtool, you may include this file under the same +# distribution terms that you use for the rest of that program. # -# GNU Libtool is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of +# GNU Libtool is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License -# along with GNU Libtool; see the file COPYING. If not, a copy -# can be downloaded from http://www.gnu.org/licenses/gpl.html, or -# obtained by writing to the Free Software Foundation, Inc., -# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# along with this program. If not, see <http://www.gnu.org/licenses/>. # The names of the tagged configurations supported by this script. @@ -16511,6 +16578,9 @@ nm_file_list_spec=$lt_nm_file_list_spec # The root where to search for dependent libraries,and where our libraries should be installed. lt_sysroot=$lt_sysroot +# Command to truncate a binary pipe. +lt_truncate_bin=$lt_lt_cv_truncate_bin + # The name of the directory that contains temporary libtool files. objdir=$objdir diff --git a/extension/inplace.c b/extension/inplace.c index 8a7375c4..0693ad92 100644 --- a/extension/inplace.c +++ b/extension/inplace.c @@ -170,8 +170,12 @@ do_inplace_begin(int nargs, awk_value_t *result) state.tname, strerror(errno)); /* N.B. chown/chmod should be more portable than fchown/fchmod */ - if (chown(state.tname, sbuf.st_uid, sbuf.st_gid) < 0) - (void) chown(state.tname, -1, sbuf.st_gid); + if (chown(state.tname, sbuf.st_uid, sbuf.st_gid) < 0) { + /* jumping through hoops to silence gcc. :-( */ + int junk; + junk = chown(state.tname, -1, sbuf.st_gid); + junk = junk; + } if (chmod(state.tname, sbuf.st_mode) < 0) fatal(ext_id, _("inplace_begin: chmod failed (%s)"), diff --git a/extension/m4/libtool.m4 b/extension/m4/libtool.m4 index 4bc6b22c..068f0d8b 100644 --- a/extension/m4/libtool.m4 +++ b/extension/m4/libtool.m4 @@ -1,6 +1,6 @@ # libtool.m4 - Configure libtool for the host system. -*-Autoconf-*- # -# Copyright (C) 1996-2001, 2003-2013 Free Software Foundation, Inc. +# Copyright (C) 1996-2001, 2003-2014 Free Software Foundation, Inc. # Written by Gordon Matzigkeit, 1996 # # This file is free software; the Free Software Foundation gives @@ -8,33 +8,27 @@ # modifications, as long as this notice is preserved. m4_define([_LT_COPYING], [dnl -# Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2003, 2004, 2005, -# 2006, 2007, 2008, 2009, 2010, 2011 Free Software -# Foundation, Inc. -# Written by Gordon Matzigkeit, 1996 -# -# This file is part of GNU Libtool. +# Copyright (C) 2014 Free Software Foundation, Inc. +# This is free software; see the source for copying conditions. There is NO +# warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +# GNU Libtool is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of of the License, or +# (at your option) any later version. # -# GNU Libtool is free software; you can redistribute it and/or -# modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of -# the License, or (at your option) any later version. +# As a special exception to the GNU General Public License, if you +# distribute this file as part of a program or library that is built +# using GNU Libtool, you may include this file under the same +# distribution terms that you use for the rest of that program. # -# As a special exception to the GNU General Public License, -# if you distribute this file as part of a program or library that -# is built using GNU Libtool, you may include this file under the -# same distribution terms that you use for the rest of that program. -# -# GNU Libtool is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of +# GNU Libtool is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License -# along with GNU Libtool; see the file COPYING. If not, a copy -# can be downloaded from http://www.gnu.org/licenses/gpl.html, or -# obtained by writing to the Free Software Foundation, Inc., -# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. +# along with this program. If not, see <http://www.gnu.org/licenses/>. ]) # serial 58 LT_INIT @@ -65,7 +59,7 @@ esac # LT_INIT([OPTIONS]) # ------------------ AC_DEFUN([LT_INIT], -[AC_PREREQ([2.58])dnl We use AC_INCLUDES_DEFAULT +[AC_PREREQ([2.62])dnl We use AC_PATH_PROGS_FEATURE_CHECK AC_REQUIRE([AC_CONFIG_AUX_DIR_DEFAULT])dnl AC_BEFORE([$0], [LT_LANG])dnl AC_BEFORE([$0], [LT_OUTPUT])dnl @@ -175,6 +169,7 @@ m4_require([_LT_CHECK_SHAREDLIB_FROM_LINKLIB])dnl m4_require([_LT_CMD_OLD_ARCHIVE])dnl m4_require([_LT_CMD_GLOBAL_SYMBOLS])dnl m4_require([_LT_WITH_SYSROOT])dnl +m4_require([_LT_CMD_TRUNCATE])dnl _LT_CONFIG_LIBTOOL_INIT([ # See if we are running on zsh, and set the options that allow our @@ -715,12 +710,13 @@ _LT_CONFIG_SAVE_COMMANDS([ cat <<_LT_EOF >> "$cfgfile" #! $SHELL - -# `$ECHO "$ofile" | sed 's%^.*/%%'` - Provide generalized library-building support services. # Generated automatically by $as_me ($PACKAGE) $VERSION # Libtool was configured on host `(hostname || uname -n) 2>/dev/null | sed 1q`: # NOTE: Changes made to this file will be lost: look at ltmain.sh. -# + +# Provide generalized library-building support services. +# Written by Gordon Matzigkeit, 1996 + _LT_COPYING _LT_LIBTOOL_TAGS @@ -1047,7 +1043,7 @@ _LT_EOF case ${MACOSX_DEPLOYMENT_TARGET-10.0},$host in 10.0,*86*-darwin8*|10.0,*-darwin[[91]]*) _lt_dar_allow_undefined='$wl-undefined ${wl}dynamic_lookup' ;; - 10.[[012]]*) + 10.[[012]][[,.]]*) _lt_dar_allow_undefined='$wl-flat_namespace $wl-undefined ${wl}suppress' ;; 10.*) _lt_dar_allow_undefined='$wl-undefined ${wl}dynamic_lookup' ;; @@ -3221,6 +3217,43 @@ _LT_TAGDECL([], [reload_cmds], [2])dnl ])# _LT_CMD_RELOAD +# _LT_PATH_DD +# ----------- +# find a working dd +m4_defun([_LT_PATH_DD], +[AC_CACHE_CHECK([for a working dd], [ac_cv_path_lt_DD], +[printf 0123456789abcdef0123456789abcdef >conftest.i +cat conftest.i conftest.i >conftest2.i +: ${lt_DD:=$DD} +AC_PATH_PROGS_FEATURE_CHECK([lt_DD], [dd], +[if "$ac_path_lt_DD" bs=32 count=1 <conftest2.i >conftest.out 2>/dev/null; then + cmp -s conftest.i conftest.out \ + && ac_cv_path_lt_DD="$ac_path_lt_DD" ac_path_lt_DD_found=: +fi]) +rm -f conftest.i conftest2.i conftest.out]) +])# _LT_PATH_DD + + +# _LT_CMD_TRUNCATE +# ---------------- +# find command to truncate a binary pipe +m4_defun([_LT_CMD_TRUNCATE], +[m4_require([_LT_PATH_DD]) +AC_CACHE_CHECK([how to truncate binary pipes], [lt_cv_truncate_bin], +[printf 0123456789abcdef0123456789abcdef >conftest.i +cat conftest.i conftest.i >conftest2.i +lt_cv_truncate_bin= +if "$ac_cv_path_lt_DD" bs=32 count=1 <conftest2.i >conftest.out 2>/dev/null; then + cmp -s conftest.i conftest.out \ + && lt_cv_truncate_bin="$ac_cv_path_lt_DD bs=4096 count=1" +fi +rm -f conftest.i conftest2.i conftest.out +test -z "$lt_cv_truncate_bin" && lt_cv_truncate_bin="$SED -e 4q"]) +_LT_DECL([lt_truncate_bin], [lt_cv_truncate_bin], [1], + [Command to truncate a binary pipe]) +])# _LT_CMD_TRUNCATE + + # _LT_CHECK_MAGIC_METHOD # ---------------------- # how to check for library dependencies @@ -3476,8 +3509,13 @@ else # Adding the 'sed 1q' prevents false positives on HP-UX, which says: # nm: unknown option "B" ignored # Tru64's nm complains that /dev/null is an invalid object file - case `"$tmp_nm" -B /dev/null 2>&1 | sed '1q'` in - */dev/null* | *'Invalid file or object type'*) + # MSYS converts /dev/null to NUL, MinGW nm treats NUL as empty + case $build_os in + mingw*) lt_bad_file=conftest.nm/nofile ;; + *) lt_bad_file=/dev/null ;; + esac + case `"$tmp_nm" -B $lt_bad_file 2>&1 | sed '1q'` in + *$lt_bad_file* | *'Invalid file or object type'*) lt_cv_path_NM="$tmp_nm -B" break 2 ;; diff --git a/extension/m4/ltoptions.m4 b/extension/m4/ltoptions.m4 index 50c77236..de6520ed 100644 --- a/extension/m4/ltoptions.m4 +++ b/extension/m4/ltoptions.m4 @@ -1,6 +1,6 @@ # Helper functions for option handling. -*- Autoconf -*- # -# Copyright (C) 2004-2005, 2007-2009, 2011-2013 Free Software +# Copyright (C) 2004-2005, 2007-2009, 2011-2014 Free Software # Foundation, Inc. # Written by Gary V. Vaughan, 2004 # diff --git a/extension/m4/ltsugar.m4 b/extension/m4/ltsugar.m4 index 9000a057..da4ac6b3 100644 --- a/extension/m4/ltsugar.m4 +++ b/extension/m4/ltsugar.m4 @@ -1,6 +1,7 @@ # ltsugar.m4 -- libtool m4 base layer. -*-Autoconf-*- # -# Copyright (C) 2004, 2005, 2007, 2008 Free Software Foundation, Inc. +# Copyright (C) 2004-2005, 2007-2008, 2011-2014 Free Software +# Foundation, Inc. # Written by Gary V. Vaughan, 2004 # # This file is free software; the Free Software Foundation gives @@ -33,7 +34,7 @@ m4_define([_lt_join], # ------------ # Manipulate m4 lists. # These macros are necessary as long as will still need to support -# Autoconf-2.59 which quotes differently. +# Autoconf-2.59, which quotes differently. m4_define([lt_car], [[$1]]) m4_define([lt_cdr], [m4_if([$#], 0, [m4_fatal([$0: cannot be called without arguments])], @@ -44,7 +45,7 @@ m4_define([lt_unquote], $1) # lt_append(MACRO-NAME, STRING, [SEPARATOR]) # ------------------------------------------ -# Redefine MACRO-NAME to hold its former content plus `SEPARATOR'`STRING'. +# Redefine MACRO-NAME to hold its former content plus 'SEPARATOR''STRING'. # Note that neither SEPARATOR nor STRING are expanded; they are appended # to MACRO-NAME as is (leaving the expansion for when MACRO-NAME is invoked). # No SEPARATOR is output if MACRO-NAME was previously undefined (different diff --git a/extension/m4/ltversion.m4 b/extension/m4/ltversion.m4 index daeb0af7..3535ff40 100644 --- a/extension/m4/ltversion.m4 +++ b/extension/m4/ltversion.m4 @@ -1,6 +1,6 @@ # ltversion.m4 -- version numbers -*- Autoconf -*- # -# Copyright (C) 2004, 2011-2013 Free Software Foundation, Inc. +# Copyright (C) 2004, 2011-2014 Free Software Foundation, Inc. # Written by Scott James Remnant, 2004 # # This file is free software; the Free Software Foundation gives @@ -9,15 +9,15 @@ # @configure_input@ -# serial 4038 ltversion.m4 +# serial 4105 ltversion.m4 # This file is part of GNU Libtool -m4_define([LT_PACKAGE_VERSION], [2.4.2.418]) -m4_define([LT_PACKAGE_REVISION], [2.4.2.418]) +m4_define([LT_PACKAGE_VERSION], [2.4.2.458.26-92994]) +m4_define([LT_PACKAGE_REVISION], [2.4.3]) AC_DEFUN([LTVERSION_VERSION], -[macro_version='2.4.2.418' -macro_revision='2.4.2.418' +[macro_version='2.4.2.458.26-92994' +macro_revision='2.4.3' _LT_DECL(, macro_version, 0, [Which release of libtool.m4 was used?]) _LT_DECL(, macro_revision, 0) ]) diff --git a/extension/m4/lt~obsolete.m4 b/extension/m4/lt~obsolete.m4 index c573da90..6975098b 100644 --- a/extension/m4/lt~obsolete.m4 +++ b/extension/m4/lt~obsolete.m4 @@ -1,6 +1,7 @@ # lt~obsolete.m4 -- aclocal satisfying obsolete definitions. -*-Autoconf-*- # -# Copyright (C) 2004, 2005, 2007, 2009 Free Software Foundation, Inc. +# Copyright (C) 2004-2005, 2007, 2009, 2011-2014 Free Software +# Foundation, Inc. # Written by Scott James Remnant, 2004. # # This file is free software; the Free Software Foundation gives @@ -11,7 +12,7 @@ # These exist entirely to fool aclocal when bootstrapping libtool. # -# In the past libtool.m4 has provided macros via AC_DEFUN (or AU_DEFUN) +# In the past libtool.m4 has provided macros via AC_DEFUN (or AU_DEFUN), # which have later been changed to m4_define as they aren't part of the # exported API, or moved to Autoconf or Automake where they belong. # @@ -25,7 +26,7 @@ # included after everything else. This provides aclocal with the # AC_DEFUNs it wants, but when m4 processes it, it doesn't do anything # because those macros already exist, or will be overwritten later. -# We use AC_DEFUN over AU_DEFUN for compatibility with aclocal-1.6. +# We use AC_DEFUN over AU_DEFUN for compatibility with aclocal-1.6. # # Anytime we withdraw an AC_DEFUN or AU_DEFUN, remember to add it here. # Yes, that means every name once taken will need to remain here until diff --git a/extras/Makefile.in b/extras/Makefile.in index 8418e2dc..f6416f56 100644 --- a/extras/Makefile.in +++ b/extras/Makefile.in @@ -234,6 +234,7 @@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ POSUB = @POSUB@ +SED = @SED@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ SOCKET_LIBS = @SOCKET_LIBS@ @@ -277,6 +277,12 @@ set_record(const char *buf, int cnt) /* copy the data */ memcpy(databuf, buf, cnt); + /* + * Add terminating '\0' so that C library routines + * will know when to stop. + */ + databuf[cnt] = '\0'; + /* manage field 0: */ unref(fields_arr[0]); getnode(n); @@ -386,12 +392,10 @@ re_parse_field(long up_to, /* parse only up to this field number */ char *end = scan + len; int regex_flags = RE_NEED_START; char *sep; -#if MBS_SUPPORT size_t mbclen = 0; mbstate_t mbs; - if (gawk_mb_cur_max > 1) - memset(&mbs, 0, sizeof(mbstate_t)); -#endif + + memset(&mbs, 0, sizeof(mbstate_t)); if (in_middle) regex_flags |= RE_NO_BOL; @@ -418,7 +422,6 @@ re_parse_field(long up_to, /* parse only up to this field number */ && nf < up_to) { regex_flags |= RE_NO_BOL; if (REEND(rp, scan) == RESTART(rp, scan)) { /* null match */ -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { mbclen = mbrlen(scan, end-scan, &mbs); if ((mbclen == 1) || (mbclen == (size_t) -1) @@ -428,8 +431,7 @@ re_parse_field(long up_to, /* parse only up to this field number */ } scan += mbclen; } else -#endif - scan++; + scan++; if (scan == end) { (*set)(++nf, field, (long)(scan - field), n); up_to = nf; @@ -630,7 +632,6 @@ null_parse_field(long up_to, /* parse only up to this field number */ if (len == 0) return nf; -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { mbstate_t mbs; memset(&mbs, 0, sizeof(mbstate_t)); @@ -646,12 +647,12 @@ null_parse_field(long up_to, /* parse only up to this field number */ (*set)(++nf, scan, mbclen, n); scan += mbclen; } - } else -#endif - for (; nf < up_to && scan < end; scan++) { - if (sep_arr != NULL && nf > 0) - set_element(nf, scan, 0L, sep_arr); - (*set)(++nf, scan, 1L, n); + } else { + for (; nf < up_to && scan < end; scan++) { + if (sep_arr != NULL && nf > 0) + set_element(nf, scan, 0L, sep_arr); + (*set)(++nf, scan, 1L, n); + } } *buf = scan; @@ -682,12 +683,10 @@ sc_parse_field(long up_to, /* parse only up to this field number */ char *field; char *end = scan + len; char sav; -#if MBS_SUPPORT size_t mbclen = 0; mbstate_t mbs; - if (gawk_mb_cur_max > 1) - memset(&mbs, 0, sizeof(mbstate_t)); -#endif + + memset(&mbs, 0, sizeof(mbstate_t)); if (up_to == UNLIMITED) nf = 0; @@ -706,7 +705,6 @@ sc_parse_field(long up_to, /* parse only up to this field number */ for (; nf < up_to;) { field = scan; -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { while (*scan != fschar) { mbclen = mbrlen(scan, end-scan, &mbs); @@ -717,10 +715,10 @@ sc_parse_field(long up_to, /* parse only up to this field number */ } scan += mbclen; } - } else -#endif - while (*scan != fschar) - scan++; + } else { + while (*scan != fschar) + scan++; + } (*set)(++nf, field, (long)(scan - field), n); if (scan == end) break; @@ -760,7 +758,6 @@ fw_parse_field(long up_to, /* parse only up to this field number */ char *scan = *buf; long nf = parse_high_water; char *end = scan + len; -#if MBS_SUPPORT int nmbc; size_t mbclen; size_t mbslen; @@ -769,14 +766,12 @@ fw_parse_field(long up_to, /* parse only up to this field number */ mbstate_t mbs; memset(&mbs, 0, sizeof(mbstate_t)); -#endif if (up_to == UNLIMITED) nf = 0; if (len == 0) return nf; for (; nf < up_to && (len = FIELDWIDTHS[nf+1]) != -1; ) { -#if MBS_SUPPORT if (gawk_mb_cur_max > 1) { nmbc = 0; mbslen = 0; @@ -799,10 +794,7 @@ fw_parse_field(long up_to, /* parse only up to this field number */ } (*set)(++nf, scan, (long) mbslen, n); scan += mbslen; - } - else -#endif - { + } else { if (len > end - scan) len = end - scan; (*set)(++nf, scan, (long) len, n); @@ -1445,13 +1437,8 @@ set_fpat_function: * Implementation varies if doing MBS or not. */ -#if MBS_SUPPORT #define increment_scan(scanp, len) incr_scan(scanp, len, & mbs) -#else -#define increment_scan(scanp, len) ((*scanp)++) -#endif -#if MBS_SUPPORT /* incr_scan --- MBS version of increment_scan() */ static void @@ -1472,7 +1459,6 @@ incr_scan(char **scanp, size_t len, mbstate_t *mbs) } else (*scanp)++; } -#endif /* * fpat_parse_field --- parse fields using a regexp. @@ -1597,12 +1583,9 @@ fpat_parse_field(long up_to, /* parse only up to this field number */ bool need_to_set_sep; bool non_empty; bool eosflag; -#if MBS_SUPPORT mbstate_t mbs; - if (gawk_mb_cur_max > 1) - memset(&mbs, 0, sizeof(mbstate_t)); -#endif + memset(&mbs, 0, sizeof(mbstate_t)); if (up_to == UNLIMITED) nf = 0; @@ -52,6 +52,8 @@ pointer xmalloc(size_t bytes) { pointer p; + if (bytes == 0) + bytes = 1; /* avoid dfa.c mishegos */ emalloc(p, pointer, bytes, "xmalloc"); return p; } @@ -48,6 +48,21 @@ extern "C" { #endif +#ifdef __KLIBC__ +/* OS/2 kLIBC has already getopt(). So to avoid name clash, rename + them here. */ + +# define optarg gawk_optarg +# define optind gawk_optind +# define opterr gawk_opterr +# define optopt gawk_optopt + +# define getopt gawk_getopt +# define getopt_long gawk_getopt_long +# define getopt_long_only gawk_getopt_long_only +#endif + + /* For communication from `getopt' to the caller. When `getopt' finds an option that takes an argument, the argument value is returned here. diff --git a/interpret.h b/interpret.h index 23ce0c1a..3a9cab37 100644 --- a/interpret.h +++ b/interpret.h @@ -23,7 +23,19 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA */ - +#define UNFIELD(l, r) \ +{ \ + /* if was a field, turn it into a var */ \ + if ((r->flags & FIELD) == 0) { \ + l = r; \ + } else if (r->valref == 1) { \ + r->flags &= ~FIELD; \ + l = r; \ + } else { \ + l = dupnode(r); \ + DEREF(r); \ + } \ +} int r_interpret(INSTRUCTION *code) { @@ -340,7 +352,12 @@ uninitialized_scalar: lhs = r_get_field(t1, (Func_ptr *) 0, true); decr_sp(); DEREF(t1); - r = dupnode(*lhs); /* can't use UPREF here */ + /* only for $0, up ref count */ + if (*lhs == fields_arr[0]) { + r = *lhs; + UPREF(r); + } else + r = dupnode(*lhs); PUSH(r); break; @@ -631,7 +648,8 @@ mod: } unref(*lhs); - *lhs = POP_SCALAR(); + r = POP_SCALAR(); + UNFIELD(*lhs, r); /* execute post-assignment routine if any */ if (t1->astore != NULL) @@ -649,11 +667,12 @@ mod: lhs = get_lhs(pc->memory, false); unref(*lhs); r = pc->initval; /* constant initializer */ - if (r == NULL) - *lhs = POP_SCALAR(); - else { + if (r != NULL) { UPREF(r); *lhs = r; + } else { + r = POP_SCALAR(); + UNFIELD(*lhs, r); } break; @@ -669,7 +688,8 @@ mod: decr_sp(); DEREF(t1); unref(*lhs); - *lhs = POP_SCALAR(); + r = POP_SCALAR(); + UNFIELD(*lhs, r); assert(assign != NULL); assign(); } @@ -695,7 +715,6 @@ mod: t1->stptr[nlen] = '\0'; t1->flags &= ~(NUMCUR|NUMBER|NUMINT); -#if MBS_SUPPORT if ((t1->flags & WSTRCUR) != 0 && (t2->flags & WSTRCUR) != 0) { size_t wlen = t1->wstlen + t2->wstlen; @@ -707,7 +726,6 @@ mod: t1->flags |= WSTRCUR; } else free_wstr(*lhs); -#endif } else { size_t nlen = t1->stlen + t2->stlen; char *p; @@ -725,8 +743,8 @@ mod: lhs = POP_ADDRESS(); r = TOP_SCALAR(); unref(*lhs); - *lhs = r; UPREF(r); + UNFIELD(*lhs, r); REPLACE(r); break; @@ -110,6 +110,14 @@ #ifdef __EMX__ #include <process.h> + +#if !defined(_S_IFDIR) && defined(S_IFDIR) +#define _S_IFDIR S_IFDIR +#endif + +#if !defined(_S_IRWXU) && defined(S_IRWXU) +#define _S_IRWXU S_IRWXU +#endif #endif #ifndef ENFILE @@ -3126,10 +3134,8 @@ rs1scan(IOBUF *iop, struct recmatch *recm, SCANSTATE *state) { char *bp; char rs; -#if MBS_SUPPORT size_t mbclen = 0; mbstate_t mbs; -#endif memset(recm, '\0', sizeof(struct recmatch)); rs = RS->stptr[0]; @@ -3140,7 +3146,6 @@ rs1scan(IOBUF *iop, struct recmatch *recm, SCANSTATE *state) if (*state == INDATA) /* skip over data we've already seen */ bp += iop->scanoff; -#if MBS_SUPPORT /* * From: Bruno Haible <bruno@clisp.org> * To: Aharon Robbins <arnold@skeeve.com>, gnits@gnits.org @@ -3237,7 +3242,7 @@ rs1scan(IOBUF *iop, struct recmatch *recm, SCANSTATE *state) return NOTERM; } } -#endif + while (*bp != rs) bp++; diff --git a/m4/ChangeLog b/m4/ChangeLog index 17c482cb..9ef76c4f 100644 --- a/m4/ChangeLog +++ b/m4/ChangeLog @@ -1,3 +1,14 @@ +2014-11-19 gettextize <bug-gnu-gettext@gnu.org> + + * gettext.m4: Upgrade to gettext-0.19.3. + * iconv.m4: Upgrade to gettext-0.19.3. + * lib-ld.m4: Upgrade to gettext-0.19.3. + * lib-link.m4: Upgrade to gettext-0.19.3. + * lib-prefix.m4: Upgrade to gettext-0.19.3. + * nls.m4: Upgrade to gettext-0.19.3. + * po.m4: Upgrade to gettext-0.19.3. + * progtest.m4: Upgrade to gettext-0.19.3. + 2014-10-30 Arnold D. Robbins <arnold@skeeve.com> * readline.m4: Enable cross compiling. Thanks to diff --git a/m4/gettext.m4 b/m4/gettext.m4 index f84e6a5d..be247bf7 100644 --- a/m4/gettext.m4 +++ b/m4/gettext.m4 @@ -1,5 +1,5 @@ -# gettext.m4 serial 63 (gettext-0.18) -dnl Copyright (C) 1995-2010 Free Software Foundation, Inc. +# gettext.m4 serial 66 (gettext-0.18.2) +dnl Copyright (C) 1995-2014 Free Software Foundation, Inc. dnl This file is free software; the Free Software Foundation dnl gives unlimited permission to copy and/or distribute it, dnl with or without modifications, as long as this notice is preserved. @@ -35,7 +35,7 @@ dnl will be ignored. If NEEDSYMBOL is specified and is dnl 'need-formatstring-macros', then GNU gettext implementations that don't dnl support the ISO C 99 <inttypes.h> formatstring macros will be ignored. dnl INTLDIR is used to find the intl libraries. If empty, -dnl the value `$(top_builddir)/intl/' is used. +dnl the value '$(top_builddir)/intl/' is used. dnl dnl The result of the configuration is one of three cases: dnl 1) GNU gettext, as included in the intl subdirectory, will be compiled @@ -97,7 +97,7 @@ AC_DEFUN([AM_GNU_GETTEXT], AC_REQUIRE([AM_ICONV_LINKFLAGS_BODY]) ]) - dnl Sometimes, on MacOS X, libintl requires linking with CoreFoundation. + dnl Sometimes, on Mac OS X, libintl requires linking with CoreFoundation. gt_INTL_MACOSX dnl Set USE_NLS. @@ -157,12 +157,18 @@ changequote([,])dnl fi AC_CACHE_CHECK([for GNU gettext in libc], [$gt_func_gnugettext_libc], - [AC_TRY_LINK([#include <libintl.h> + [AC_LINK_IFELSE( + [AC_LANG_PROGRAM( + [[ +#include <libintl.h> $gt_revision_test_code extern int _nl_msg_cat_cntr; -extern int *_nl_domain_bindings;], - [bindtextdomain ("", ""); -return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_domain_bindings], +extern int *_nl_domain_bindings; + ]], + [[ +bindtextdomain ("", ""); +return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_domain_bindings + ]])], [eval "$gt_func_gnugettext_libc=yes"], [eval "$gt_func_gnugettext_libc=no"])]) @@ -183,35 +189,47 @@ return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_domain_b gt_save_LIBS="$LIBS" LIBS="$LIBS $LIBINTL" dnl Now see whether libintl exists and does not depend on libiconv. - AC_TRY_LINK([#include <libintl.h> + AC_LINK_IFELSE( + [AC_LANG_PROGRAM( + [[ +#include <libintl.h> $gt_revision_test_code extern int _nl_msg_cat_cntr; extern #ifdef __cplusplus "C" #endif -const char *_nl_expand_alias (const char *);], - [bindtextdomain ("", ""); -return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_expand_alias ("")], +const char *_nl_expand_alias (const char *); + ]], + [[ +bindtextdomain ("", ""); +return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_expand_alias ("") + ]])], [eval "$gt_func_gnugettext_libintl=yes"], [eval "$gt_func_gnugettext_libintl=no"]) dnl Now see whether libintl exists and depends on libiconv. if { eval "gt_val=\$$gt_func_gnugettext_libintl"; test "$gt_val" != yes; } && test -n "$LIBICONV"; then LIBS="$LIBS $LIBICONV" - AC_TRY_LINK([#include <libintl.h> + AC_LINK_IFELSE( + [AC_LANG_PROGRAM( + [[ +#include <libintl.h> $gt_revision_test_code extern int _nl_msg_cat_cntr; extern #ifdef __cplusplus "C" #endif -const char *_nl_expand_alias (const char *);], - [bindtextdomain ("", ""); -return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_expand_alias ("")], - [LIBINTL="$LIBINTL $LIBICONV" - LTLIBINTL="$LTLIBINTL $LTLIBICONV" - eval "$gt_func_gnugettext_libintl=yes" - ]) +const char *_nl_expand_alias (const char *); + ]], + [[ +bindtextdomain ("", ""); +return * gettext ("")$gt_expression_test_code + _nl_msg_cat_cntr + *_nl_expand_alias ("") + ]])], + [LIBINTL="$LIBINTL $LIBICONV" + LTLIBINTL="$LTLIBINTL $LTLIBICONV" + eval "$gt_func_gnugettext_libintl=yes" + ]) fi CPPFLAGS="$gt_save_CPPFLAGS" LIBS="$gt_save_LIBS"]) diff --git a/m4/iconv.m4 b/m4/iconv.m4 index e2041b9b..4b29c5f2 100644 --- a/m4/iconv.m4 +++ b/m4/iconv.m4 @@ -1,5 +1,5 @@ -# iconv.m4 serial 11 (gettext-0.18.1) -dnl Copyright (C) 2000-2002, 2007-2010 Free Software Foundation, Inc. +# iconv.m4 serial 18 (gettext-0.18.2) +dnl Copyright (C) 2000-2002, 2007-2014 Free Software Foundation, Inc. dnl This file is free software; the Free Software Foundation dnl gives unlimited permission to copy and/or distribute it, dnl with or without modifications, as long as this notice is preserved. @@ -30,27 +30,35 @@ AC_DEFUN([AM_ICONV_LINK], dnl Add $INCICONV to CPPFLAGS before performing the following checks, dnl because if the user has installed libiconv and not disabled its use dnl via --without-libiconv-prefix, he wants to use it. The first - dnl AC_TRY_LINK will then fail, the second AC_TRY_LINK will succeed. + dnl AC_LINK_IFELSE will then fail, the second AC_LINK_IFELSE will succeed. am_save_CPPFLAGS="$CPPFLAGS" AC_LIB_APPENDTOVAR([CPPFLAGS], [$INCICONV]) AC_CACHE_CHECK([for iconv], [am_cv_func_iconv], [ am_cv_func_iconv="no, consider installing GNU libiconv" am_cv_lib_iconv=no - AC_TRY_LINK([#include <stdlib.h> -#include <iconv.h>], - [iconv_t cd = iconv_open("",""); - iconv(cd,NULL,NULL,NULL,NULL); - iconv_close(cd);], + AC_LINK_IFELSE( + [AC_LANG_PROGRAM( + [[ +#include <stdlib.h> +#include <iconv.h> + ]], + [[iconv_t cd = iconv_open("",""); + iconv(cd,NULL,NULL,NULL,NULL); + iconv_close(cd);]])], [am_cv_func_iconv=yes]) if test "$am_cv_func_iconv" != yes; then am_save_LIBS="$LIBS" LIBS="$LIBS $LIBICONV" - AC_TRY_LINK([#include <stdlib.h> -#include <iconv.h>], - [iconv_t cd = iconv_open("",""); - iconv(cd,NULL,NULL,NULL,NULL); - iconv_close(cd);], + AC_LINK_IFELSE( + [AC_LANG_PROGRAM( + [[ +#include <stdlib.h> +#include <iconv.h> + ]], + [[iconv_t cd = iconv_open("",""); + iconv(cd,NULL,NULL,NULL,NULL); + iconv_close(cd);]])], [am_cv_lib_iconv=yes] [am_cv_func_iconv=yes]) LIBS="$am_save_LIBS" @@ -58,16 +66,19 @@ AC_DEFUN([AM_ICONV_LINK], ]) if test "$am_cv_func_iconv" = yes; then AC_CACHE_CHECK([for working iconv], [am_cv_func_iconv_works], [ - dnl This tests against bugs in AIX 5.1, HP-UX 11.11, Solaris 10. + dnl This tests against bugs in AIX 5.1, AIX 6.1..7.1, HP-UX 11.11, + dnl Solaris 10. am_save_LIBS="$LIBS" if test $am_cv_lib_iconv = yes; then LIBS="$LIBS $LIBICONV" fi - AC_TRY_RUN([ + AC_RUN_IFELSE( + [AC_LANG_SOURCE([[ #include <iconv.h> #include <string.h> int main () { + int result = 0; /* Test against AIX 5.1 bug: Failures are not distinguishable from successful returns. */ { @@ -84,7 +95,8 @@ int main () (char **) &inptr, &inbytesleft, &outptr, &outbytesleft); if (res == 0) - return 1; + result |= 1; + iconv_close (cd_utf8_to_88591); } } /* Test against Solaris 10 bug: Failures are not distinguishable from @@ -103,7 +115,27 @@ int main () (char **) &inptr, &inbytesleft, &outptr, &outbytesleft); if (res == 0) - return 1; + result |= 2; + iconv_close (cd_ascii_to_88591); + } + } + /* Test against AIX 6.1..7.1 bug: Buffer overrun. */ + { + iconv_t cd_88591_to_utf8 = iconv_open ("UTF-8", "ISO-8859-1"); + if (cd_88591_to_utf8 != (iconv_t)(-1)) + { + static const char input[] = "\304"; + static char buf[2] = { (char)0xDE, (char)0xAD }; + const char *inptr = input; + size_t inbytesleft = 1; + char *outptr = buf; + size_t outbytesleft = 1; + size_t res = iconv (cd_88591_to_utf8, + (char **) &inptr, &inbytesleft, + &outptr, &outbytesleft); + if (res != (size_t)(-1) || outptr - buf > 1 || buf[1] != (char)0xAD) + result |= 4; + iconv_close (cd_88591_to_utf8); } } #if 0 /* This bug could be worked around by the caller. */ @@ -122,7 +154,8 @@ int main () (char **) &inptr, &inbytesleft, &outptr, &outbytesleft); if ((int)res > 0) - return 1; + result |= 8; + iconv_close (cd_88591_to_utf8); } } #endif @@ -136,13 +169,19 @@ int main () && iconv_open ("UTF-8", "IBM-eucJP") == (iconv_t)(-1) /* Try HP-UX names. */ && iconv_open ("utf8", "eucJP") == (iconv_t)(-1)) - return 1; - return 0; -}], [am_cv_func_iconv_works=yes], [am_cv_func_iconv_works=no], - [case "$host_os" in + result |= 16; + return result; +}]])], + [am_cv_func_iconv_works=yes], + [am_cv_func_iconv_works=no], + [ +changequote(,)dnl + case "$host_os" in aix* | hpux*) am_cv_func_iconv_works="guessing no" ;; *) am_cv_func_iconv_works="guessing yes" ;; - esac]) + esac +changequote([,])dnl + ]) LIBS="$am_save_LIBS" ]) case "$am_cv_func_iconv_works" in @@ -183,32 +222,47 @@ m4_define([gl_iconv_AC_DEFUN], m4_version_prereq([2.64], [[AC_DEFUN_ONCE( [$1], [$2])]], - [[AC_DEFUN( - [$1], [$2])]])) + [m4_ifdef([gl_00GNULIB], + [[AC_DEFUN_ONCE( + [$1], [$2])]], + [[AC_DEFUN( + [$1], [$2])]])])) gl_iconv_AC_DEFUN([AM_ICONV], [ AM_ICONV_LINK if test "$am_cv_func_iconv" = yes; then AC_MSG_CHECKING([for iconv declaration]) AC_CACHE_VAL([am_cv_proto_iconv], [ - AC_TRY_COMPILE([ + AC_COMPILE_IFELSE( + [AC_LANG_PROGRAM( + [[ #include <stdlib.h> #include <iconv.h> extern #ifdef __cplusplus "C" #endif -#if defined(__STDC__) || defined(__cplusplus) +#if defined(__STDC__) || defined(_MSC_VER) || defined(__cplusplus) size_t iconv (iconv_t cd, char * *inbuf, size_t *inbytesleft, char * *outbuf, size_t *outbytesleft); #else size_t iconv(); #endif -], [], [am_cv_proto_iconv_arg1=""], [am_cv_proto_iconv_arg1="const"]) + ]], + [[]])], + [am_cv_proto_iconv_arg1=""], + [am_cv_proto_iconv_arg1="const"]) am_cv_proto_iconv="extern size_t iconv (iconv_t cd, $am_cv_proto_iconv_arg1 char * *inbuf, size_t *inbytesleft, char * *outbuf, size_t *outbytesleft);"]) am_cv_proto_iconv=`echo "[$]am_cv_proto_iconv" | tr -s ' ' | sed -e 's/( /(/'` AC_MSG_RESULT([ $am_cv_proto_iconv]) AC_DEFINE_UNQUOTED([ICONV_CONST], [$am_cv_proto_iconv_arg1], [Define as const if the declaration of iconv() needs const.]) + dnl Also substitute ICONV_CONST in the gnulib generated <iconv.h>. + m4_ifdef([gl_ICONV_H_DEFAULTS], + [AC_REQUIRE([gl_ICONV_H_DEFAULTS]) + if test -n "$am_cv_proto_iconv_arg1"; then + ICONV_CONST="const" + fi + ]) fi ]) diff --git a/m4/lib-ld.m4 b/m4/lib-ld.m4 index ebb30528..ddc569f7 100644 --- a/m4/lib-ld.m4 +++ b/m4/lib-ld.m4 @@ -1,50 +1,56 @@ -# lib-ld.m4 serial 4 (gettext-0.18) -dnl Copyright (C) 1996-2003, 2009-2010 Free Software Foundation, Inc. +# lib-ld.m4 serial 6 +dnl Copyright (C) 1996-2003, 2009-2014 Free Software Foundation, Inc. dnl This file is free software; the Free Software Foundation dnl gives unlimited permission to copy and/or distribute it, dnl with or without modifications, as long as this notice is preserved. dnl Subroutines of libtool.m4, -dnl with replacements s/AC_/AC_LIB/ and s/lt_cv/acl_cv/ to avoid collision -dnl with libtool.m4. +dnl with replacements s/_*LT_PATH/AC_LIB_PROG/ and s/lt_/acl_/ to avoid +dnl collision with libtool.m4. -dnl From libtool-1.4. Sets the variable with_gnu_ld to yes or no. +dnl From libtool-2.4. Sets the variable with_gnu_ld to yes or no. AC_DEFUN([AC_LIB_PROG_LD_GNU], [AC_CACHE_CHECK([if the linker ($LD) is GNU ld], [acl_cv_prog_gnu_ld], -[# I'd rather use --version here, but apparently some GNU ld's only accept -v. +[# I'd rather use --version here, but apparently some GNU lds only accept -v. case `$LD -v 2>&1 </dev/null` in *GNU* | *'with BFD'*) - acl_cv_prog_gnu_ld=yes ;; + acl_cv_prog_gnu_ld=yes + ;; *) - acl_cv_prog_gnu_ld=no ;; + acl_cv_prog_gnu_ld=no + ;; esac]) with_gnu_ld=$acl_cv_prog_gnu_ld ]) -dnl From libtool-1.4. Sets the variable LD. +dnl From libtool-2.4. Sets the variable LD. AC_DEFUN([AC_LIB_PROG_LD], -[AC_ARG_WITH([gnu-ld], -[ --with-gnu-ld assume the C compiler uses GNU ld [default=no]], -test "$withval" = no || with_gnu_ld=yes, with_gnu_ld=no) -AC_REQUIRE([AC_PROG_CC])dnl +[AC_REQUIRE([AC_PROG_CC])dnl AC_REQUIRE([AC_CANONICAL_HOST])dnl + +AC_ARG_WITH([gnu-ld], + [AS_HELP_STRING([--with-gnu-ld], + [assume the C compiler uses GNU ld [default=no]])], + [test "$withval" = no || with_gnu_ld=yes], + [with_gnu_ld=no])dnl + # Prepare PATH_SEPARATOR. # The user is always right. if test "${PATH_SEPARATOR+set}" != set; then - echo "#! /bin/sh" >conf$$.sh - echo "exit 0" >>conf$$.sh - chmod +x conf$$.sh - if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then - PATH_SEPARATOR=';' - else - PATH_SEPARATOR=: - fi - rm -f conf$$.sh + # Determine PATH_SEPARATOR by trying to find /bin/sh in a PATH which + # contains only /bin. Note that ksh looks also at the FPATH variable, + # so we have to set that as well for the test. + PATH_SEPARATOR=: + (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + && { (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + || PATH_SEPARATOR=';' + } fi + ac_prog=ld if test "$GCC" = yes; then # Check if gcc -print-prog-name=ld gives a path. - AC_MSG_CHECKING([for ld used by GCC]) + AC_MSG_CHECKING([for ld used by $CC]) case $host in *-*-mingw*) # gcc leaves a trailing carriage return which upsets mingw @@ -54,11 +60,11 @@ if test "$GCC" = yes; then esac case $ac_prog in # Accept absolute paths. - [[\\/]* | [A-Za-z]:[\\/]*)] - [re_direlt='/[^/][^/]*/\.\./'] - # Canonicalize the path of ld - ac_prog=`echo $ac_prog| sed 's%\\\\%/%g'` - while echo $ac_prog | grep "$re_direlt" > /dev/null 2>&1; do + [[\\/]]* | ?:[[\\/]]*) + re_direlt='/[[^/]][[^/]]*/\.\./' + # Canonicalize the pathname of ld + ac_prog=`echo "$ac_prog"| sed 's%\\\\%/%g'` + while echo "$ac_prog" | grep "$re_direlt" > /dev/null 2>&1; do ac_prog=`echo $ac_prog| sed "s%$re_direlt%/%"` done test -z "$LD" && LD="$ac_prog" @@ -79,23 +85,26 @@ else fi AC_CACHE_VAL([acl_cv_path_LD], [if test -z "$LD"; then - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS="${IFS}${PATH_SEPARATOR-:}" + acl_save_ifs="$IFS"; IFS=$PATH_SEPARATOR for ac_dir in $PATH; do + IFS="$acl_save_ifs" test -z "$ac_dir" && ac_dir=. if test -f "$ac_dir/$ac_prog" || test -f "$ac_dir/$ac_prog$ac_exeext"; then acl_cv_path_LD="$ac_dir/$ac_prog" # Check to see if the program is GNU ld. I'd rather use --version, - # but apparently some GNU ld's only accept -v. + # but apparently some variants of GNU ld only accept -v. # Break only if it was the GNU/non-GNU ld that we prefer. - case `"$acl_cv_path_LD" -v 2>&1 < /dev/null` in + case `"$acl_cv_path_LD" -v 2>&1 </dev/null` in *GNU* | *'with BFD'*) - test "$with_gnu_ld" != no && break ;; + test "$with_gnu_ld" != no && break + ;; *) - test "$with_gnu_ld" != yes && break ;; + test "$with_gnu_ld" != yes && break + ;; esac fi done - IFS="$ac_save_ifs" + IFS="$acl_save_ifs" else acl_cv_path_LD="$LD" # Let the user override the test with a path. fi]) diff --git a/m4/lib-link.m4 b/m4/lib-link.m4 index c73bd8e3..3522d994 100644 --- a/m4/lib-link.m4 +++ b/m4/lib-link.m4 @@ -1,5 +1,5 @@ -# lib-link.m4 serial 21 (gettext-0.18) -dnl Copyright (C) 2001-2010 Free Software Foundation, Inc. +# lib-link.m4 serial 26 (gettext-0.18.2) +dnl Copyright (C) 2001-2014 Free Software Foundation, Inc. dnl This file is free software; the Free Software Foundation dnl gives unlimited permission to copy and/or distribute it, dnl with or without modifications, as long as this notice is preserved. @@ -18,9 +18,9 @@ AC_DEFUN([AC_LIB_LINKFLAGS], [ AC_REQUIRE([AC_LIB_PREPARE_PREFIX]) AC_REQUIRE([AC_LIB_RPATH]) - pushdef([Name],[translit([$1],[./-], [___])]) - pushdef([NAME],[translit([$1],[abcdefghijklmnopqrstuvwxyz./-], - [ABCDEFGHIJKLMNOPQRSTUVWXYZ___])]) + pushdef([Name],[m4_translit([$1],[./+-], [____])]) + pushdef([NAME],[m4_translit([$1],[abcdefghijklmnopqrstuvwxyz./+-], + [ABCDEFGHIJKLMNOPQRSTUVWXYZ____])]) AC_CACHE_CHECK([how to link with lib[]$1], [ac_cv_lib[]Name[]_libs], [ AC_LIB_LINKFLAGS_BODY([$1], [$2]) ac_cv_lib[]Name[]_libs="$LIB[]NAME" @@ -58,9 +58,9 @@ AC_DEFUN([AC_LIB_HAVE_LINKFLAGS], [ AC_REQUIRE([AC_LIB_PREPARE_PREFIX]) AC_REQUIRE([AC_LIB_RPATH]) - pushdef([Name],[translit([$1],[./-], [___])]) - pushdef([NAME],[translit([$1],[abcdefghijklmnopqrstuvwxyz./-], - [ABCDEFGHIJKLMNOPQRSTUVWXYZ___])]) + pushdef([Name],[m4_translit([$1],[./+-], [____])]) + pushdef([NAME],[m4_translit([$1],[abcdefghijklmnopqrstuvwxyz./+-], + [ABCDEFGHIJKLMNOPQRSTUVWXYZ____])]) dnl Search for lib[]Name and define LIB[]NAME, LTLIB[]NAME and INC[]NAME dnl accordingly. @@ -85,7 +85,8 @@ AC_DEFUN([AC_LIB_HAVE_LINKFLAGS], *" -l"*) LIBS="$LIBS $LIB[]NAME" ;; *) LIBS="$LIB[]NAME $LIBS" ;; esac - AC_TRY_LINK([$3], [$4], + AC_LINK_IFELSE( + [AC_LANG_PROGRAM([[$3]], [[$4]])], [ac_cv_lib[]Name=yes], [ac_cv_lib[]Name='m4_if([$5], [], [no], [[$5]])']) LIBS="$ac_save_LIBS" @@ -115,6 +116,8 @@ AC_DEFUN([AC_LIB_HAVE_LINKFLAGS], dnl Determine the platform dependent parameters needed to use rpath: dnl acl_libext, dnl acl_shlibext, +dnl acl_libname_spec, +dnl acl_library_names_spec, dnl acl_hardcode_libdir_flag_spec, dnl acl_hardcode_libdir_separator, dnl acl_hardcode_direct, @@ -157,15 +160,15 @@ dnl package. This declaration must occur before an AC_LIB_LINKFLAGS or similar dnl macro call that searches for libname. AC_DEFUN([AC_LIB_FROMPACKAGE], [ - pushdef([NAME],[translit([$1],[abcdefghijklmnopqrstuvwxyz./-], - [ABCDEFGHIJKLMNOPQRSTUVWXYZ___])]) + pushdef([NAME],[m4_translit([$1],[abcdefghijklmnopqrstuvwxyz./+-], + [ABCDEFGHIJKLMNOPQRSTUVWXYZ____])]) define([acl_frompackage_]NAME, [$2]) popdef([NAME]) pushdef([PACK],[$2]) - pushdef([PACKUP],[translit(PACK,[abcdefghijklmnopqrstuvwxyz./-], - [ABCDEFGHIJKLMNOPQRSTUVWXYZ___])]) + pushdef([PACKUP],[m4_translit(PACK,[abcdefghijklmnopqrstuvwxyz./+-], + [ABCDEFGHIJKLMNOPQRSTUVWXYZ____])]) define([acl_libsinpackage_]PACKUP, - m4_ifdef([acl_libsinpackage_]PACKUP, [acl_libsinpackage_]PACKUP[[, ]],)[lib$1]) + m4_ifdef([acl_libsinpackage_]PACKUP, [m4_defn([acl_libsinpackage_]PACKUP)[, ]],)[lib$1]) popdef([PACKUP]) popdef([PACK]) ]) @@ -178,14 +181,14 @@ dnl in ${LIB${NAME}_PREFIX}/$acl_libdirstem. AC_DEFUN([AC_LIB_LINKFLAGS_BODY], [ AC_REQUIRE([AC_LIB_PREPARE_MULTILIB]) - pushdef([NAME],[translit([$1],[abcdefghijklmnopqrstuvwxyz./-], - [ABCDEFGHIJKLMNOPQRSTUVWXYZ___])]) + pushdef([NAME],[m4_translit([$1],[abcdefghijklmnopqrstuvwxyz./+-], + [ABCDEFGHIJKLMNOPQRSTUVWXYZ____])]) pushdef([PACK],[m4_ifdef([acl_frompackage_]NAME, [acl_frompackage_]NAME, lib[$1])]) - pushdef([PACKUP],[translit(PACK,[abcdefghijklmnopqrstuvwxyz./-], - [ABCDEFGHIJKLMNOPQRSTUVWXYZ___])]) + pushdef([PACKUP],[m4_translit(PACK,[abcdefghijklmnopqrstuvwxyz./+-], + [ABCDEFGHIJKLMNOPQRSTUVWXYZ____])]) pushdef([PACKLIBS],[m4_ifdef([acl_frompackage_]NAME, [acl_libsinpackage_]PACKUP, lib[$1])]) dnl Autoconf >= 2.61 supports dots in --with options. - pushdef([P_A_C_K],[m4_if(m4_version_compare(m4_defn([m4_PACKAGE_VERSION]),[2.61]),[-1],[translit(PACK,[.],[_])],PACK)]) + pushdef([P_A_C_K],[m4_if(m4_version_compare(m4_defn([m4_PACKAGE_VERSION]),[2.61]),[-1],[m4_translit(PACK,[.],[_])],PACK)]) dnl By default, look in $includedir and $libdir. use_additional=yes AC_LIB_WITH_FINAL_PREFIX([ @@ -242,7 +245,7 @@ AC_DEFUN([AC_LIB_LINKFLAGS_BODY], names_already_handled="$names_already_handled $name" dnl See if it was already located by an earlier AC_LIB_LINKFLAGS dnl or AC_LIB_HAVE_LINKFLAGS call. - uppername=`echo "$name" | sed -e 'y|abcdefghijklmnopqrstuvwxyz./-|ABCDEFGHIJKLMNOPQRSTUVWXYZ___|'` + uppername=`echo "$name" | sed -e 'y|abcdefghijklmnopqrstuvwxyz./+-|ABCDEFGHIJKLMNOPQRSTUVWXYZ____|'` eval value=\"\$HAVE_LIB$uppername\" if test -n "$value"; then if test "$value" = yes; then diff --git a/m4/lib-prefix.m4 b/m4/lib-prefix.m4 index 1601ceae..31f49e40 100644 --- a/m4/lib-prefix.m4 +++ b/m4/lib-prefix.m4 @@ -1,5 +1,5 @@ # lib-prefix.m4 serial 7 (gettext-0.18) -dnl Copyright (C) 2001-2005, 2008-2010 Free Software Foundation, Inc. +dnl Copyright (C) 2001-2005, 2008-2014 Free Software Foundation, Inc. dnl This file is free software; the Free Software Foundation dnl gives unlimited permission to copy and/or distribute it, dnl with or without modifications, as long as this notice is preserved. @@ -1,5 +1,5 @@ # nls.m4 serial 5 (gettext-0.18) -dnl Copyright (C) 1995-2003, 2005-2006, 2008-2010 Free Software Foundation, +dnl Copyright (C) 1995-2003, 2005-2006, 2008-2014 Free Software Foundation, dnl Inc. dnl This file is free software; the Free Software Foundation dnl gives unlimited permission to copy and/or distribute it, @@ -1,5 +1,5 @@ -# po.m4 serial 17 (gettext-0.18) -dnl Copyright (C) 1995-2010 Free Software Foundation, Inc. +# po.m4 serial 22 (gettext-0.19) +dnl Copyright (C) 1995-2014 Free Software Foundation, Inc. dnl This file is free software; the Free Software Foundation dnl gives unlimited permission to copy and/or distribute it, dnl with or without modifications, as long as this notice is preserved. @@ -17,7 +17,7 @@ dnl Authors: dnl Ulrich Drepper <drepper@cygnus.com>, 1995-2000. dnl Bruno Haible <haible@clisp.cons.org>, 2000-2003. -AC_PREREQ([2.50]) +AC_PREREQ([2.60]) dnl Checks for all prerequisites of the po subdirectory. AC_DEFUN([AM_PO_SUBDIRS], @@ -25,11 +25,12 @@ AC_DEFUN([AM_PO_SUBDIRS], AC_REQUIRE([AC_PROG_MAKE_SET])dnl AC_REQUIRE([AC_PROG_INSTALL])dnl AC_REQUIRE([AC_PROG_MKDIR_P])dnl + AC_REQUIRE([AC_PROG_SED])dnl AC_REQUIRE([AM_NLS])dnl dnl Release version of the gettext macros. This is used to ensure that dnl the gettext macros and po/Makefile.in.in are in sync. - AC_SUBST([GETTEXT_MACRO_VERSION], [0.18]) + AC_SUBST([GETTEXT_MACRO_VERSION], [0.19]) dnl Perform the following tests also if --disable-nls has been given, dnl because they are needed for "make dist" to work. @@ -102,7 +103,7 @@ changequote([,])dnl case "$ac_file" in */Makefile.in) # Adjust a relative srcdir. ac_dir=`echo "$ac_file"|sed 's%/[^/][^/]*$%%'` - ac_dir_suffix="/`echo "$ac_dir"|sed 's%^\./%%'`" + ac_dir_suffix=/`echo "$ac_dir"|sed 's%^\./%%'` ac_dots=`echo "$ac_dir_suffix"|sed 's%/[^/]*%../%g'` # In autoconf-2.13 it is called $ac_given_srcdir. # In autoconf-2.50 it is called $srcdir. @@ -118,7 +119,8 @@ changequote([,])dnl if test -f "$ac_given_srcdir/$ac_dir/POTFILES.in"; then rm -f "$ac_dir/POTFILES" test -n "$as_me" && echo "$as_me: creating $ac_dir/POTFILES" || echo "creating $ac_dir/POTFILES" - cat "$ac_given_srcdir/$ac_dir/POTFILES.in" | sed -e "/^#/d" -e "/^[ ]*\$/d" -e "s,.*, $top_srcdir/& \\\\," | sed -e "\$s/\(.*\) \\\\/\1/" > "$ac_dir/POTFILES" + gt_tab=`printf '\t'` + cat "$ac_given_srcdir/$ac_dir/POTFILES.in" | sed -e "/^#/d" -e "/^[ ${gt_tab}]*\$/d" -e "s,.*, $top_srcdir/& \\\\," | sed -e "\$s/\(.*\) \\\\/\1/" > "$ac_dir/POTFILES" POMAKEFILEDEPS="POTFILES.in" # ALL_LINGUAS, POFILES, UPDATEPOFILES, DUMMYPOFILES, GMOFILES depend # on $ac_dir but don't depend on user-specified configuration @@ -129,12 +131,12 @@ changequote([,])dnl test -n "$as_me" && echo "$as_me: setting ALL_LINGUAS in configure.in is obsolete" || echo "setting ALL_LINGUAS in configure.in is obsolete" fi ALL_LINGUAS_=`sed -e "/^#/d" -e "s/#.*//" "$ac_given_srcdir/$ac_dir/LINGUAS"` - # Hide the ALL_LINGUAS assigment from automake < 1.5. + # Hide the ALL_LINGUAS assignment from automake < 1.5. eval 'ALL_LINGUAS''=$ALL_LINGUAS_' POMAKEFILEDEPS="$POMAKEFILEDEPS LINGUAS" else # The set of available languages was given in configure.in. - # Hide the ALL_LINGUAS assigment from automake < 1.5. + # Hide the ALL_LINGUAS assignment from automake < 1.5. eval 'ALL_LINGUAS''=$OBSOLETE_ALL_LINGUAS' fi # Compute POFILES @@ -226,7 +228,7 @@ AC_DEFUN([AM_POSTPROCESS_PO_MAKEFILE], changequote(,)dnl # Adjust a relative srcdir. ac_dir=`echo "$ac_file"|sed 's%/[^/][^/]*$%%'` - ac_dir_suffix="/`echo "$ac_dir"|sed 's%^\./%%'`" + ac_dir_suffix=/`echo "$ac_dir"|sed 's%^\./%%'` ac_dots=`echo "$ac_dir_suffix"|sed 's%/[^/]*%../%g'` # In autoconf-2.13 it is called $ac_given_srcdir. # In autoconf-2.50 it is called $srcdir. @@ -254,6 +256,7 @@ EOT fi # A sed script that extracts the value of VARIABLE from a Makefile. + tab=`printf '\t'` sed_x_variable=' # Test if the hold space is empty. x @@ -261,9 +264,9 @@ s/P/P/ x ta # Yes it was empty. Look if we have the expected variable definition. -/^[ ]*VARIABLE[ ]*=/{ +/^['"${tab}"' ]*VARIABLE['"${tab}"' ]*=/{ # Seen the first line of the variable definition. - s/^[ ]*VARIABLE[ ]*=// + s/^['"${tab}"' ]*VARIABLE['"${tab}"' ]*=// ba } bd @@ -315,7 +318,7 @@ changequote([,])dnl sed_x_LINGUAS=`$gt_echo "$sed_x_variable" | sed -e '/^ *#/d' -e 's/VARIABLE/LINGUAS/g'` ALL_LINGUAS_=`sed -n -e "$sed_x_LINGUAS" < "$ac_file"` fi - # Hide the ALL_LINGUAS assigment from automake < 1.5. + # Hide the ALL_LINGUAS assignment from automake < 1.5. eval 'ALL_LINGUAS''=$ALL_LINGUAS_' # Compute POFILES # as $(foreach lang, $(ALL_LINGUAS), $(srcdir)/$(lang).po) @@ -405,14 +408,15 @@ changequote([,])dnl fi sed -e "s|@POTFILES_DEPS@|$POTFILES_DEPS|g" -e "s|@POFILES@|$POFILES|g" -e "s|@UPDATEPOFILES@|$UPDATEPOFILES|g" -e "s|@DUMMYPOFILES@|$DUMMYPOFILES|g" -e "s|@GMOFILES@|$GMOFILES|g" -e "s|@PROPERTIESFILES@|$PROPERTIESFILES|g" -e "s|@CLASSFILES@|$CLASSFILES|g" -e "s|@QMFILES@|$QMFILES|g" -e "s|@MSGFILES@|$MSGFILES|g" -e "s|@RESOURCESDLLFILES@|$RESOURCESDLLFILES|g" -e "s|@CATALOGS@|$CATALOGS|g" -e "s|@JAVACATALOGS@|$JAVACATALOGS|g" -e "s|@QTCATALOGS@|$QTCATALOGS|g" -e "s|@TCLCATALOGS@|$TCLCATALOGS|g" -e "s|@CSHARPCATALOGS@|$CSHARPCATALOGS|g" -e 's,^#distdir:,distdir:,' < "$ac_file" > "$ac_file.tmp" + tab=`printf '\t'` if grep -l '@TCLCATALOGS@' "$ac_file" > /dev/null; then # Add dependencies that cannot be formulated as a simple suffix rule. for lang in $ALL_LINGUAS; do frobbedlang=`echo $lang | sed -e 's/\..*$//' -e 'y/ABCDEFGHIJKLMNOPQRSTUVWXYZ/abcdefghijklmnopqrstuvwxyz/'` cat >> "$ac_file.tmp" <<EOF $frobbedlang.msg: $lang.po - @echo "\$(MSGFMT) -c --tcl -d \$(srcdir) -l $lang $srcdirpre$lang.po"; \ - \$(MSGFMT) -c --tcl -d "\$(srcdir)" -l $lang $srcdirpre$lang.po || { rm -f "\$(srcdir)/$frobbedlang.msg"; exit 1; } +${tab}@echo "\$(MSGFMT) -c --tcl -d \$(srcdir) -l $lang $srcdirpre$lang.po"; \ +${tab}\$(MSGFMT) -c --tcl -d "\$(srcdir)" -l $lang $srcdirpre$lang.po || { rm -f "\$(srcdir)/$frobbedlang.msg"; exit 1; } EOF done fi @@ -422,8 +426,8 @@ EOF frobbedlang=`echo $lang | sed -e 's/_/-/g' -e 's/^sr-CS/sr-SP/' -e 's/@latin$/-Latn/' -e 's/@cyrillic$/-Cyrl/' -e 's/^sr-SP$/sr-SP-Latn/' -e 's/^uz-UZ$/uz-UZ-Latn/'` cat >> "$ac_file.tmp" <<EOF $frobbedlang/\$(DOMAIN).resources.dll: $lang.po - @echo "\$(MSGFMT) -c --csharp -d \$(srcdir) -l $lang $srcdirpre$lang.po -r \$(DOMAIN)"; \ - \$(MSGFMT) -c --csharp -d "\$(srcdir)" -l $lang $srcdirpre$lang.po -r "\$(DOMAIN)" || { rm -f "\$(srcdir)/$frobbedlang.msg"; exit 1; } +${tab}@echo "\$(MSGFMT) -c --csharp -d \$(srcdir) -l $lang $srcdirpre$lang.po -r \$(DOMAIN)"; \ +${tab}\$(MSGFMT) -c --csharp -d "\$(srcdir)" -l $lang $srcdirpre$lang.po -r "\$(DOMAIN)" || { rm -f "\$(srcdir)/$frobbedlang.msg"; exit 1; } EOF done fi diff --git a/m4/progtest.m4 b/m4/progtest.m4 index 2d804ac9..b499f79c 100644 --- a/m4/progtest.m4 +++ b/m4/progtest.m4 @@ -1,5 +1,5 @@ -# progtest.m4 serial 6 (gettext-0.18) -dnl Copyright (C) 1996-2003, 2005, 2008-2010 Free Software Foundation, Inc. +# progtest.m4 serial 7 (gettext-0.18.2) +dnl Copyright (C) 1996-2003, 2005, 2008-2014 Free Software Foundation, Inc. dnl This file is free software; the Free Software Foundation dnl gives unlimited permission to copy and/or distribute it, dnl with or without modifications, as long as this notice is preserved. @@ -27,15 +27,14 @@ AC_DEFUN([AM_PATH_PROG_WITH_TEST], # Prepare PATH_SEPARATOR. # The user is always right. if test "${PATH_SEPARATOR+set}" != set; then - echo "#! /bin/sh" >conf$$.sh - echo "exit 0" >>conf$$.sh - chmod +x conf$$.sh - if (PATH="/nonexistent;."; conf$$.sh) >/dev/null 2>&1; then - PATH_SEPARATOR=';' - else - PATH_SEPARATOR=: - fi - rm -f conf$$.sh + # Determine PATH_SEPARATOR by trying to find /bin/sh in a PATH which + # contains only /bin. Note that ksh looks also at the FPATH variable, + # so we have to set that as well for the test. + PATH_SEPARATOR=: + (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + && { (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 \ + || PATH_SEPARATOR=';' + } fi # Find out how to test for executable files. Don't use a zero-byte file, @@ -142,17 +142,20 @@ static bool disallow_var_assigns = false; /* true for --exec */ static void add_preassign(enum assign_type type, char *val); +static void parse_args(int argc, char **argv); +static void set_locale_stuff(void); +static bool stopped_early = false; + int do_flags = false; bool do_optimize = false; /* apply default optimizations */ static int do_nostalgia = false; /* provide a blast from the past */ static int do_binary = false; /* hands off my data! */ static int do_version = false; /* print version info */ +static const char *locale = ""; /* default value to setlocale */ int use_lc_numeric = false; /* obey locale for decimal point */ -#if MBS_SUPPORT int gawk_mb_cur_max; /* MB_CUR_MAX value, see comment in main() */ -#endif FILE *output_fp; /* default gawk output, can be redirected in the debugger */ bool output_is_tty = false; /* control flushing of output */ @@ -186,6 +189,9 @@ static const struct option optab[] = { { "lint", optional_argument, NULL, 'L' }, { "lint-old", no_argument, NULL, 't' }, { "load", required_argument, NULL, 'l' }, +#if defined(LOCALEDEBUG) + { "locale", required_argument, NULL, 'Z' }, +#endif { "non-decimal-data", no_argument, NULL, 'n' }, { "nostalgia", no_argument, & do_nostalgia, 1 }, { "optimize", no_argument, NULL, 'O' }, @@ -209,15 +215,7 @@ static const struct option optab[] = { int main(int argc, char **argv) { - /* - * The + on the front tells GNU getopt not to rearrange argv. - */ - const char *optlist = "+F:f:v:W;bcCd::D::e:E:ghi:l:L:nNo::Op::MPrStVY"; - bool stopped_early = false; - int old_optind; int i; - int c; - char *scan, *src; char *extra_stack; int have_srcfile = 0; SRCFILE *s; @@ -233,49 +231,11 @@ main(int argc, char **argv) #endif /* HAVE_MTRACE */ #endif /* HAVE_MCHECK_H */ -#if defined(LC_CTYPE) - setlocale(LC_CTYPE, ""); -#endif -#if defined(LC_COLLATE) - setlocale(LC_COLLATE, ""); -#endif -#if defined(LC_MESSAGES) - setlocale(LC_MESSAGES, ""); -#endif -#if defined(LC_NUMERIC) && defined(HAVE_LOCALE_H) - /* - * Force the issue here. According to POSIX 2001, decimal - * point is used for parsing source code and for command-line - * assignments and the locale value for processing input, - * number to string conversion, and printing output. - * - * 10/2005 --- see below also; we now only use the locale's - * decimal point if do_posix in effect. - * - * 9/2007: - * This is a mess. We need to get the locale's numeric info for - * the thousands separator for the %'d flag. - */ - setlocale(LC_NUMERIC, ""); - init_locale(& loc); - setlocale(LC_NUMERIC, "C"); -#endif -#if defined(LC_TIME) - setlocale(LC_TIME, ""); -#endif - -#if MBS_SUPPORT - /* - * In glibc, MB_CUR_MAX is actually a function. This value is - * tested *a lot* in many speed-critical places in gawk. Caching - * this value once makes a speed difference. - */ - gawk_mb_cur_max = MB_CUR_MAX; - /* Without MBS_SUPPORT, gawk_mb_cur_max is 1. */ + myname = gawk_name(argv[0]); + os_arg_fixup(&argc, &argv); /* emulate redirection, expand wildcards */ - /* init the cache for checking bytes if they're characters */ - init_btowc_cache(); -#endif + if (argc < 2) + usage(EXIT_FAILURE, stderr); (void) bindtextdomain(PACKAGE, LOCALEDIR); (void) textdomain(PACKAGE); @@ -307,12 +267,6 @@ main(int argc, char **argv) (void) stackoverflow_install_handler(catchstackoverflow, extra_stack, STACK_SIZE); #undef STACK_SIZE - myname = gawk_name(argv[0]); - os_arg_fixup(&argc, &argv); /* emulate redirection, expand wildcards */ - - if (argc < 2) - usage(EXIT_FAILURE, stderr); - /* initialize the null string */ Nnull_string = make_string("", 0); @@ -327,230 +281,22 @@ main(int argc, char **argv) output_fp = stdout; - /* we do error messages ourselves on invalid options */ - opterr = false; - - /* copy argv before getopt gets to it; used to restart the debugger */ - save_argv(argc, argv); - /* initialize global (main) execution context */ push_context(new_context()); - /* option processing. ready, set, go! */ - for (optopt = 0, old_optind = 1; - (c = getopt_long(argc, argv, optlist, optab, NULL)) != EOF; - optopt = 0, old_optind = optind) { - if (do_posix) - opterr = true; - - switch (c) { - case 'F': - add_preassign(PRE_ASSIGN_FS, optarg); - break; - - case 'E': - disallow_var_assigns = true; - /* fall through */ - case 'f': - /* - * Allow multiple -f options. - * This makes function libraries real easy. - * Most of the magic is in the scanner. - * - * The following is to allow for whitespace at the end - * of a #! /bin/gawk line in an executable file - */ - scan = optarg; - if (argv[optind-1] != optarg) - while (isspace((unsigned char) *scan)) - scan++; - src = (*scan == '\0' ? argv[optind++] : optarg); - (void) add_srcfile((src && src[0] == '-' && src[1] == '\0') ? - SRC_STDIN : SRC_FILE, - src, srcfiles, NULL, NULL); - - break; - - case 'v': - add_preassign(PRE_ASSIGN, optarg); - break; - - case 'b': - do_binary = true; - break; - - case 'c': - do_flags |= DO_TRADITIONAL; - break; - - case 'C': - copyleft(); - break; - - case 'd': - do_flags |= DO_DUMP_VARS; - if (optarg != NULL && optarg[0] != '\0') - varfile = optarg; - break; - - case 'D': - do_flags |= DO_DEBUG; - if (optarg != NULL && optarg[0] != '\0') - command_file = optarg; - break; - - case 'e': - if (optarg[0] == '\0') - warning(_("empty argument to `-e/--source' ignored")); - else - (void) add_srcfile(SRC_CMDLINE, optarg, srcfiles, NULL, NULL); - break; - - case 'g': - do_flags |= DO_INTL; - break; - - case 'h': - /* write usage to stdout, per GNU coding stds */ - usage(EXIT_SUCCESS, stdout); - break; - - case 'i': - (void) add_srcfile(SRC_INC, optarg, srcfiles, NULL, NULL); - break; + parse_args(argc, argv); - case 'l': - (void) add_srcfile(SRC_EXTLIB, optarg, srcfiles, NULL, NULL); - break; + set_locale_stuff(); -#ifndef NO_LINT - case 'L': - do_flags |= DO_LINT_ALL; - if (optarg != NULL) { - if (strcmp(optarg, "fatal") == 0) - lintfunc = r_fatal; - else if (strcmp(optarg, "invalid") == 0) { - do_flags &= ~DO_LINT_ALL; - do_flags |= DO_LINT_INVALID; - } - } - break; - - case 't': - do_flags |= DO_LINT_OLD; - break; -#else - case 'L': - case 't': - break; -#endif - - case 'n': - do_flags |= DO_NON_DEC_DATA; - break; - - case 'N': - use_lc_numeric = true; - break; - - case 'O': - do_optimize = true; - break; - - case 'p': - do_flags |= DO_PROFILE; - /* fall through */ - case 'o': - do_flags |= DO_PRETTY_PRINT; - if (optarg != NULL) - set_prof_file(optarg); - else - set_prof_file(DEFAULT_PROFILE); - break; - - case 'M': -#ifdef HAVE_MPFR - do_flags |= DO_MPFR; -#else - warning(_("-M ignored: MPFR/GMP support not compiled in")); -#endif - break; - - case 'P': - do_flags |= DO_POSIX; - break; - - case 'r': - do_flags |= DO_INTERVALS; - break; - - case 'S': - do_flags |= DO_SANDBOX; - break; - - case 'V': - do_version = true; - break; - - case 'W': /* gawk specific options - now in getopt_long */ - fprintf(stderr, _("%s: option `-W %s' unrecognized, ignored\n"), - argv[0], optarg); - break; - - case 0: - /* - * getopt_long found an option that sets a variable - * instead of returning a letter. Do nothing, just - * cycle around for the next one. - */ - break; + /* + * In glibc, MB_CUR_MAX is actually a function. This value is + * tested *a lot* in many speed-critical places in gawk. Caching + * this value once makes a speed difference. + */ + gawk_mb_cur_max = MB_CUR_MAX; - case 'Y': -#if defined(YYDEBUG) || defined(GAWKDEBUG) - if (c == 'Y') { - yydebug = 2; - break; - } -#endif - /* if not debugging, fall through */ - case '?': - default: - /* - * If not posix, an unrecognized option stops argument - * processing so that it can go into ARGV for the awk - * program to see. This makes use of ``#! /bin/gawk -f'' - * easier. - * - * However, it's never simple. If optopt is set, - * an option that requires an argument didn't get the - * argument. We care because if opterr is 0, then - * getopt_long won't print the error message for us. - */ - if (! do_posix - && (optopt == '\0' || strchr(optlist, optopt) == NULL)) { - /* - * can't just do optind--. In case of an - * option with >= 2 letters, getopt_long - * won't have incremented optind. - */ - optind = old_optind; - stopped_early = true; - goto out; - } else if (optopt != '\0') { - /* Use POSIX required message format */ - fprintf(stderr, - _("%s: option requires an argument -- %c\n"), - myname, optopt); - usage(EXIT_FAILURE, stderr); - } - /* else - let getopt print error message for us */ - break; - } - if (c == 'E') /* --exec ends option processing */ - break; - } -out: + /* init the cache for checking bytes if they're characters */ + init_btowc_cache(); if (do_nostalgia) nostalgia(); @@ -583,7 +329,6 @@ out: if (do_lint && os_is_setuid()) warning(_("running %s setuid root may be a security problem"), myname); -#if MBS_SUPPORT if (do_binary) { if (do_posix) warning(_("`--posix' overrides `--characters-as-bytes'")); @@ -593,7 +338,6 @@ out: setlocale(LC_ALL, "C"); #endif } -#endif if (do_debug) /* Need to register the debugger pre-exec hook before any other */ init_debug(); @@ -734,9 +478,9 @@ out: * data using the local decimal point. */ if (use_lc_numeric) - setlocale(LC_NUMERIC, ""); + setlocale(LC_NUMERIC, locale); #endif - + init_io(); output_fp = stdout; @@ -1379,7 +1123,7 @@ arg_assign(char *arg, bool initing) setlocale(LC_NUMERIC, "C"); (void) force_number(it); if (do_posix) - setlocale(LC_NUMERIC, ""); + setlocale(LC_NUMERIC, locale); #endif /* LC_NUMERIC */ /* @@ -1643,3 +1387,285 @@ getenv_long(const char *name) } return -1; } + +/* parse_args --- do the getopt_long thing */ + +static void +parse_args(int argc, char **argv) +{ + /* + * The + on the front tells GNU getopt not to rearrange argv. + */ + const char *optlist = "+F:f:v:W;bcCd::D::e:E:ghi:l:L:nNo::Op::MPrStVYZ:"; + int old_optind; + int c; + char *scan; + char *src; + + /* we do error messages ourselves on invalid options */ + opterr = false; + + /* copy argv before getopt gets to it; used to restart the debugger */ + save_argv(argc, argv); + + /* option processing. ready, set, go! */ + for (optopt = 0, old_optind = 1; + (c = getopt_long(argc, argv, optlist, optab, NULL)) != EOF; + optopt = 0, old_optind = optind) { + if (do_posix) + opterr = true; + + switch (c) { + case 'F': + add_preassign(PRE_ASSIGN_FS, optarg); + break; + + case 'E': + disallow_var_assigns = true; + /* fall through */ + case 'f': + /* + * Allow multiple -f options. + * This makes function libraries real easy. + * Most of the magic is in the scanner. + * + * The following is to allow for whitespace at the end + * of a #! /bin/gawk line in an executable file + */ + scan = optarg; + if (argv[optind-1] != optarg) + while (isspace((unsigned char) *scan)) + scan++; + src = (*scan == '\0' ? argv[optind++] : optarg); + (void) add_srcfile((src && src[0] == '-' && src[1] == '\0') ? + SRC_STDIN : SRC_FILE, + src, srcfiles, NULL, NULL); + + break; + + case 'v': + add_preassign(PRE_ASSIGN, optarg); + break; + + case 'b': + do_binary = true; + break; + + case 'c': + do_flags |= DO_TRADITIONAL; + break; + + case 'C': + copyleft(); + break; + + case 'd': + do_flags |= DO_DUMP_VARS; + if (optarg != NULL && optarg[0] != '\0') + varfile = optarg; + break; + + case 'D': + do_flags |= DO_DEBUG; + if (optarg != NULL && optarg[0] != '\0') + command_file = optarg; + break; + + case 'e': + if (optarg[0] == '\0') + warning(_("empty argument to `-e/--source' ignored")); + else + (void) add_srcfile(SRC_CMDLINE, optarg, srcfiles, NULL, NULL); + break; + + case 'g': + do_flags |= DO_INTL; + break; + + case 'h': + /* write usage to stdout, per GNU coding stds */ + usage(EXIT_SUCCESS, stdout); + break; + + case 'i': + (void) add_srcfile(SRC_INC, optarg, srcfiles, NULL, NULL); + break; + + case 'l': + (void) add_srcfile(SRC_EXTLIB, optarg, srcfiles, NULL, NULL); + break; + +#ifndef NO_LINT + case 'L': + do_flags |= DO_LINT_ALL; + if (optarg != NULL) { + if (strcmp(optarg, "fatal") == 0) + lintfunc = r_fatal; + else if (strcmp(optarg, "invalid") == 0) { + do_flags &= ~DO_LINT_ALL; + do_flags |= DO_LINT_INVALID; + } + } + break; + + case 't': + do_flags |= DO_LINT_OLD; + break; +#else + case 'L': + case 't': + break; +#endif + + case 'n': + do_flags |= DO_NON_DEC_DATA; + break; + + case 'N': + use_lc_numeric = true; + break; + + case 'O': + do_optimize = true; + break; + + case 'p': + do_flags |= DO_PROFILE; + /* fall through */ + case 'o': + do_flags |= DO_PRETTY_PRINT; + if (optarg != NULL) + set_prof_file(optarg); + else + set_prof_file(DEFAULT_PROFILE); + break; + + case 'M': +#ifdef HAVE_MPFR + do_flags |= DO_MPFR; +#else + warning(_("-M ignored: MPFR/GMP support not compiled in")); +#endif + break; + + case 'P': + do_flags |= DO_POSIX; + break; + + case 'r': + do_flags |= DO_INTERVALS; + break; + + case 'S': + do_flags |= DO_SANDBOX; + break; + + case 'V': + do_version = true; + break; + + case 'W': /* gawk specific options - now in getopt_long */ + fprintf(stderr, _("%s: option `-W %s' unrecognized, ignored\n"), + argv[0], optarg); + break; + + case 0: + /* + * getopt_long found an option that sets a variable + * instead of returning a letter. Do nothing, just + * cycle around for the next one. + */ + break; + + case 'Y': + case 'Z': +#if defined(YYDEBUG) || defined(GAWKDEBUG) + if (c == 'Y') { + yydebug = 2; + break; + } +#endif +#if defined(LOCALEDEBUG) + if (c == 'Z') { + locale = optarg; + break; + } +#endif + /* if not debugging, fall through */ + case '?': + default: + /* + * If not posix, an unrecognized option stops argument + * processing so that it can go into ARGV for the awk + * program to see. This makes use of ``#! /bin/gawk -f'' + * easier. + * + * However, it's never simple. If optopt is set, + * an option that requires an argument didn't get the + * argument. We care because if opterr is 0, then + * getopt_long won't print the error message for us. + */ + if (! do_posix + && (optopt == '\0' || strchr(optlist, optopt) == NULL)) { + /* + * can't just do optind--. In case of an + * option with >= 2 letters, getopt_long + * won't have incremented optind. + */ + optind = old_optind; + stopped_early = true; + goto out; + } else if (optopt != '\0') { + /* Use POSIX required message format */ + fprintf(stderr, + _("%s: option requires an argument -- %c\n"), + myname, optopt); + usage(EXIT_FAILURE, stderr); + } + /* else + let getopt print error message for us */ + break; + } + if (c == 'E') /* --exec ends option processing */ + break; + } +out: + return; +} + +/* set_locale_stuff --- setup the locale stuff */ + +static void +set_locale_stuff(void) +{ +#if defined(LC_CTYPE) + setlocale(LC_CTYPE, locale); +#endif +#if defined(LC_COLLATE) + setlocale(LC_COLLATE, locale); +#endif +#if defined(LC_MESSAGES) + setlocale(LC_MESSAGES, locale); +#endif +#if defined(LC_NUMERIC) && defined(HAVE_LOCALE_H) + /* + * Force the issue here. According to POSIX 2001, decimal + * point is used for parsing source code and for command-line + * assignments and the locale value for processing input, + * number to string conversion, and printing output. + * + * 10/2005 --- see below also; we now only use the locale's + * decimal point if do_posix in effect. + * + * 9/2007: + * This is a mess. We need to get the locale's numeric info for + * the thousands separator for the %'d flag. + */ + setlocale(LC_NUMERIC, locale); + init_locale(& loc); + setlocale(LC_NUMERIC, "C"); +#endif +#if defined(LC_TIME) + setlocale(LC_TIME, locale); +#endif +} diff --git a/mbsupport.h b/mbsupport.h index 9a62486f..f4e1a821 100644 --- a/mbsupport.h +++ b/mbsupport.h @@ -23,81 +23,25 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA */ -/* - * This file is needed because we test for i18n support in 3 different - * places, and we want a consistent definition in all of them. Following - * the ``Don't Repeat Yourself'' principle from "The Pragmatic Programmer", - * we centralize the tests here. - * - * This test is the union of all the current tests. - */ - -#ifdef HAVE_STDLIB_H -#include <stdlib.h> -#endif - -#ifndef NO_MBSUPPORT - -#if defined(HAVE_ISWCTYPE) \ - && defined(HAVE_LOCALE_H) \ - && (defined(HAVE_BTOWC) || defined(ZOS_USS)) \ - && defined(HAVE_MBRLEN) \ - && defined(HAVE_MBRTOWC) \ - && defined(HAVE_WCHAR_H) \ - && defined(HAVE_WCRTOMB) \ - && defined(HAVE_WCSCOLL) \ - && defined(HAVE_WCTYPE) \ - && defined(HAVE_WCTYPE_H) \ - && defined(HAVE_WCTYPE_T) \ - && defined(HAVE_WINT_T) \ - && defined(HAVE_ISWLOWER) \ - && defined(HAVE_ISWUPPER) \ - && defined(HAVE_TOWLOWER) \ - && defined(HAVE_TOWUPPER) \ - && (defined(HAVE_STDLIB_H) && defined(MB_CUR_MAX)) \ -/* We can handle multibyte strings. */ -# define MBS_SUPPORT 1 -#else -# define MBS_SUPPORT 0 -#endif -#else /* NO_MBSUPPORT is defined */ -# define MBS_SUPPORT 0 -#endif - -#if ! MBS_SUPPORT +#ifdef __DJGPP__ # undef MB_CUR_MAX # define MB_CUR_MAX 1 -/* All this glop is for dfa.c. Bleah. */ - -#ifndef __DJGPP__ -#define wchar_t char -#endif +/* All this glop is for DGJPP */ -#define wctype_t int -#define wint_t int -#define mbstate_t int -#define WEOF EOF #define towupper toupper #define towlower tolower -#ifndef __DJGPP__ -#define btowc(x) ((int)x) -#endif #define iswalnum isalnum #define iswalpha isalpha #define iswupper isupper -#if defined(ZOS_USS) -#undef towupper -#undef towlower -#undef btowc -#undef iswalnum -#undef iswalpha -#undef iswupper -#undef wctype -#undef iswctype -#undef wcscoll -#endif +#define iswlower islower + +#define mbrtowc(wcp, s, e, mbs) (-1) +#define mbrlen(s, e, mbs) strlen(s) +#define wcrtomb(wc, b, mbs) (-1) +#define wcslen strlen +#define wctob(wc) (EOF) extern wctype_t wctype(const char *name); extern int iswctype(wint_t wc, wctype_t desc); @@ -121,10 +121,8 @@ mpg_node(unsigned int tp) r->flags |= MALLOC|NUMBER|NUMCUR; r->stptr = NULL; r->stlen = 0; -#if MBS_SUPPORT r->wstptr = NULL; r->wstlen = 0; -#endif /* defined MBS_SUPPORT */ return r; } @@ -281,7 +281,6 @@ r_dupnode(NODE *n) r->flags &= ~FIELD; r->flags |= MALLOC; r->valref = 1; -#if MBS_SUPPORT /* * DON'T call free_wstr(r) here! * r->wstptr still points at n->wstptr's value, and we @@ -289,13 +288,11 @@ r_dupnode(NODE *n) */ r->wstptr = NULL; r->wstlen = 0; -#endif /* MBS_SUPPORT */ if ((n->flags & STRCUR) != 0) { emalloc(r->stptr, char *, n->stlen + 2, "r_dupnode"); memcpy(r->stptr, n->stptr, n->stlen); r->stptr[n->stlen] = '\0'; -#if MBS_SUPPORT if ((n->flags & WSTRCUR) != 0) { r->wstlen = n->wstlen; emalloc(r->wstptr, wchar_t *, sizeof(wchar_t) * (n->wstlen + 2), "r_dupnode"); @@ -303,7 +300,6 @@ r_dupnode(NODE *n) r->wstptr[n->wstlen] = L'\0'; r->flags |= WSTRCUR; } -#endif /* MBS_SUPPORT */ } return r; @@ -322,10 +318,8 @@ r_make_number(double x) r->valref = 1; r->stptr = NULL; r->stlen = 0; -#if MBS_SUPPORT r->wstptr = NULL; r->wstlen = 0; -#endif /* defined MBS_SUPPORT */ return r; } @@ -368,11 +362,8 @@ make_str_node(const char *s, size_t len, int flags) r->flags = (MALLOC|STRING|STRCUR); r->valref = 1; r->stfmt = -1; - -#if MBS_SUPPORT r->wstptr = NULL; r->wstlen = 0; -#endif /* MBS_SUPPORT */ if ((flags & ALREADY_MALLOCED) != 0) r->stptr = (char *) s; @@ -387,15 +378,12 @@ make_str_node(const char *s, size_t len, int flags) char *ptm; int c; const char *end; -#if MBS_SUPPORT mbstate_t cur_state; memset(& cur_state, 0, sizeof(cur_state)); -#endif end = &(r->stptr[len]); for (pf = ptm = r->stptr; pf < end;) { -#if MBS_SUPPORT /* * Keep multibyte characters together. This avoids * problems if a subsequent byte of a multibyte @@ -412,7 +400,7 @@ make_str_node(const char *s, size_t len, int flags) continue; } } -#endif + c = *pf++; if (c == '\\') { c = parse_escape(&pf); @@ -641,7 +629,6 @@ get_numbase(const char *s, bool use_locale) return 8; } -#if MBS_SUPPORT /* str2wstr --- convert a multibyte string to a wide string */ NODE * @@ -890,7 +877,6 @@ out: ; return NULL; } -#endif /* MBS_SUPPORT */ /* is_ieee_magic_val --- return true for +inf, -inf, +nan, -nan */ @@ -937,7 +923,6 @@ get_ieee_magic_val(const char *val) return v; } -#if MBS_SUPPORT wint_t btowc_cache[256]; /* init_btowc_cache --- initialize the cache */ @@ -950,7 +935,6 @@ void init_btowc_cache() btowc_cache[i] = btowc(i); } } -#endif #define BLOCKCHUNK 100 diff --git a/pc/ChangeLog b/pc/ChangeLog index 235f520c..218621eb 100644 --- a/pc/ChangeLog +++ b/pc/ChangeLog @@ -1,3 +1,17 @@ +2014-11-21 Arnold D. Robbins <arnold@skeeve.com> + + * Makefile.tst (id): Add an 'expect to fail for DJGPP' message. + +2014-11-13 Scott Deifik <scottd.mail@sbcglobal.net> + + * Makefile.tst: Sync with mainline. + +2014-10-12 KO Myung-Hun <komh78@gmail.com> + + Fixes for OS/2: + + * gawkmisc.pc (init_sockets): Add additional checks for __EMX__. + 2014-09-23 Scott Deifik <scottd.mail@sbcglobal.net> * Makefile.tst: Sync with mainline. diff --git a/pc/Makefile.tst b/pc/Makefile.tst index 48fc5189..79d01ad9 100644 --- a/pc/Makefile.tst +++ b/pc/Makefile.tst @@ -183,7 +183,7 @@ GAWK_EXT_TESTS = \ colonwarn clos1way dbugeval delsub devfd devfd1 devfd2 dumpvars exit \ fieldwdth fpat1 fpat2 fpat3 fpatnull fsfwfs funlen \ functab1 functab2 functab3 fwtest fwtest2 fwtest3 \ - gensub gensub2 getlndir gnuops2 gnuops3 gnureops \ + genpot gensub gensub2 getlndir gnuops2 gnuops3 gnureops \ icasefs icasers id igncdym igncfs ignrcas2 ignrcase \ incdupe incdupe2 incdupe3 incdupe4 incdupe5 incdupe6 incdupe7 \ include include2 indirectcall indirectcall2 \ @@ -191,7 +191,7 @@ GAWK_EXT_TESTS = \ manyfiles match1 match2 match3 mbstr1 \ nastyparm next nondec nondec2 \ patsplit posix printfbad1 printfbad2 printfbad3 printhuge procinfs \ - profile1 profile2 profile3 profile4 profile5 pty1 \ + profile1 profile2 profile3 profile4 profile5 profile6 profile7 pty1 \ rebuf regnul1 regnul2 regx8bit reginttrad reint reint2 rsgetline rsglstdin rsstart1 \ rsstart2 rsstart3 rstest6 shadow sortfor sortu split_after_fpat \ splitarg4 strftime \ @@ -322,6 +322,8 @@ charset-msg-start: @echo "************************************************" @echo "** Some or all of these tests may fail if you **" @echo "** have inadequate or missing locale support **" + @echo "** At least en_US.UTF-8, ru_RU.UTF-8 and **" + @echo "** ja_JP.UTF-8 are needed. **" @echo "************************************************" charset-msg-end: @@ -861,7 +863,7 @@ dumpvars:: profile1: @echo $@ @$(AWK) --pretty-print=ap-$@.out -f "$(srcdir)"/xref.awk "$(srcdir)"/dtdgport.awk > _$@.out1 - @$(AWK) -f ap-$@.out "$(srcdir)"/dtdgport.awk > _$@.out2 ; rm ap-$@.out + @$(AWK) -f ./ap-$@.out "$(srcdir)"/dtdgport.awk > _$@.out2 ; rm ap-$@.out @$(CMP) _$@.out1 _$@.out2 && rm _$@.out[12] || { echo EXIT CODE: $$? >>_$@ ; \ cp "$(srcdir)"/dtdgport.awk > $@.ok ; } @@ -890,6 +892,18 @@ profile5: @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +profile6: + @echo $@ + @$(AWK) --profile=ap-$@.out -f "$(srcdir)"/$@.awk > /dev/null + @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + +profile7: + @echo $@ + @$(AWK) --profile=ap-$@.out -f "$(srcdir)"/$@.awk > /dev/null + @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + posix2008sub: @echo $@ @$(AWK) --posix -f "$(srcdir)"/$@.awk > _$@ 2>&1 @@ -1055,7 +1069,7 @@ testext:: @echo $@ # @$(AWK) '/^(@load|BEGIN)/,/^}/' "$(top_srcdir)"/extension/testext.c > testext.awk @$(AWK) ' /^(@load|BEGIN)/,/^}/' "$(top_srcdir)"/extension/testext.c > testext.awk - @$(AWK) -f testext.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @$(AWK) -f ./testext.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ testext.awk readdir: @@ -1176,6 +1190,11 @@ filefuncs: @echo $@ @AWKPATH="$(srcdir)" $(AWK) -f $@.awk -v builddir="$(abs_top_builddir)" >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + +genpot: + @echo $@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk --gen-pot >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ Gt-dummy: # file Maketests, generated from Makefile.am by the Gentests program addcomma: @@ -2240,6 +2259,7 @@ icasers: id: @echo $@ + @echo Expect id to fail with DJGPP. @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ diff --git a/pc/gawkmisc.pc b/pc/gawkmisc.pc index 239f3f8f..fdd32e7e 100644 --- a/pc/gawkmisc.pc +++ b/pc/gawkmisc.pc @@ -850,12 +850,12 @@ w32_shutdown (int fd, int how) #endif /* __MINGW32__ */ -#if defined(__DJGPP__) || defined(__MINGW32__) +#if defined(__DJGPP__) || defined(__MINGW32__) || defined(__EMX__) void init_sockets(void) { -#ifdef HAVE_SOCKETS +#if defined(HAVE_SOCKETS) && !defined(__EMX__) WSADATA winsockData; int errcode; diff --git a/po/ChangeLog b/po/ChangeLog index a9cca765..022e5326 100644 --- a/po/ChangeLog +++ b/po/ChangeLog @@ -1,3 +1,8 @@ +2014-11-19 gettextize <bug-gnu-gettext@gnu.org> + + * Makefile.in.in: Upgrade to gettext-0.19.3. + * Rules-quot: Upgrade to gettext-0.19.3. + 2014-04-08 Arnold D. Robbins <arnold@skeeve.com> * 4.1.1: Release tar ball made. diff --git a/po/Makefile.in.in b/po/Makefile.in.in index 83d8838a..65184f65 100644 --- a/po/Makefile.in.in +++ b/po/Makefile.in.in @@ -8,13 +8,14 @@ # Please note that the actual code of GNU gettext is covered by the GNU # General Public License and is *not* in the public domain. # -# Origin: gettext-0.18 -GETTEXT_MACRO_VERSION = 0.18 +# Origin: gettext-0.19 +GETTEXT_MACRO_VERSION = 0.19 PACKAGE = @PACKAGE@ VERSION = @VERSION@ PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +SED = @SED@ SHELL = /bin/sh @SET_MAKE@ @@ -76,6 +77,16 @@ POTFILES = \ CATALOGS = @CATALOGS@ +POFILESDEPS_ = $(srcdir)/$(DOMAIN).pot +POFILESDEPS_yes = $(POFILESDEPS_) +POFILESDEPS_no = +POFILESDEPS = $(POFILESDEPS_$(PO_DEPENDS_ON_POT)) + +DISTFILESDEPS_ = update-po +DISTFILESDEPS_yes = $(DISTFILESDEPS_) +DISTFILESDEPS_no = +DISTFILESDEPS = $(DISTFILESDEPS_$(DIST_DEPENDS_ON_UPDATE_PO)) + # Makevars gets inserted here. (Don't remove this line!) .SUFFIXES: @@ -96,14 +107,14 @@ CATALOGS = @CATALOGS@ mv t-$@ $@ -all: check-macro-version all-@USE_NLS@ +all: all-@USE_NLS@ all-yes: stamp-po all-no: # Ensure that the gettext macros and this Makefile.in.in are in sync. -check-macro-version: - @test "$(GETTEXT_MACRO_VERSION)" = "@GETTEXT_MACRO_VERSION@" \ +CHECK_MACRO_VERSION = \ + test "$(GETTEXT_MACRO_VERSION)" = "@GETTEXT_MACRO_VERSION@" \ || { echo "*** error: gettext infrastructure mismatch: using a Makefile.in.in from gettext version $(GETTEXT_MACRO_VERSION) but the autoconf macros are from gettext version @GETTEXT_MACRO_VERSION@" 1>&2; \ exit 1; \ } @@ -123,6 +134,7 @@ check-macro-version: # $(POFILES) has been designed to not touch files that don't need to be # changed. stamp-po: $(srcdir)/$(DOMAIN).pot + @$(CHECK_MACRO_VERSION) test ! -f $(srcdir)/$(DOMAIN).pot || \ test -z "$(GMOFILES)" || $(MAKE) $(GMOFILES) @test ! -f $(srcdir)/$(DOMAIN).pot || { \ @@ -137,11 +149,29 @@ stamp-po: $(srcdir)/$(DOMAIN).pot # This target rebuilds $(DOMAIN).pot; it is an expensive operation. # Note that $(DOMAIN).pot is not touched if it doesn't need to be changed. +# The determination of whether the package xyz is a GNU one is based on the +# heuristic whether some file in the top level directory mentions "GNU xyz". +# If GNU 'find' is available, we avoid grepping through monster files. $(DOMAIN).pot-update: $(POTFILES) $(srcdir)/POTFILES.in remove-potcdate.sed - if LC_ALL=C grep 'GNU @PACKAGE@' $(top_srcdir)/* 2>/dev/null | grep -v 'libtool:' >/dev/null; then \ - package_gnu='GNU '; \ + package_gnu="$(PACKAGE_GNU)"; \ + test -n "$$package_gnu" || { \ + if { if (LC_ALL=C find --version) 2>/dev/null | grep GNU >/dev/null; then \ + LC_ALL=C find -L $(top_srcdir) -maxdepth 1 -type f \ + -size -10000000c -exec grep 'GNU @PACKAGE@' \ + /dev/null '{}' ';' 2>/dev/null; \ + else \ + LC_ALL=C grep 'GNU @PACKAGE@' $(top_srcdir)/* 2>/dev/null; \ + fi; \ + } | grep -v 'libtool:' >/dev/null; then \ + package_gnu=yes; \ + else \ + package_gnu=no; \ + fi; \ + }; \ + if test "$$package_gnu" = "yes"; then \ + package_prefix='GNU '; \ else \ - package_gnu=''; \ + package_prefix=''; \ fi; \ if test -n '$(MSGID_BUGS_ADDRESS)' || test '$(PACKAGE_BUGREPORT)' = '@'PACKAGE_BUGREPORT'@'; then \ msgid_bugs_address='$(MSGID_BUGS_ADDRESS)'; \ @@ -161,7 +191,7 @@ $(DOMAIN).pot-update: $(POTFILES) $(srcdir)/POTFILES.in remove-potcdate.sed --add-comments=TRANSLATORS: $(XGETTEXT_OPTIONS) @XGETTEXT_EXTRA_OPTIONS@ \ --files-from=$(srcdir)/POTFILES.in \ --copyright-holder='$(COPYRIGHT_HOLDER)' \ - --package-name="$${package_gnu}@PACKAGE@" \ + --package-name="$${package_prefix}@PACKAGE@" \ --package-version='@VERSION@' \ --msgid-bugs-address="$$msgid_bugs_address" \ ;; \ @@ -189,9 +219,10 @@ $(srcdir)/$(DOMAIN).pot: # This target rebuilds a PO file if $(DOMAIN).pot has changed. # Note that a PO file is not touched if it doesn't need to be changed. -$(POFILES): $(srcdir)/$(DOMAIN).pot +$(POFILES): $(POFILESDEPS) @lang=`echo $@ | sed -e 's,.*/,,' -e 's/\.po$$//'`; \ if test -f "$(srcdir)/$${lang}.po"; then \ + test -f $(srcdir)/$(DOMAIN).pot || $(MAKE) $(srcdir)/$(DOMAIN).pot; \ test "$(srcdir)" = . && cdcmd="" || cdcmd="cd $(srcdir) && "; \ echo "$${cdcmd}$(MSGMERGE_UPDATE) $(MSGMERGE_OPTIONS) --lang=$${lang} $${lang}.po $(DOMAIN).pot"; \ cd $(srcdir) \ @@ -352,7 +383,7 @@ maintainer-clean: distclean distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir) dist distdir: - $(MAKE) update-po + test -z "$(DISTFILESDEPS)" || $(MAKE) $(DISTFILESDEPS) @$(MAKE) dist2 # This is a separate target because 'update-po' must be executed before. dist2: stamp-po $(DISTFILES) diff --git a/po/Makevars b/po/Makevars index c5a271db..4293de4e 100644 --- a/po/Makevars +++ b/po/Makevars @@ -20,6 +20,13 @@ XGETTEXT_OPTIONS = --keyword=_ --keyword=N_ # their copyright. COPYRIGHT_HOLDER = Free Software Foundation, Inc. +# This tells whether or not to prepend "GNU " prefix to the package +# name that gets inserted into the header of the $(DOMAIN).pot file. +# Possible values are "yes", "no", or empty. If it is empty, try to +# detect it automatically by scanning the files in $(top_srcdir) for +# "GNU packagename" string. +PACKAGE_GNU = + # This is the email address or URL to which the translators shall report # bugs in the untranslated strings: # - Strings which are not entire sentences, see the maintainer guidelines @@ -34,8 +41,38 @@ COPYRIGHT_HOLDER = Free Software Foundation, Inc. # It can be your email address, or a mailing list address where translators # can write to without being subscribed, or the URL of a web page through # which the translators can contact you. -MSGID_BUGS_ADDRESS = arnold@skeeve.com +MSGID_BUGS_ADDRESS = bug-gawk@gnu.org # This is the list of locale categories, beyond LC_MESSAGES, for which the # message catalogs shall be used. It is usually empty. EXTRA_LOCALE_CATEGORIES = + +# This tells whether the $(DOMAIN).pot file contains messages with an 'msgctxt' +# context. Possible values are "yes" and "no". Set this to yes if the +# package uses functions taking also a message context, like pgettext(), or +# if in $(XGETTEXT_OPTIONS) you define keywords with a context argument. +USE_MSGCTXT = no + +# These options get passed to msgmerge. +# Useful options are in particular: +# --previous to keep previous msgids of translated messages, +# --quiet to reduce the verbosity. +MSGMERGE_OPTIONS = + +# These options get passed to msginit. +# If you want to disable line wrapping when writing PO files, add +# --no-wrap to MSGMERGE_OPTIONS, XGETTEXT_OPTIONS, and +# MSGINIT_OPTIONS. +MSGINIT_OPTIONS = + +# This tells whether or not to regenerate a PO file when $(DOMAIN).pot +# has changed. Possible values are "yes" and "no". Set this to no if +# the POT file is checked in the repository and the version control +# program ignores timestamps. +PO_DEPENDS_ON_POT = yes + +# This tells whether or not to forcibly update $(DOMAIN).pot and +# regenerate PO files on "make dist". Possible values are "yes" and +# "no". Set this to no if the POT file and PO files are maintained +# externally. +DIST_DEPENDS_ON_UPDATE_PO = yes diff --git a/po/Makevars.template b/po/Makevars.template index 32692ab4..0648ec75 100644 --- a/po/Makevars.template +++ b/po/Makevars.template @@ -20,6 +20,13 @@ XGETTEXT_OPTIONS = --keyword=_ --keyword=N_ # their copyright. COPYRIGHT_HOLDER = Free Software Foundation, Inc. +# This tells whether or not to prepend "GNU " prefix to the package +# name that gets inserted into the header of the $(DOMAIN).pot file. +# Possible values are "yes", "no", or empty. If it is empty, try to +# detect it automatically by scanning the files in $(top_srcdir) for +# "GNU packagename" string. +PACKAGE_GNU = + # This is the email address or URL to which the translators shall report # bugs in the untranslated strings: # - Strings which are not entire sentences, see the maintainer guidelines @@ -39,3 +46,33 @@ MSGID_BUGS_ADDRESS = # This is the list of locale categories, beyond LC_MESSAGES, for which the # message catalogs shall be used. It is usually empty. EXTRA_LOCALE_CATEGORIES = + +# This tells whether the $(DOMAIN).pot file contains messages with an 'msgctxt' +# context. Possible values are "yes" and "no". Set this to yes if the +# package uses functions taking also a message context, like pgettext(), or +# if in $(XGETTEXT_OPTIONS) you define keywords with a context argument. +USE_MSGCTXT = no + +# These options get passed to msgmerge. +# Useful options are in particular: +# --previous to keep previous msgids of translated messages, +# --quiet to reduce the verbosity. +MSGMERGE_OPTIONS = + +# These options get passed to msginit. +# If you want to disable line wrapping when writing PO files, add +# --no-wrap to MSGMERGE_OPTIONS, XGETTEXT_OPTIONS, and +# MSGINIT_OPTIONS. +MSGINIT_OPTIONS = + +# This tells whether or not to regenerate a PO file when $(DOMAIN).pot +# has changed. Possible values are "yes" and "no". Set this to no if +# the POT file is checked in the repository and the version control +# program ignores timestamps. +PO_DEPENDS_ON_POT = yes + +# This tells whether or not to forcibly update $(DOMAIN).pot and +# regenerate PO files on "make dist". Possible values are "yes" and +# "no". Set this to no if the POT file and PO files are maintained +# externally. +DIST_DEPENDS_ON_UPDATE_PO = yes diff --git a/po/Rules-quot b/po/Rules-quot index af524879..9dc96307 100644 --- a/po/Rules-quot +++ b/po/Rules-quot @@ -1,3 +1,4 @@ +# This file, Rules-quot, can be copied and used freely without restrictions. # Special Makefile rules for English message catalogs with quotation marks. DISTFILES.common.extra1 = quot.sed boldquot.sed en@quot.header en@boldquot.header insert-header.sin Rules-quot @@ -14,13 +15,23 @@ en@boldquot.po-update: en@boldquot.po-update-en .insert-header.po-update-en: @lang=`echo $@ | sed -e 's/\.po-update-en$$//'`; \ - if test "$(PACKAGE)" = "gettext"; then PATH=`pwd`/../src:$$PATH; GETTEXTLIBDIR=`cd $(top_srcdir)/src && pwd`; export GETTEXTLIBDIR; fi; \ + if test "$(PACKAGE)" = "gettext-tools"; then PATH=`pwd`/../src:$$PATH; GETTEXTLIBDIR=`cd $(top_srcdir)/src && pwd`; export GETTEXTLIBDIR; fi; \ tmpdir=`pwd`; \ echo "$$lang:"; \ ll=`echo $$lang | sed -e 's/@.*//'`; \ LC_ALL=C; export LC_ALL; \ cd $(srcdir); \ - if $(MSGINIT) -i $(DOMAIN).pot --no-translator -l $$lang -o - 2>/dev/null | sed -f $$tmpdir/$$lang.insert-header | $(MSGCONV) -t UTF-8 | $(MSGFILTER) sed -f `echo $$lang | sed -e 's/.*@//'`.sed 2>/dev/null > $$tmpdir/$$lang.new.po; then \ + if $(MSGINIT) $(MSGINIT_OPTIONS) -i $(DOMAIN).pot --no-translator -l $$lang -o - 2>/dev/null \ + | $(SED) -f $$tmpdir/$$lang.insert-header | $(MSGCONV) -t UTF-8 | \ + { case `$(MSGFILTER) --version | sed 1q | sed -e 's,^[^0-9]*,,'` in \ + '' | 0.[0-9] | 0.[0-9].* | 0.1[0-8] | 0.1[0-8].*) \ + $(MSGFILTER) $(SED) -f `echo $$lang | sed -e 's/.*@//'`.sed \ + ;; \ + *) \ + $(MSGFILTER) `echo $$lang | sed -e 's/.*@//'` \ + ;; \ + esac } 2>/dev/null > $$tmpdir/$$lang.new.po \ + ; then \ if cmp $$lang.po $$tmpdir/$$lang.new.po >/dev/null 2>&1; then \ rm -f $$tmpdir/$$lang.new.po; \ else \ Binary files differ@@ -1,15 +1,15 @@ # Japanese messages for gawk. -# Copyright (C) 2003, 2011 Free Software Foundation, Inc. +# Copyright (C) 2003, 2014 Free Software Foundation, Inc. # This file is distributed under the same license as the gawk package. # Makoto Hosoya <mhosoya@ozemail.com.au>, 2003. -# Yasuaki Taniguchi <yasuakit@gmail.com>, 2011. +# Yasuaki Taniguchi <yasuakit@gmail.com>, 2011, 2014. # msgid "" msgstr "" -"Project-Id-Version: gawk 4.0.0\n" +"Project-Id-Version: gawk 4.1.0b\n" "Report-Msgid-Bugs-To: arnold@skeeve.com\n" "POT-Creation-Date: 2014-04-08 19:23+0300\n" -"PO-Revision-Date: 2011-07-17 08:28+0900\n" +"PO-Revision-Date: 2014-11-07 12:26+0000\n" "Last-Translator: Yasuaki Taniguchi <yasuakit@gmail.com>\n" "Language-Team: Japanese <translation-team-ja@lists.sourceforge.net>\n" "Language: ja\n" @@ -55,9 +55,8 @@ msgid "attempt to use scalar `%s[\"%.*s\"]' as an array" msgstr "スカラー `%s[\"%.*s\"]' を配列として使用する試みです" #: array.c:776 -#, fuzzy msgid "adump: first argument not an array" -msgstr "adump: 引数が配列ではありません" +msgstr "adump: 第一引数が配列ではありません" #: array.c:815 msgid "asort: second argument not an array" @@ -250,9 +249,9 @@ msgid "can't open source file `%s' for reading (%s)" msgstr "ソースファイル `%s' を読み込み用に開けません (%s)" #: awkgram.y:2384 awkgram.y:2509 -#, fuzzy, c-format +#, c-format msgid "can't open shared library `%s' for reading (%s)" -msgstr "ソースファイル `%s' を読み込み用に開けません (%s)" +msgstr "共有ライブラリ `%s' を読み込み用に開けません (%s)" #: awkgram.y:2386 awkgram.y:2460 awkgram.y:2510 builtin.c:135 debug.c:5206 msgid "reason unknown" @@ -269,9 +268,9 @@ msgid "already included source file `%s'" msgstr "ソースファイル `%s' は既に読み込まれています" #: awkgram.y:2409 -#, fuzzy, c-format +#, c-format msgid "already loaded shared library `%s'" -msgstr "ソースファイル `%s' は既に読み込まれています" +msgstr "共有ライブラリ `%s' は既に読み込まれています" #: awkgram.y:2444 msgid "@include is a gawk extension" @@ -282,14 +281,12 @@ msgid "empty filename after @include" msgstr "@include の後に空のファイル名があります" #: awkgram.y:2494 -#, fuzzy msgid "@load is a gawk extension" -msgstr "@include は gawk 拡張です" +msgstr "@load は gawk 拡張です" #: awkgram.y:2500 -#, fuzzy msgid "empty filename after @load" -msgstr "@include の後に空のファイル名があります" +msgstr "@load の後に空のファイル名があります" #: awkgram.y:2634 msgid "empty program text on command line" @@ -684,9 +681,8 @@ msgid "too many arguments supplied for format string" msgstr "書式文字列に与えられている引数が多すぎます" #: builtin.c:1634 -#, fuzzy msgid "sprintf: no arguments" -msgstr "printf: 引数がありません" +msgstr "sprintf: 引数がありません" #: builtin.c:1657 builtin.c:1668 msgid "printf: no arguments" @@ -834,19 +830,19 @@ msgid "lshift: received non-numeric second argument" msgstr "lshift: 非数値の第二引数を受け取りました" #: builtin.c:3038 -#, fuzzy, c-format +#, c-format msgid "lshift(%f, %f): negative values will give strange results" -msgstr "lshift(%lf, %lf): 負の数値を使用すると異常な結果になります" +msgstr "lshift(%f, %f): 負の数値を使用すると異常な結果になります" #: builtin.c:3040 -#, fuzzy, c-format +#, c-format msgid "lshift(%f, %f): fractional values will be truncated" -msgstr "lshift(%lf, %lf): 小数点以下は切り捨てられます" +msgstr "lshift(%f, %f): 小数点以下は切り捨てられます" #: builtin.c:3042 -#, fuzzy, c-format +#, c-format msgid "lshift(%f, %f): too large shift value will give strange results" -msgstr "lshift(%lf, %lf): シフト値が大き過ぎると異常な結果になります" +msgstr "lshift(%f, %f): シフト値が大き過ぎると異常な結果になります" #: builtin.c:3067 msgid "rshift: received non-numeric first argument" @@ -857,29 +853,28 @@ msgid "rshift: received non-numeric second argument" msgstr "rshift: 非数値の第二引数を受け取りました" #: builtin.c:3075 -#, fuzzy, c-format +#, c-format msgid "rshift(%f, %f): negative values will give strange results" -msgstr "rshift(%lf, %lf): 負の数値を使用すると異常な結果になります" +msgstr "rshift(%f, %f): 負の数値を使用すると異常な結果になります" #: builtin.c:3077 -#, fuzzy, c-format +#, c-format msgid "rshift(%f, %f): fractional values will be truncated" -msgstr "rshift(%lf, %lf): 小数点以下は切り捨てられます" +msgstr "rshift(%f, %f): 小数点以下は切り捨てられます" #: builtin.c:3079 -#, fuzzy, c-format +#, c-format msgid "rshift(%f, %f): too large shift value will give strange results" -msgstr "rshift(%lf, %lf): シフト値が大き過ぎると異常な結果になります" +msgstr "rshift(%f, %f): シフト値が大き過ぎると異常な結果になります" #: builtin.c:3104 mpfr.c:968 -#, fuzzy msgid "and: called with less than two arguments" -msgstr "sqrt: 負の値 %g を引数に使用して呼び出されました" +msgstr "and: 2個未満の引数で呼び出されました" #: builtin.c:3109 -#, fuzzy, c-format +#, c-format msgid "and: argument %d is non-numeric" -msgstr "exp: 引数 %g が範囲外です" +msgstr "and: 引数 %d が非数値です" #: builtin.c:3113 #, fuzzy, c-format @@ -887,14 +882,13 @@ msgid "and: argument %d negative value %g will give strange results" msgstr "and(%lf, %lf): 負の数値を使用すると異常な結果になります" #: builtin.c:3136 mpfr.c:1000 -#, fuzzy msgid "or: called with less than two arguments" -msgstr "sqrt: 負の値 %g を引数に使用して呼び出されました" +msgstr "or: 2個未満の引数で呼び出されました" #: builtin.c:3141 -#, fuzzy, c-format +#, c-format msgid "or: argument %d is non-numeric" -msgstr "exp: 引数 %g が範囲外です" +msgstr "or: 引数 %d が非数値です" #: builtin.c:3145 #, fuzzy, c-format @@ -904,12 +898,12 @@ msgstr "compl(%lf): 負の数値を使用すると異常な結果になります #: builtin.c:3167 mpfr.c:1031 #, fuzzy msgid "xor: called with less than two arguments" -msgstr "sqrt: 負の値 %g を引数に使用して呼び出されました" +msgstr "xor: 2個未満の引数で呼び出されました" #: builtin.c:3173 -#, fuzzy, c-format +#, c-format msgid "xor: argument %d is non-numeric" -msgstr "exp: 引数 %g が範囲外です" +msgstr "xor: 引数 %d が非数値です" #: builtin.c:3177 #, fuzzy, c-format @@ -921,14 +915,14 @@ msgid "compl: received non-numeric argument" msgstr "compl: 非数値の引数を受け取りました" #: builtin.c:3208 -#, fuzzy, c-format +#, c-format msgid "compl(%f): negative value will give strange results" -msgstr "compl(%lf): 負の数値を使用すると異常な結果になります" +msgstr "compl(%f): 負の数値を使用すると異常な結果になります" #: builtin.c:3210 -#, fuzzy, c-format +#, c-format msgid "compl(%f): fractional value will be truncated" -msgstr "compl(%lf): 小数点以下は切り捨てられます" +msgstr "compl(%f): 小数点以下は切り捨てられます" #: builtin.c:3379 #, c-format @@ -941,24 +935,24 @@ msgid "Type (g)awk statement(s). End with the command \"end\"\n" msgstr "" #: command.y:289 -#, fuzzy, c-format +#, c-format msgid "invalid frame number: %d" -msgstr "無効な範囲終了です" +msgstr "無効なフレーム番号です: %d" #: command.y:295 #, fuzzy, c-format msgid "info: invalid option - \"%s\"" -msgstr "%s: 無効なオプション -- '%c'\n" +msgstr "info: 無効なオプション - \"%s\"" #: command.y:321 #, c-format msgid "source \"%s\": already sourced." -msgstr "" +msgstr "source \"%s\": 既に読み込まれて(source)います。" #: command.y:326 #, c-format msgid "save \"%s\": command not permitted." -msgstr "" +msgstr "save \"%s\": コマンドは許可されていません。" #: command.y:339 msgid "Can't use command `commands' for breakpoint/watchpoint commands" @@ -966,11 +960,11 @@ msgstr "" #: command.y:341 msgid "no breakpoint/watchpoint has been set yet" -msgstr "" +msgstr "まだ一つもブレークポイント/ウオッチポイントは設定されていません" #: command.y:343 msgid "invalid breakpoint/watchpoint number" -msgstr "" +msgstr "無効なブレークポイント/ウオッチポイント番号です" #: command.y:348 #, c-format @@ -991,51 +985,49 @@ msgid "`silent' valid only in command `commands'" msgstr "" #: command.y:373 -#, fuzzy, c-format +#, c-format msgid "trace: invalid option - \"%s\"" -msgstr "%s: 無効なオプション -- '%c'\n" +msgstr "trace: 無効なオプション - \"%s\"" #: command.y:387 msgid "condition: invalid breakpoint/watchpoint number" msgstr "" #: command.y:449 -#, fuzzy msgid "argument not a string" -msgstr "exp: 引数 %g が範囲外です" +msgstr "引数が文字列ではありません" #: command.y:459 command.y:464 #, c-format msgid "option: invalid parameter - \"%s\"" -msgstr "" +msgstr "option: 無効なパラメーター - \"%s\"" #: command.y:474 #, c-format msgid "no such function - \"%s\"" -msgstr "" +msgstr "そのような関数はありません - \"%s\"" #: command.y:531 -#, fuzzy, c-format +#, c-format msgid "enable: invalid option - \"%s\"" -msgstr "%s: 無効なオプション -- '%c'\n" +msgstr "enable: 無効なオプション - \"%s\"" #: command.y:597 -#, fuzzy, c-format +#, c-format msgid "invalid range specification: %d - %d" -msgstr "無効な範囲終了です" +msgstr "無効な範囲指定: %d - %d" #: command.y:659 -#, fuzzy msgid "non-numeric value for field number" -msgstr "フィールド指定に不明な値があります: %d\n" +msgstr "フィールド番号に対して非数値が指定されています" #: command.y:680 command.y:687 msgid "non-numeric value found, numeric expected" -msgstr "" +msgstr "非数値が見つかりました。数値が予期されます。" #: command.y:712 command.y:718 msgid "non-zero integer value" -msgstr "" +msgstr "非ゼロ整数" #: command.y:817 msgid "" @@ -1243,9 +1235,8 @@ msgid "%s" msgstr "" #: command.y:1284 -#, fuzzy msgid "invalid character" -msgstr "無効な照合文字です" +msgstr "無効な文字です" #: command.y:1455 #, c-format @@ -1417,9 +1408,9 @@ msgid "" msgstr "" #: debug.c:1029 -#, fuzzy, c-format +#, c-format msgid "no symbol `%s' in current context\n" -msgstr "`next' は `%s' から呼び出すことが出来ません" +msgstr "" #: debug.c:1041 debug.c:1427 #, fuzzy, c-format @@ -1709,7 +1700,7 @@ msgstr "" #: debug.c:3424 #, fuzzy, c-format msgid "element not in array\n" -msgstr "delete: 配列 `%2$s' 内にインデックス `%1$s' がありません" +msgstr "adump: 引数が配列ではありません" #: debug.c:3424 #, c-format @@ -1754,14 +1745,13 @@ msgid "invalid number" msgstr "" #: debug.c:5381 -#, fuzzy, c-format +#, c-format msgid "`%s' not allowed in current context; statement ignored" -msgstr "`next' は `%s' から呼び出すことが出来ません" +msgstr "" #: debug.c:5389 -#, fuzzy msgid "`return' not allowed in current context; statement ignored" -msgstr "`next' は `%s' から呼び出すことが出来ません" +msgstr "" #: debug.c:5590 #, c-format @@ -2002,32 +1992,31 @@ msgid "make_builtin: negative argument count for function `%s'" msgstr "make_builtin: 関数 `%s' の引数の数が負です" #: ext.c:276 -#, fuzzy msgid "extension: missing function name" msgstr "extension: 関数名がありません" #: ext.c:279 ext.c:283 -#, fuzzy, c-format +#, c-format msgid "extension: illegal character `%c' in function name `%s'" msgstr "extension: 関数名 `%2$s' の中で不正な文字 `%1$c' が使用されています" #: ext.c:291 -#, fuzzy, c-format +#, c-format msgid "extension: can't redefine function `%s'" msgstr "extension: 関数 `%s' を再定義できません" #: ext.c:295 -#, fuzzy, c-format +#, c-format msgid "extension: function `%s' already defined" msgstr "extension: 関数 `%s' は既に定義されています" #: ext.c:299 -#, fuzzy, c-format +#, c-format msgid "extension: function name `%s' previously defined" -msgstr "関数名 `%s' は前に定義されています" +msgstr "extension: 関数名 `%s' は前に定義されています" #: ext.c:301 -#, fuzzy, c-format +#, c-format msgid "extension: can't use gawk built-in `%s' as function name" msgstr "extension: gawk に組み込まれている `%s' は関数名として使用出来ません" @@ -2076,9 +2065,9 @@ msgid "stat: bad parameters" msgstr "%s: 仮引数です\n" #: extension/filefuncs.c:533 -#, fuzzy, c-format +#, c-format msgid "fts init: could not create variable %s" -msgstr "index: 文字列では無い第二引数を受け取りました" +msgstr "" #: extension/filefuncs.c:554 #, fuzzy @@ -2094,9 +2083,8 @@ msgid "fill_stat_element: could not set element" msgstr "" #: extension/filefuncs.c:597 -#, fuzzy msgid "fill_path_element: could not set element" -msgstr "index: 文字列では無い第二引数を受け取りました" +msgstr "" #: extension/filefuncs.c:613 msgid "fill_error_element: could not set element" @@ -2108,9 +2096,8 @@ msgstr "" #: extension/filefuncs.c:670 extension/filefuncs.c:717 #: extension/filefuncs.c:735 -#, fuzzy msgid "fts-process: could not set element" -msgstr "index: 文字列では無い第二引数を受け取りました" +msgstr "" #: extension/filefuncs.c:784 #, fuzzy @@ -2133,9 +2120,8 @@ msgid "fts: bad third parameter" msgstr "%s: 仮引数です\n" #: extension/filefuncs.c:806 -#, fuzzy msgid "fts: could not flatten array\n" -msgstr "`%s' は不正な変数名です" +msgstr "" #: extension/filefuncs.c:824 msgid "fts: ignoring sneaky FTS_NOSTAT flag. nyah, nyah, nyah." @@ -2234,9 +2220,9 @@ msgid "inplace_begin: Cannot stat `%s' (%s)" msgstr "致命的: extension: `%s' を開くことが出来ません (%s)\n" #: extension/inplace.c:158 -#, fuzzy, c-format +#, c-format msgid "inplace_begin: `%s' is not a regular file" -msgstr "`%s' は不正な変数名です" +msgstr "" #: extension/inplace.c:169 #, c-format @@ -2379,7 +2365,7 @@ msgstr "exp: 引数 %g が範囲外です" #: extension/rwarray.c:293 #, fuzzy, c-format msgid "do_reada: argument 1 is not an array\n" -msgstr "match: 第三引数が配列ではありません" +msgstr "adump: 引数が配列ではありません" #: extension/rwarray.c:337 #, c-format @@ -3288,17 +3274,17 @@ msgstr "" #: mpfr.c:857 #, fuzzy msgid "%s: argument #%d negative value %Rg will give strange results" -msgstr "compl(%lf): 負の数値を使用すると異常な結果になります" +msgstr "and(%lf, %lf): 負の数値を使用すると異常な結果になります" #: mpfr.c:863 #, fuzzy msgid "%s: argument #%d fractional value %Rg will be truncated" -msgstr "or(%lf, %lf): 小数点以下は切り捨てられます" +msgstr "and(%lf, %lf): 小数点以下は切り捨てられます" #: mpfr.c:878 #, fuzzy, c-format msgid "%s: argument #%d negative value %Zd will give strange results" -msgstr "compl(%lf): 負の数値を使用すると異常な結果になります" +msgstr "and(%lf, %lf): 負の数値を使用すると異常な結果になります" #: msg.c:68 #, c-format @@ -3490,50 +3476,27 @@ msgstr "以前に正規表現がありません" msgid "can not pop main context" msgstr "" -#, fuzzy -#~ msgid "range of the form `[%c-%c]' is locale dependent" -#~ msgstr "`[%c-%c]' 形式の範囲はロケール依存です" - -#, fuzzy -#~ msgid "[s]printf called with no arguments" -#~ msgstr "sqrt: 負の値 %g を引数に使用して呼び出されました" - -#~ msgid "`-m[fr]' option irrelevant in gawk" -#~ msgstr "gawk ではオプション `-m[fr]' に効果はありません。" - -#~ msgid "-m option usage: `-m[fr] nnn'" -#~ msgstr "-m オプションの使用法: `-m[fr] 数値'" - -#, fuzzy -#~ msgid "%s: received non-numeric first argument" -#~ msgstr "or: 非数値の第一引数を受け取りました" - -#, fuzzy -#~ msgid "%s: received non-numeric second argument" -#~ msgstr "or: 非数値の第二引数を受け取りました" +#~ msgid "attempt to use function `%s' as an array" +#~ msgstr "関数 `%s' を配列として使用する試みです" -#, fuzzy -#~ msgid "%s(%Rg, ..): negative values will give strange results" -#~ msgstr "or(%lf, %lf): 負の数値を使用すると異常な結果になります" +#~ msgid "reference to uninitialized element `%s[\"%.*s\"]'" +#~ msgstr "初期化されていない要素 `%s[\"%.*s\"]' への参照です" -#, fuzzy -#~ msgid "%s(%Rg, ..): fractional values will be truncated" -#~ msgstr "or(%lf, %lf): 小数点以下は切り捨てられます" +#~ msgid "subscript of array `%s' is null string" +#~ msgstr "配列 `%s' の添字が NULL 文字列です" -#, fuzzy -#~ msgid "%s(%Zd, ..): negative values will give strange results" -#~ msgstr "or(%lf, %lf): 負の数値を使用すると異常な結果になります" +#~ msgid "%s: empty (null)\n" +#~ msgstr "%s: 空 (null)\n" -#, fuzzy -#~ msgid "%s(.., %Rg): negative values will give strange results" -#~ msgstr "or(%lf, %lf): 負の数値を使用すると異常な結果になります" +#~ msgid "%s: empty (zero)\n" +#~ msgstr "%s: 空 (zero)\n" -#, fuzzy -#~ msgid "%s(.., %Zd): negative values will give strange results" -#~ msgstr "or(%lf, %lf): 負の数値を使用すると異常な結果になります" +#~ msgid "%s: table_size = %d, array_size = %d\n" +#~ msgstr "" +#~ "%s: テーブルサイズ (table_size) = %d, 配列サイズ (array_size) = %d\n" -#~ msgid "`%s' is a Bell Labs extension" -#~ msgstr "`%s' はベル研究所による拡張です" +#~ msgid "%s: array_ref to %s\n" +#~ msgstr "%s: %s への配列参照 (array_ref) です\n" #~ msgid "`nextfile' is a gawk extension" #~ msgstr "`nextfile' は gawk 拡張です" @@ -3541,14 +3504,29 @@ msgstr "" #~ msgid "`delete array' is a gawk extension" #~ msgstr "`delete array' は gawk 拡張です" +#~ msgid "use of non-array as array" +#~ msgstr "配列でないものを配列として使用しています" + +#~ msgid "`%s' is a Bell Labs extension" +#~ msgstr "`%s' はベル研究所による拡張です" + #~ msgid "and: received non-numeric first argument" #~ msgstr "and: 非数値の第一引数を受け取りました" #~ msgid "and: received non-numeric second argument" #~ msgstr "and: 非数値の第二引数を受け取りました" -#~ msgid "and(%lf, %lf): fractional values will be truncated" -#~ msgstr "and(%lf, %lf): 小数点以下は切り捨てられます" +#~ msgid "or: received non-numeric first argument" +#~ msgstr "or: 非数値の第一引数を受け取りました" + +#~ msgid "or: received non-numeric second argument" +#~ msgstr "or: 非数値の第二引数を受け取りました" + +#~ msgid "or(%lf, %lf): negative values will give strange results" +#~ msgstr "or(%lf, %lf): 負の数値を使用すると異常な結果になります" + +#~ msgid "or(%lf, %lf): fractional values will be truncated" +#~ msgstr "or(%lf, %lf): 小数点以下は切り捨てられます" #~ msgid "xor: received non-numeric first argument" #~ msgstr "xor: 非数値の第一引数を受け取りました" @@ -3559,37 +3537,12 @@ msgstr "" #~ msgid "xor(%lf, %lf): fractional values will be truncated" #~ msgstr "xor(%lf, %lf): 小数点以下は切り捨てられます" -#~ msgid "Operation Not Supported" -#~ msgstr "この操作はサポートされていません" - -#~ msgid "attempt to use function `%s' as an array" -#~ msgstr "関数 `%s' を配列として使用する試みです" - -#~ msgid "reference to uninitialized element `%s[\"%.*s\"]'" -#~ msgstr "初期化されていない要素 `%s[\"%.*s\"]' への参照です" - -#~ msgid "subscript of array `%s' is null string" -#~ msgstr "配列 `%s' の添字が NULL 文字列です" - -#~ msgid "%s: empty (null)\n" -#~ msgstr "%s: 空 (null)\n" - -#~ msgid "%s: empty (zero)\n" -#~ msgstr "%s: 空 (zero)\n" - -#~ msgid "%s: table_size = %d, array_size = %d\n" -#~ msgstr "" -#~ "%s: テーブルサイズ (table_size) = %d, 配列サイズ (array_size) = %d\n" - -#~ msgid "%s: array_ref to %s\n" -#~ msgstr "%s: %s への配列参照 (array_ref) です\n" - -#~ msgid "use of non-array as array" -#~ msgstr "配列でないものを配列として使用しています" - #~ msgid "can't use function name `%s' as variable or array" #~ msgstr "関数名 `%s' は変数または配列として使用出来ません" +#~ msgid "assignment is not allowed to result of builtin function" +#~ msgstr "組込関数の戻り値への代入は許可されていません" + #~ msgid "assignment used in conditional context" #~ msgstr "条件コンテキスト内で代入が使用されました" @@ -3620,11 +3573,20 @@ msgstr "" #~ msgid "Sorry, don't know how to interpret `%s'" #~ msgstr "申し訳ありませんが `%s' をどのように解釈するか分かりません" +#~ msgid "Operation Not Supported" +#~ msgstr "この操作はサポートされていません" + +#~ msgid "`-m[fr]' option irrelevant in gawk" +#~ msgstr "gawk ではオプション `-m[fr]' に効果はありません。" + +#~ msgid "-m option usage: `-m[fr] nnn'" +#~ msgstr "-m オプションの使用法: `-m[fr] 数値'" + #~ msgid "\t-R file\t\t\t--command=file\n" #~ msgstr "\t-R file\t\t\t--command=file\n" #~ msgid "could not find groups: %s" #~ msgstr "グループが見つかりません: %s" -#~ msgid "assignment is not allowed to result of builtin function" -#~ msgstr "組込関数の戻り値への代入は許可されていません" +#~ msgid "range of the form `[%c-%c]' is locale dependant" +#~ msgstr "`[%c-%c]' 形式の範囲はロケール依存です" @@ -26,6 +26,7 @@ #include "awk.h" static void pprint(INSTRUCTION *startp, INSTRUCTION *endp, bool in_for_header); +static void end_line(INSTRUCTION *ip); static void pp_parenthesize(NODE *n); static void parenthesize(int type, NODE *left, NODE *right); static char *pp_list(int nargs, const char *paren, const char *delim); @@ -176,70 +177,80 @@ pprint(INSTRUCTION *startp, INSTRUCTION *endp, bool in_for_header) NODE *t1; char *str; NODE *t2; - INSTRUCTION *ip; + INSTRUCTION *ip1; + INSTRUCTION *ip2; NODE *m; char *tmp; int rule; - long lind; static int rule_count[MAXRULE]; for (pc = startp; pc != endp; pc = pc->nexti) { if (pc->source_line > 0) sourceline = pc->source_line; + /* skip leading EOL comment as it has already been printed */ + if (pc->opcode == Op_comment + && pc->memory->comment_type == EOL_COMMENT) + continue; switch (pc->opcode) { case Op_rule: + /* + * Rules are three instructions long. + * See append_rule in awkgram.y. + * The first has the Rule Op Code, nexti etc. + * The second, (pc + 1) has firsti and lasti: + * the first/last ACTION instructions for this rule. + * The third has first_line and last_line: + * the first and last source line numbers. + */ source = pc->source_file; rule = pc->in_rule; if (rule != Rule) { - ip = (pc + 1)->firsti; - - /* print pre-begin/end comments */ - if (ip->opcode == Op_comment) { - print_comment(ip, 0); - ip = ip->nexti; - } + /* Allow for pre-non-rule-block comment */ + if (pc->nexti != (pc +1)->firsti + && pc->nexti->opcode == Op_comment + && pc->nexti->memory->comment_type == FULL_COMMENT) + print_comment(pc->nexti, -1); + ip1 = (pc + 1)->firsti; + ip2 = (pc + 1)->lasti; if (do_profile) { if (! rule_count[rule]++) fprintf(prof_fp, _("\t# %s rule(s)\n\n"), ruletab[rule]); indent(0); } - fprintf(prof_fp, "%s {\n", ruletab[rule]); + fprintf(prof_fp, "%s {", ruletab[rule]); + end_line(pc); } else { if (do_profile && ! rule_count[rule]++) fprintf(prof_fp, _("\t# Rule(s)\n\n")); - ip = pc->nexti; - lind = ip->exec_count; - /* print pre-block comments */ - if (ip->opcode == Op_exec_count && ip->nexti->opcode == Op_comment) - ip = ip->nexti; - if (ip->opcode == Op_comment) { - print_comment(ip, lind); - if (ip->nexti->nexti == (pc + 1)->firsti) - ip = ip->nexti->nexti; - } - if (ip != (pc + 1)->firsti) { /* non-empty pattern */ - indent(lind); - pprint(ip->nexti, (pc + 1)->firsti, false); - t1 = pp_pop(); - fprintf(prof_fp, "%s {", t1->pp_str); - pp_free(t1); - ip = (pc + 1)->firsti; - - if (do_profile && ip->exec_count > 0) - fprintf(prof_fp, " # %ld", ip->exec_count); - - fprintf(prof_fp, "\n"); + ip1 = pc->nexti; + if (ip1 != (pc + 1)->firsti) { /* non-empty pattern */ + pprint(ip1->nexti, (pc + 1)->firsti, false); + /* Allow for case where the "pattern" is just a comment */ + if (ip1->nexti->nexti->nexti != (pc +1)->firsti + || ip1->nexti->opcode != Op_comment) { + t1 = pp_pop(); + fprintf(prof_fp, "%s {", t1->pp_str); + pp_free(t1); + } else + fprintf(prof_fp, "{"); + ip1 = (pc + 1)->firsti; + ip2 = (pc + 1)->lasti; + + if (do_profile && ip1->exec_count > 0) + fprintf(prof_fp, " # %ld", ip1->exec_count); + + end_line(ip1); } else { fprintf(prof_fp, "{\n"); - ip = (pc + 1)->firsti; + ip1 = (pc + 1)->firsti; } - ip = ip->nexti; + ip1 = ip1->nexti; } indent_in(); - pprint(ip, (pc + 1)->lasti, false); + pprint(ip1, ip2, false); indent_out(); if (do_profile) indent(0); @@ -328,7 +339,7 @@ cleanup: pp_free(t2); pp_free(t1); if (! in_for_header) - fprintf(prof_fp, "\n"); + end_line(pc); break; default: @@ -454,7 +465,7 @@ cleanup: pp_free(t2); pp_free(t1); if (! in_for_header) - fprintf(prof_fp, "\n"); + end_line(pc); break; case Op_concat: @@ -475,7 +486,7 @@ cleanup: } else fprintf(prof_fp, "%s %s", op2str(Op_K_delete), array); if (! in_for_header) - fprintf(prof_fp, "\n"); + end_line(pc); pp_free(t1); } break; @@ -587,7 +598,7 @@ cleanup: fprintf(prof_fp, "%s%s", op2str(pc->opcode), tmp); efree(tmp); if (! in_for_header) - fprintf(prof_fp, "\n"); + end_line(pc); break; case Op_push_re: @@ -705,33 +716,33 @@ cleanup: t1 = pp_pop(); fprintf(prof_fp, "%s", t1->pp_str); if (! in_for_header) - fprintf(prof_fp, "\n"); + end_line(pc); pp_free(t1); break; case Op_line_range: - ip = pc + 1; - pprint(pc->nexti, ip->condpair_left, false); - pprint(ip->condpair_left->nexti, ip->condpair_right, false); + ip1 = pc + 1; + pprint(pc->nexti, ip1->condpair_left, false); + pprint(ip1->condpair_left->nexti, ip1->condpair_right, false); t2 = pp_pop(); t1 = pp_pop(); str = pp_group3(t1->pp_str, ", ", t2->pp_str); pp_free(t1); pp_free(t2); pp_push(Op_line_range, str, CAN_FREE); - pc = ip->condpair_right; + pc = ip1->condpair_right; break; case Op_K_while: - ip = pc + 1; - indent(ip->while_body->exec_count); + ip1 = pc + 1; + indent(ip1->while_body->exec_count); fprintf(prof_fp, "%s (", op2str(pc->opcode)); - pprint(pc->nexti, ip->while_body, false); + pprint(pc->nexti, ip1->while_body, false); t1 = pp_pop(); fprintf(prof_fp, "%s) {\n", t1->pp_str); pp_free(t1); indent_in(); - pprint(ip->while_body->nexti, pc->target_break, false); + pprint(ip1->while_body->nexti, pc->target_break, false); indent_out(); indent(SPACEOVER); fprintf(prof_fp, "}\n"); @@ -739,13 +750,13 @@ cleanup: break; case Op_K_do: - ip = pc + 1; + ip1 = pc + 1; indent(pc->nexti->exec_count); fprintf(prof_fp, "%s {\n", op2str(pc->opcode)); indent_in(); - pprint(pc->nexti->nexti, ip->doloop_cond, false); + pprint(pc->nexti->nexti, ip1->doloop_cond, false); indent_out(); - pprint(ip->doloop_cond, pc->target_break, false); + pprint(ip1->doloop_cond, pc->target_break, false); indent(SPACEOVER); t1 = pp_pop(); fprintf(prof_fp, "} %s (%s)\n", op2str(Op_K_while), t1->pp_str); @@ -754,24 +765,24 @@ cleanup: break; case Op_K_for: - ip = pc + 1; - indent(ip->forloop_body->exec_count); + ip1 = pc + 1; + indent(ip1->forloop_body->exec_count); fprintf(prof_fp, "%s (", op2str(pc->opcode)); /* If empty for looop header, print it a little more nicely. */ if ( pc->nexti->opcode == Op_no_op - && ip->forloop_cond == pc->nexti + && ip1->forloop_cond == pc->nexti && pc->target_continue->opcode == Op_jmp) { fprintf(prof_fp, ";;"); } else { - pprint(pc->nexti, ip->forloop_cond, true); + pprint(pc->nexti, ip1->forloop_cond, true); fprintf(prof_fp, "; "); - if (ip->forloop_cond->opcode == Op_no_op && - ip->forloop_cond->nexti == ip->forloop_body) + if (ip1->forloop_cond->opcode == Op_no_op && + ip1->forloop_cond->nexti == ip1->forloop_body) fprintf(prof_fp, "; "); else { - pprint(ip->forloop_cond, ip->forloop_body, true); + pprint(ip1->forloop_cond, ip1->forloop_body, true); t1 = pp_pop(); fprintf(prof_fp, "%s; ", t1->pp_str); pp_free(t1); @@ -781,7 +792,7 @@ cleanup: } fprintf(prof_fp, ") {\n"); indent_in(); - pprint(ip->forloop_body->nexti, pc->target_continue, false); + pprint(ip1->forloop_body->nexti, pc->target_continue, false); indent_out(); indent(SPACEOVER); fprintf(prof_fp, "}\n"); @@ -793,20 +804,20 @@ cleanup: char *array; const char *item; - ip = pc + 1; + ip1 = pc + 1; t1 = pp_pop(); array = t1->pp_str; - m = ip->forloop_cond->array_var; + m = ip1->forloop_cond->array_var; if (m->type == Node_param_list) item = func_params[m->param_cnt].param; else item = m->vname; - indent(ip->forloop_body->exec_count); + indent(ip1->forloop_body->exec_count); fprintf(prof_fp, "%s (%s%s%s) {\n", op2str(Op_K_arrayfor), item, op2str(Op_in_array), array); indent_in(); pp_free(t1); - pprint(ip->forloop_body->nexti, pc->target_break, false); + pprint(ip1->forloop_body->nexti, pc->target_break, false); indent_out(); indent(SPACEOVER); fprintf(prof_fp, "}\n"); @@ -815,13 +826,13 @@ cleanup: break; case Op_K_switch: - ip = pc + 1; + ip1 = pc + 1; fprintf(prof_fp, "%s (", op2str(pc->opcode)); - pprint(pc->nexti, ip->switch_start, false); + pprint(pc->nexti, ip1->switch_start, false); t1 = pp_pop(); fprintf(prof_fp, "%s) {\n", t1->pp_str); pp_free(t1); - pprint(ip->switch_start, ip->switch_end, false); + pprint(ip1->switch_start, ip1->switch_end, false); indent(SPACEOVER); fprintf(prof_fp, "}\n"); pc = pc->target_break; @@ -848,12 +859,12 @@ cleanup: fprintf(prof_fp, "%s) {", t1->pp_str); pp_free(t1); - ip = pc->branch_if; - if (ip->exec_count > 0) - fprintf(prof_fp, " # %ld", ip->exec_count); - fprintf(prof_fp, "\n"); + ip1 = pc->branch_if; + if (ip1->exec_count > 0) + fprintf(prof_fp, " # %ld", ip1->exec_count); + end_line(pc); indent_in(); - pprint(ip->nexti, pc->branch_else, false); + pprint(ip1->nexti, pc->branch_else, false); indent_out(); pc = pc->branch_else; if (pc->nexti->opcode == Op_no_op) { @@ -878,11 +889,11 @@ cleanup: size_t len; pprint(pc->nexti, pc->branch_if, false); - ip = pc->branch_if; - pprint(ip->nexti, pc->branch_else, false); - ip = pc->branch_else->nexti; + ip1 = pc->branch_if; + pprint(ip1->nexti, pc->branch_else, false); + ip1 = pc->branch_else->nexti; - pc = ip->nexti; + pc = ip1->nexti; assert(pc->opcode == Op_cond_exp); pprint(pc->nexti, pc->branch_end, false); @@ -923,6 +934,21 @@ cleanup: } } +/* end_line --- end pretty print line with new line or on-line comment */ + +void +end_line(INSTRUCTION *ip) +{ + if (ip->nexti->opcode == Op_comment + && ip->nexti->memory->comment_type == EOL_COMMENT) { + fprintf(prof_fp, "\t"); + print_comment(ip->nexti, -1); + ip = ip->nexti->nexti; + } + else + fprintf(prof_fp, "\n"); +} + /* pp_string_fp --- printy print a string to the fp */ /* @@ -1008,7 +1034,8 @@ print_comment(INSTRUCTION* pc, long in) count = pc->memory->stlen; text = pc->memory->stptr; - indent(in); /* is this correct? Where should comments go? */ + if (in >= 0) + indent(in); /* is this correct? Where should comments go? */ for (; count > 0; count--, text++) { if (after_newline) { indent(in); @@ -1586,7 +1613,7 @@ pp_func(INSTRUCTION *pc, void *data ATTRIBUTE_UNUSED) /* print any function comment */ if (fp->opcode == Op_comment && fp->source_line == 0) { - print_comment(fp, 0); + print_comment(fp, -1); /* -1 ==> don't indent */ fp = fp->nexti; } @@ -54,12 +54,9 @@ make_regexp(const char *s, size_t len, bool ignorecase, bool dfa, bool canfatal) * It is 0, when the current character is a singlebyte character. */ size_t is_multibyte = 0; -#if MBS_SUPPORT mbstate_t mbs; - if (gawk_mb_cur_max > 1) - memset(&mbs, 0, sizeof(mbstate_t)); /* Initialize. */ -#endif + memset(&mbs, 0, sizeof(mbstate_t)); /* Initialize. */ if (first) { first = false; @@ -87,7 +84,6 @@ make_regexp(const char *s, size_t len, bool ignorecase, bool dfa, bool canfatal) dest = buf; while (src < end) { -#if MBS_SUPPORT if (gawk_mb_cur_max > 1 && ! is_multibyte) { /* The previous byte is a singlebyte character, or last byte of a multibyte character. We check the next character. */ @@ -100,7 +96,6 @@ make_regexp(const char *s, size_t len, bool ignorecase, bool dfa, bool canfatal) is_multibyte = 0; } } -#endif /* We skip multibyte character, since it must not be a special character. */ diff --git a/regex_internal.h b/regex_internal.h index c8981a08..3fc2fc58 100644 --- a/regex_internal.h +++ b/regex_internal.h @@ -26,18 +26,16 @@ #include <stdlib.h> #include <string.h> -#include "mbsupport.h" /* gawk */ - #if defined HAVE_LANGINFO_H || defined HAVE_LANGINFO_CODESET || defined _LIBC # include <langinfo.h> #endif #if defined HAVE_LOCALE_H || defined _LIBC # include <locale.h> #endif -#if MBS_SUPPORT && (defined HAVE_WCHAR_H || defined _LIBC) +#if defined HAVE_WCHAR_H || defined _LIBC # include <wchar.h> #endif /* HAVE_WCHAR_H || _LIBC */ -#if MBS_SUPPORT && (defined HAVE_WCTYPE_H || defined _LIBC) +#if defined HAVE_WCTYPE_H || defined _LIBC # include <wctype.h> #endif /* HAVE_WCTYPE_H || _LIBC */ #if defined HAVE_STDBOOL_H || defined _LIBC @@ -109,7 +107,7 @@ is_blank (int c) # define SIZE_MAX ((size_t) -1) #endif -#if MBS_SUPPORT || _LIBC +#if ! defined(__DJGPP__) && (defined(GAWK) || _LIBC) # define RE_ENABLE_I18N #endif @@ -111,6 +111,6 @@ #include "missing_d/strcoll.c" #endif -#if ! MBS_SUPPORT +#if defined(__DJGPP__) #include "missing_d/wcmisc.c" #endif diff --git a/test/ChangeLog b/test/ChangeLog index b6d60d97..5e6b2c13 100644 --- a/test/ChangeLog +++ b/test/ChangeLog @@ -1,3 +1,26 @@ +2014-12-12 Arnold D. Robbins <arnold@skeeve.com> + + * profile5.ok: Updated after code changes. + +2014-11-26 Arnold D. Robbins <arnold@skeeve.com> + + * Gentests: Fix gensub call after adding warning. + +2014-11-26 Arnold D. Robbins <arnold@skeeve.com> + + * gensub2.ok: Update after code changes. + +2014-11-16 Arnold D. Robbins <arnold@skeeve.com> + + * Makefile.am (sortglos): New test. + * sortglos.awk, sortglos.in, sortglos.ok: New files. + Thanks to Antonio Columbo. + +2014-11-09 Arnold D. Robbins <arnold@skeeve.com> + + * mbprintf4.awk: Add record and line number for debugging. + * mpprint4.ok: Adjust. + 2014-11-06 Andrew J. Schorr <aschorr@telemetry-investments.com> * testext.ok: Add results from new test_get_file test. diff --git a/test/Gentests b/test/Gentests index 460edbae..5a7aaa09 100755 --- a/test/Gentests +++ b/test/Gentests @@ -123,7 +123,7 @@ END { printf "WARNING: --lint-old target `%s' is missing.\n", x > "/dev/stderr" for (x in files) if (!(x in unused) && \ - !(gensub(/\.(awk|in)$/,"","",x) in targets)) + !(gensub(/\.(awk|in)$/,"",1,x) in targets)) printf "WARNING: unused file `%s'.\n", x > "/dev/stderr" } diff --git a/test/Makefile.am b/test/Makefile.am index db1cb086..a00e011e 100644 --- a/test/Makefile.am +++ b/test/Makefile.am @@ -833,6 +833,9 @@ EXTRA_DIST = \ sortfor.awk \ sortfor.in \ sortfor.ok \ + sortglos.awk \ + sortglos.in \ + sortglos.ok \ sortu.awk \ sortu.ok \ space.ok \ @@ -998,7 +1001,7 @@ BASIC_TESTS = \ rand randtest range1 rebt8b1 redfilnm regeq regexprange regrange reindops \ reparse resplit rri1 rs rsnul1nl rsnulbig rsnulbig2 rstest1 rstest2 \ rstest3 rstest4 rstest5 rswhite \ - scalar sclforin sclifin sortempty splitargv splitarr splitdef \ + scalar sclforin sclifin sortempty sortglos splitargv splitarr splitdef \ splitvar splitwht strcat1 strnum1 strtod subamp subi18n \ subsepnm subslash substr swaplns synerr1 synerr2 tradanch tweakfld \ uninit2 uninit3 uninit4 uninit5 uninitialized unterm uparrfs \ diff --git a/test/Makefile.in b/test/Makefile.in index 7214b707..93a989b5 100644 --- a/test/Makefile.in +++ b/test/Makefile.in @@ -205,6 +205,7 @@ PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ POSUB = @POSUB@ +SED = @SED@ SET_MAKE = @SET_MAKE@ SHELL = @SHELL@ SOCKET_LIBS = @SOCKET_LIBS@ @@ -1079,6 +1080,9 @@ EXTRA_DIST = \ sortfor.awk \ sortfor.in \ sortfor.ok \ + sortglos.awk \ + sortglos.in \ + sortglos.ok \ sortu.awk \ sortu.ok \ space.ok \ @@ -1243,7 +1247,7 @@ BASIC_TESTS = \ rand randtest range1 rebt8b1 redfilnm regeq regexprange regrange reindops \ reparse resplit rri1 rs rsnul1nl rsnulbig rsnulbig2 rstest1 rstest2 \ rstest3 rstest4 rstest5 rswhite \ - scalar sclforin sclifin sortempty splitargv splitarr splitdef \ + scalar sclforin sclifin sortempty sortglos splitargv splitarr splitdef \ splitvar splitwht strcat1 strnum1 strtod subamp subi18n \ subsepnm subslash substr swaplns synerr1 synerr2 tradanch tweakfld \ uninit2 uninit3 uninit4 uninit5 uninitialized unterm uparrfs \ @@ -3201,6 +3205,11 @@ sortempty: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +sortglos: + @echo $@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + splitargv: @echo $@ @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ diff --git a/test/Maketests b/test/Maketests index f8d5e8a9..85c13d5d 100644 --- a/test/Maketests +++ b/test/Maketests @@ -777,6 +777,11 @@ sortempty: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +sortglos: + @echo $@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + splitargv: @echo $@ @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ diff --git a/test/gensub2.ok b/test/gensub2.ok index 89824140..318f940c 100644 --- a/test/gensub2.ok +++ b/test/gensub2.ok @@ -1,3 +1,4 @@ xy xy +gawk: gensub2.awk:4: warning: gensub: third argument `a' treated as 1 yx diff --git a/test/mbprintf4.awk b/test/mbprintf4.awk index a4b2a218..1e436bca 100644 --- a/test/mbprintf4.awk +++ b/test/mbprintf4.awk @@ -1,32 +1,35 @@ # printf with multi-byte text encoding, %c and %s, width and precision, and left-alignment. { - print "printf %c " $0 - printf "|%c|\n", $0 - printf "|%1c|\n", $0 - printf "|%3c|\n", $0 + count = 1 + + print NR, count++, "printf %c " $0 + printf "%d:%d: |%c|\n", NR, count++, $0 + printf "%d:%d: |%1c|\n", NR, count++, $0 + printf "%d:%d: |%3c|\n", NR, count++, $0 # precision is ignored by %c. - printf "|%3.1c|\n", $0 - printf "|%3.5c|\n", $0 - print "printf %-c " $0 - printf "|%-c|\n", $0 - printf "|%-1c|\n", $0 - printf "|%-3c|\n", $0 + printf "%d:%d: |%3.1c|\n", NR, count++, $0 + printf "%d:%d: |%3.5c|\n", NR, count++, $0 + print NR, count++, "printf %-c " $0 + printf "%d:%d: |%-c|\n", NR, count++, $0 + printf "%d:%d: |%-1c|\n", NR, count++, $0 + printf "%d:%d: |%-3c|\n", NR, count++, $0 # precision is ignored by %c. - printf "|%-3.1c|\n", $0 - printf "|%-3.5c|\n", $0 + printf "%d:%d: |%-3.1c|\n", NR, count++, $0 + printf "%d:%d: |%-3.5c|\n", NR, count++, $0 printf ORS - print "printf %s " $0 - printf "|%s|\n", $0 - printf "|%1s|\n", $0 - printf "|%3s|\n", $0 - printf "|%3.1s|\n", $0 - printf "|%3.5s|\n", $0 - print "printf %-s " $0 - printf "|%-s|\n", $0 - printf "|%-1s|\n", $0 - printf "|%-3s|\n", $0 - printf "|%-3.1s|\n", $0 - printf "|%-3.5s|\n", $0 + print NR, count++, "printf %s " $0 + printf "%d:%d: |%s|\n", NR, count++, $0 + printf "%d:%d: |%1s|\n", NR, count++, $0 + printf "%d:%d: |%3s|\n", NR, count++, $0 + printf "%d:%d: |%3.1s|\n", NR, count++, $0 + printf "%d:%d: |%3.5s|\n", NR, count++, $0 + + print NR, count++, "printf %-s " $0 + printf "%d:%d: |%-s|\n", NR, count++, $0 + printf "%d:%d: |%-1s|\n", NR, count++, $0 + printf "%d:%d: |%-3s|\n", NR, count++, $0 + printf "%d:%d: |%-3.1s|\n", NR, count++, $0 + printf "%d:%d: |%-3.5s|\n", NR, count++, $0 printf ORS ORS } diff --git a/test/mbprintf4.ok b/test/mbprintf4.ok index 9b9dd4e2..e32fe408 100644 --- a/test/mbprintf4.ok +++ b/test/mbprintf4.ok @@ -1,81 +1,81 @@ -printf %c ú -|ú| -|ú| -| ú| -| ú| -| ú| -printf %-c ú -|ú| -|ú| -|ú | -|ú | -|ú | +1 1 printf %c ú +1:2: |ú| +1:3: |ú| +1:4: | ú| +1:5: | ú| +1:6: | ú| +1 7 printf %-c ú +1:8: |ú| +1:9: |ú| +1:10: |ú | +1:11: |ú | +1:12: |ú | -printf %s ú -|ú| -|ú| -| ú| -| ú| -| ú| -printf %-s ú -|ú| -|ú| -|ú | -|ú | -|ú | +1 13 printf %s ú +1:14: |ú| +1:15: |ú| +1:16: | ú| +1:17: | ú| +1:18: | ú| +1 19 printf %-s ú +1:20: |ú| +1:21: |ú| +1:22: |ú | +1:23: |ú | +1:24: |ú | -printf %c último -|ú| -|ú| -| ú| -| ú| -| ú| -printf %-c último -|ú| -|ú| -|ú | -|ú | -|ú | +2 1 printf %c último +2:2: |ú| +2:3: |ú| +2:4: | ú| +2:5: | ú| +2:6: | ú| +2 7 printf %-c último +2:8: |ú| +2:9: |ú| +2:10: |ú | +2:11: |ú | +2:12: |ú | -printf %s último -|último| -|último| -|último| -| ú| -|últim| -printf %-s último -|último| -|último| -|último| -|ú | -|últim| +2 13 printf %s último +2:14: |último| +2:15: |último| +2:16: |último| +2:17: | ú| +2:18: |últim| +2 19 printf %-s último +2:20: |último| +2:21: |último| +2:22: |último| +2:23: |ú | +2:24: |últim| -printf %c áé -|á| -|á| -| á| -| á| -| á| -printf %-c áé -|á| -|á| -|á | -|á | -|á | +3 1 printf %c áé +3:2: |á| +3:3: |á| +3:4: | á| +3:5: | á| +3:6: | á| +3 7 printf %-c áé +3:8: |á| +3:9: |á| +3:10: |á | +3:11: |á | +3:12: |á | -printf %s áé -|áé| -|áé| -| áé| -| á| -| áé| -printf %-s áé -|áé| -|áé| -|áé | -|á | -|áé | +3 13 printf %s áé +3:14: |áé| +3:15: |áé| +3:16: | áé| +3:17: | á| +3:18: | áé| +3 19 printf %-s áé +3:20: |áé| +3:21: |áé| +3:22: |áé | +3:23: |á | +3:24: |áé | diff --git a/test/profile5.ok b/test/profile5.ok index 4c944627..5bf04dcf 100644 --- a/test/profile5.ok +++ b/test/profile5.ok @@ -2,8 +2,7 @@ BEGIN { _addlib("_BASE") } -############################################################################ - +#___________________________________________________________________________________ BEGIN { BINMODE = "rw" SUBSEP = "\000" @@ -24,8 +23,7 @@ BEGIN { _addlib("_INSTRUC") } -############################################################################# - +#___________________________________________________________________________________ BEGIN { _delay_perfmsdelay = 11500 } @@ -38,19 +36,11 @@ BEGIN { BEGIN { } -########################################################################### - - - - - - -BEGIN { +BEGIN { ########################################################################### _addlib("_EXTFN") } -############################################################################# - +#___________________________________________________________________________________ BEGIN { delete _XCHR delete _ASC @@ -78,7 +68,6 @@ BEGIN { _QSTR[_CHR[i]] = _QSTRQ[_CHR[i]] } _QSTR["\\"] = "\\\\" - #; _QSTR["\""]="\\\"" #_____________________________________________________________________________ _CHR["CR"] = "\r" @@ -117,8 +106,7 @@ BEGIN { _addlib("_SYSIO") } -############################################################################# - +#___________________________________________________________________________________ BEGIN { _SYS_STDCON = "CON" _CON_WIDTH = (match(_cmd("MODE " _SYS_STDCON " 2>NUL"), /Columns:[ \t]*([0-9]+)/, A) ? strtonum(A[1]) : 80) @@ -128,8 +116,7 @@ BEGIN { _addlib("_FILEIO") } -############################################################################# - +#___________________________________________________________________________________ BEGIN { if (_SYS_STDOUT == "") { _SYS_STDOUT = "/dev/stdout" @@ -151,7 +138,7 @@ BEGIN { _addlib("_tOBJ") } -############################################################################# +#___________________________________________________________________________________ BEGIN { _tInBy = "\212._tInBy" _tgenuid_init() @@ -183,8 +170,7 @@ BEGIN { _addlib("_ERRLOG") } -############################################################################# - +#___________________________________________________________________________________ BEGIN { if (_gawk_scriptlevel < 1) { _ERRLOG_TF = 1 @@ -206,11 +192,7 @@ BEGIN { _shortcut_init() } -######################################################### - - - -BEGIN { +BEGIN { ######################################################### _addlib("_eXTFN") } @@ -219,10 +201,7 @@ BEGIN { _extfn_init() } -############################################################ - - -BEGIN { +BEGIN { ############################################################ _addlib("_sHARE") } @@ -231,9 +210,7 @@ BEGIN { } BEGIN { - _addlib("_DS") - ############################################################################### - + _addlib("_DS") ############################################################################### _PRODUCT_NAME = "Deployment Solution Control" _PRODUCT_VERSION = "1.0" _PRODUCT_COPYRIGHT = "Copyright (C) 2013 by CosumoGEN" @@ -300,7 +277,29 @@ BEGIN { _initsys() } -############################################################################ +#_________________________________________________________________________________________ +########################################################################################## + + + + + + + +#BootDevice BuildNumber BuildType Caption CodeSet CountryCode CreationClassName CSCreationClassName CSDVersion CSName CurrentTimeZone DataExecutionPrevention_32BitApplications DataExecutionPrevention_Available DataExecutionPrevention_Drivers DataExecutionPrevention_SupportPolicy Debug Description Distributed EncryptionLevel ForegroundApplicationBoost FreePhysicalMemory FreeSpaceInPagingFiles FreeVirtualMemory InstallDate LargeSystemCache LastBootUpTime LocalDateTime Locale Manufacturer MaxNumberOfProcesses MaxProcessMemorySize MUILanguages Name NumberOfLicensedUsers NumberOfProcesses NumberOfUsers OperatingSystemSKU Organization OSArchitecture OSLanguage OSProductSuite OSType OtherTypeDescription PAEEnabled PlusProductID PlusVersionNumber Primary ProductType RegisteredUser SerialNumber ServicePackMajorVersion ServicePackMinorVersion SizeStoredInPagingFiles Status SuiteMask SystemDevice SystemDirectory SystemDrive TotalSwapSpaceSize TotalVirtualMemorySize TotalVisibleMemorySize Version WindowsDirectory +#\Device\HarddiskVolume1 7601 Multiprocessor Free Microsoft Windows Server 2008 R2 Enterprise 1252 1 Win32_OperatingSystem Win32_ComputerSystem Service Pack 1 CPU 180 TRUE TRUE TRUE 3 FALSE FALSE 256 0 6925316 33518716 41134632 20110502192745.000000+180 20130426120425.497469+180 20130510134606.932000+180 0409 Microsoft Corporation -1 8589934464 {"en-US"} Microsoft Windows Server 2008 R2 Enterprise |C:\Windows|\Device\Harddisk0\Partition2 0 116 2 10 64-bit 1033 274 18 TRUE 3 Windows User 55041-507-2389175-84833 1 0 33554432 OK 274 \Device\HarddiskVolume2 C:\Windows\system32 C: 50311020 16758448 6.1.7601 C:\Windows + + + + + + + + + + + + BEGIN { a = ENVIRON["EGAWK_CMDLINE"] @@ -321,13 +320,43 @@ BEGIN { _END() } -######################################################################## - +#_____________________________________________________________________________ END { _EXIT() } -############################################################################### +#_______________________________________________________________________ +######################################################################## + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + END { if (_gawk_scriptlevel < 1) { @@ -339,8 +368,17 @@ END { } } -############################################################################### - +########################################################################################## +# PUBLIC: +#_____________________________________________________________________________ +# _rFBRO(ptr) - Return ptr of first-bro. [TESTED] +# If !ptr then returns "". +#_____________________________________________________________________________ +# _rLBRO(ptr) - Return ptr of last-bro. [TESTED] +# If !ptr then returns "". +#_____________________________________________________________________________ +# _rQBRO(ptr) - Returns brothers total quantity. [TESTED] +# If !ptr then returns "". END { if (_gawk_scriptlevel < 1) { if (! _fileio_notdeltmpflag) { @@ -350,7 +388,297 @@ END { } } -############################################################################### +#___________________________________________________________________________________ +#################################################################################### + + + + + + + + + + + + + + + + +#___________________________________________________________________________________ +# fn _dirtree(array,pathmask) +# +# Return in `array' file tree from pathmask: +# array["file.filerdne"]="size date time" +# array["subdir.filerd"]["file.filerdne"]="size date time" +# array["subdir.filerd"]["file.filerd"][...] +# +# The array will be cleared before any action. Function return pathmask w/o ltabspc and rtabspc. +#___________________________________________________________________________________ + + + + + +# OK: change internal function's names to: w\o "_" +# OK: FLENGTH: should cover r-spcs +# OK: optimize REXP +# OK: add new symbols to dir/file names ( ! and + ) +# OK: create _getfilepath() +# OK: del - conflict with WROOTDIR (do not update it) +# OK: dir/del - support for filemask ( * and ? ) +# OK: how to define code injections: header\ender; and HANDLERS +# OK: units in header\ender? conline division... +# OK: _FILEPATH problem: it will not been defined at the moment when subscript0 starts - at the start TMPRD="_tmp" +# OK: del: if del("dir\\") - then all ok except it NOT deleted "dir\\" - _del function removed(renamed to __del) +# OK: tmpdirs: it delete only autotmp dir and only from script0 +# OK: MICROTEST: global testing of filepath (UNC! CORRECT RESULTS! ) +# question about cache: did new just now generated absolute filepath cached in FILECACHE? its seems like NO +# check _untmp: CONFLICT: if file or dir from autotmp dir will be untmp then it anyway will be deleted; but file or dir from other point never be deleted anyway - so what is the point of untmp????? +#ERRLOG: _setmpath: warning!!!!! + +#___________________________________________________________________________________ +#################################################################################### +# PUBLIC: +#___________________________________________________________________________________ +# +# fn _rdfile(_filepath) +# +# Read and return data from file specified in _filepath. +# If _filepath=="" then no action occured and return "". +# Function read and return data from file. No any changes in data occured. +# Function use _filerdne function internally. If some syntax error +# found in _filepath then function return "". +# If some error occured while reading data from file then fuction return "" +# and error-text is in ERRNO(and no close-file action will be occured!). +# If reading data completed successfully then function try to close +# file and if while closing file some error occured then function +# returns "" and error-text is in ERRNO. +# Otherwise function returns readed data. +#_____________________________________________________________________________ +# +# fn _wrfile(_filepath,_data) +# +# Write data into file specified in _filepath. +# If _filepath=="" then no action occured and return "". +# Function write _data to file. No any changes in data occured. +# Function use _filerdne function internally. If some syntax error +# found in _filepath then function return "". +# If some error occured while writing data to file then fuction return "" +# and error-text is in ERRNO(and no close-file action will be occured!). +# If writing data completed successfully then function try to close +# file and if while closing file some error occured then function +# returns "" and error-text is in ERRNO. +# Otherwise function returns _filepath(re-processed). +#___________________________________________________________________________________ +# +# fn _filepath(_filepath) +# +# Return re-processed root-dir-name-ext of _filepath. +# If _filepath=="" then no action occured and return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +#_____________________________________________________________________________ +# +# fn _filerdne(_filepath) +# +# Return re-processed root-dir-filename of _filepath. +# If _filepath=="" then no action occured and return "". +# Function return result only if in _filepath present file-name(name +# and/or extension) - otherwise its return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +#_____________________________________________________________________________ +# +# fn _filerdn(_filepath) +# +# Return re-processed root-dir-name of _filepath. +# If _filepath=="" then no action occured and return "". +# Function return result only if in _filepath present name field - +# - otherwise its return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +#_____________________________________________________________________________ +# +# fn _filerd(_filepath) +# +# Return re-processed root-dir of _filepath. +# If _filepath=="" then no action occured and return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +#_____________________________________________________________________________ +# +# fn _filer(_filepath) +# +# Return re-processed root of _filepath. +# If _filepath=="" then no action occured and return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +#_____________________________________________________________________________ +# +# fn _filed(_filepath) +# +# Return re-processed dir of _filepath. +# If _filepath=="" then no action occured and return "". +# There is only one case when dir string can be =="" - when in +# _filepath specified unmounted drive(MS-format) and from- +# current-location address used(like Z:file.ext). In this +# case no rootdir-cache-record will be created. +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +#_____________________________________________________________________________ +# fn _filene(_filepath) +# +# Return re-processed name-ext of _filepath. +# If _filepath=="" then no action occured and return "". +# Function return result only if in _filepath present file-name(name +# and/or extension) - otherwise its return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +#_____________________________________________________________________________ +# +# fn _filen(_filepath) +# +# Return re-processed name of _filepath. +# If _filepath=="" then no action occured and return "". +# Function return result only if in _filepath present name field - +# - otherwise its return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +#_____________________________________________________________________________ +# +# fn _file(_filepath) +# +# Return re-processed ext of _filepath. +# If _filepath=="" then no action occured and return "". +# Function return result only if in _filepath present ext field - +# - otherwise its return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +#___________________________________________________________________________________ +# +# fn _dir(_ARR,_filepathmask) +# +# Get file-/folder-list of root-folder of _filepathmask. +# If _filepathmask=="" then no action occured and return "". +# _filepathmask can contain symbols like `*' and `?' as like +# its used in `dir'-shell command. +# Function gets file-/folder-list of specified root-dir-_filepathmask +# and return this list in array _ARR - where each element: +# +# index - is the _filepath of file-or-folder name-ext +# value - contains 3 fields separated by " ": +# 1. =="D" if this is folder +# ==/[0-9]+/ if this is file - size of file in bytes +# 2. ==date-of-creation of file or folder +# 3. ==time-of-creation of file or folder +# +# Function returns quantity of items in ARR. +#___________________________________________________________________________________ +# +# fn _filexist(_filepath) +# +# Test if file or path or drive specified in _filepath is exist. +# If _filepath=="" then no action occured and return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +# Function returns _filepath if _filepath is exist. Otherwise +# function return 0. +#_____________________________________________________________________________ +# +# fn _filenotexist(_filepath) +# +# Test if file or path or drive specified in _filepath is not exist. +# If _filepath=="" then no action occured and return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +# Function returns 1 if _filepath is not exist. Otherwise function +# return 0. +#_____________________________________________________________________________ +# +# fn _newdir(_filepath) +# +# Create path specified in root-dir-_filepath. +# If _filepath=="" then no action occured and return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +# Function returns root-dir of _filepath. +#_______________________________________________________________________ +# +# fn _newdir(_filepath) +# +# Create path specified in root-dir-_filepath. If this folder +# already exist then it will be completely cleared. +# If _filepath=="" then no action occured and return "". +# If some syntax error found in _filepath then function return "" +# (and NO _filepath-cache-record will be created!). +# Function returns root-dir of _filepath. +#___________________________________________________________________________________ +# +# fn _getmpfile(_filepath,_currfilepath) +# +# Return .... +# +#_____________________________________________________________________________ +# +# fn _getmpdir(_filepath,_currfilepath) +# +# Return ... +# +#_____________________________________________________________________________ +# +# Temporary files folder. +# +# Temporary files folder location is defined by _FILEIO_TMPRD. +# If it wasn't been initialized before program run or not been initialized +# by ENVIRON["TMPDIR"] then it will defined as the: +# `current rootdir(stored in _FILEIO_RD)\programname.TMP' +# In this case if its already exist then it will completely cleared when _FILEIO +# library initialization processed. +# And at the program uninitialization processed it will completely +# cleared if _FILEIO_TMPCLRFLAG is true. +#___________________________________________________________________________________ +# +# var _FILEIO_RD (ENVIRON["CD"]) +# +# This var can be set before running program. It can contain path which +# will be used as default current dir while program run. +# If this var is set before program runs - then it will be refreshed by the +# _filerd it will be used as default current dir while program run. +# If this var is not set before program runs - then ENVIRON["CD"] can also +# set up default current dir while program run. If it set before program +# begin then it will be refreshed by the _filerd - and also writed into +# _FILEIO_RD. +# If both _FILEIO_RD and ENVIRON["CD"] are not set before program begins +# then real current root\dir will be writed into both _FILEIO_RD and +# ENVIRON["CD"] and it will be used as default current dir while program run. +# +#___________________________________________________________________________________ +# +# var _FILEIO_TMPRD (ENVIRON["TMPRD"]) +# +# This var can be set before running program. It can contain path which +# will be used as default temporary files root-folder while program run. +# If this var is set before program runs - then it will be refreshed by the +# _filerd - and also writed into ENVIRON["TMPRD"]. +# If this var is not set before program runs - then ENVIRON["TMPRD"] can also +# set up default temporary files root-folder while program run. If it set +# before program begin then it will be refreshed by the _filerd - and +# also writed into _FILEIO_TMPRD. +# If both _FILEIO_TMPRD and ENVIRON["TMPRD"] are not set before program begins +# then new folder into path specified by the _FILEIO_RD(after its handling) +# will be writed into both _FILEIO_TMPRD and ENVIRON["TMPRD"] and it +# will be used as default temporary files root-folder while program run. +#___________________________________________________________________________________ +# +# var _FILEPATH +# +# This var contain filepath of working script. It should be setting up externally. +# +# var _gawk_scriptlevel +#___________________________________________________________________________________ +#################################################################################### END { if (_constatstrln > 0) { _constat() @@ -376,7 +704,6 @@ END { #_______________________________________________________________________ function W(p, p0, p1) { - ##################################################### if (isarray(p0)) { delete p0[p] if (isarray(p1)) { @@ -410,7 +737,6 @@ function W(p, p0, p1) } ########################################################## - function _ARR(c, t, P) { switch (c) { @@ -440,7 +766,6 @@ function _ARR(c, t, P) } ########################################################## - function _BASE(c, t, P, A) { switch (c) { @@ -494,7 +819,6 @@ function _BASE(c, t, P, A) #____________________________________________________________________________ function _DS(c, t, P, a, A) { - ###################################################### switch (c) { case "_lib_CMDLN": #___________________________________________________________ @@ -520,12 +844,9 @@ function _DS(c, t, P, a, A) #______________________________________________________________________________________________ function _END() { - ################################################################################# - } ######################################################## - function _ERRLOG(c, t, P, a, b, A) { switch (c) { @@ -597,12 +918,9 @@ function _ERRLOG(c, t, P, a, b, A) #______________________________________________________________________________________________ function _EXIT() { - ################################################################################ - } ######################################################## - function _EXTFN(c, t, P) { switch (c) { @@ -632,7 +950,6 @@ function _EXTFN(c, t, P) } ####################################################### - function _FILEIO(c, t, P, A) { switch (c) { @@ -679,11 +996,9 @@ function _FILEIO(c, t, P, A) } } -############################################################ #_____________________________________________________________________________ function _FILEVER(c, t, P, a, A) { - ################################################# switch (c) { case "_lib_CMDLN": #___________________________________________________________ @@ -720,13 +1035,10 @@ function _INIT(f) #___________________________________________________________________________________ function _INITBASE() { - ################################################################ - _egawk_utilpath = ENVIRON["EGAWK_PATH"] "BIN\\UTIL\\" } ###################################################### - function _INSTRUC(c, t, P) { switch (c) { @@ -764,7 +1076,6 @@ function _INSTRUC(c, t, P) #_____________________________________________________________________________ function _N(F, v, p) { - ########################################################### for (p in _UIDS) { delete _UIDS[p] return _nN_i0(p, F, v) @@ -773,7 +1084,6 @@ function _N(F, v, p) } ##################################################### - function _SHORTCUT(c, t, P) { switch (c) { @@ -805,7 +1115,6 @@ function _SHORTCUT(c, t, P) #______________________________________________________________________________________________ function _START(t, i, A) { - ######################################################################### _torexp_init() test_uid() return @@ -915,7 +1224,6 @@ function _START(t, i, A) } ######################################################### - function _SYSIO(c, t, P) { switch (c) { @@ -969,7 +1277,6 @@ function _W(p, A, v) #_______________________________________________________________________ function _Zexparr(S, s, t, i) { - ############################################## t = "" if (isarray(S)) { for (i in S) { @@ -1021,7 +1328,6 @@ function _Zexparr_i3(t) #_______________________________________________________________________ function _Zimparr(D, t, A, B) { - ############################################## if (isarray(D)) { split(t, A, /\x10/, B) t = _Zimparr_i0(A, B, _Zimparr_i1(D, A, B, 1)) @@ -1072,7 +1378,6 @@ function _Zimparr_i2(t) #_____________________________________________________________________________ function _Zimport(t, p, A, c, i, n, B) { - ############################################## if (p) { c = split(t, B, /\x0A/) for (i = 1; i <= c; i++) { @@ -1147,7 +1452,6 @@ function _accmpu(A, a, n) #_______________________________________________________________________ function _add(S, sf, D, df) { - ################################################ if (sf in S) { if (isarray(S[sf])) { if (df in D) { @@ -1171,7 +1475,6 @@ function _add(S, sf, D, df) #_________________________________________________________________ function _addarr(D, S) { - ############################################# if (isarray(S)) { _addarr_i0(D, S) } @@ -1196,7 +1499,6 @@ function _addarr_i0(D, S, i) #_______________________________________________________________________ function _addarrmask(D, S, M) { - ############################################# for (_addarrmaski0 in M) { if (_addarrmaski0 in S) { if (isarray(S[_addarrmaski0])) { @@ -1229,14 +1531,12 @@ function _addarrmask(D, S, M) #_______________________________________________________________________ function _addf(A, f) { - ##################################################### A["B"][""] = A["F"][A["B"][f] = A["B"][""]] = f } #___________________________________________________________ function _addfile(f, d, a, b) { - ################################## if ((f = _wfilerdnehnd(f)) == "" || _filene(f) == "") { ERRNO = "Filename error" return @@ -1262,7 +1562,6 @@ function _addfile(f, d, a, b) #_____________________________________________________________________________ function _addlib(f) { - ########################################################### _addf(_LIBAPI, f) } @@ -1273,15 +1572,12 @@ function _addlib(f) #_______________________________________________________________________ function _addlist(A, v) { - ################################################## A[++A[0]] = v } -############################################ #_______________________________________________________________________ function _bearray(A) { - #################################################### if (isarray(A) || A == 0 && A == "") { return 1 } @@ -1290,7 +1586,6 @@ function _bearray(A) #_________________________________________________________________ function _bframe(A, t, p) { - ########################################### return _bframe_i0(A, t, p, A[""]) } @@ -1322,7 +1617,6 @@ function _bframe_i0(A, t, p, f) #_______________________________________________________________________ function _cfguid(p, optr, pfx, sfx, hstrcnt, lstrchr) { - #################### 0 # delete _UIDOBL[p] if (_isptr(optr)) { if (optr == p) { @@ -1391,7 +1685,6 @@ function _cfguidl(p, H, L, hi, h, hl, li) #____________________________________________________________________________________________________ function _check(p) { - #################################################################################### _dll_check(p) _file_check(p) _serv_check(p) @@ -1401,14 +1694,12 @@ function _check(p) #_______________________________________________________________________ function _chrline(t, ts, w, s) { - ############################################# return ((t = " " _tabtospc(t, ts) ((t ? (t ~ /[ \t]$/ ? "" : " ") : ""))) _getchrln((s ? s : "_"), ((w ? w : _CON_WIDTH - 1)) - length(t)) _CHR["EOL"]) } #_____________________________________________________________________________ function _cmd(c, i, A) { - ####################################################### _fio_cmda = RS RS = ".{1,}" _fio_cmdb = BINMODE @@ -1426,7 +1717,6 @@ function _cmd(c, i, A) #_______________________________________________________________________ function _cmparr(A0, A1, R, a, i) { - ########################################## a = 0 delete R for (i in A0) { @@ -1452,7 +1742,6 @@ function _cmparr(A0, A1, R, a, i) #_____________________________________________________________________________ function _con(t, ts, a, b, c, d, i, r, A, B) { - ########################################## d = RLENGTH if ((c = split(r = t, A, /\x0D?\x0A/, B)) > 0) { a = BINMODE @@ -1494,7 +1783,6 @@ function _con(t, ts, a, b, c, d, i, r, A, B) #_______________________________________________________________________ function _conin(t, a, b) { - ################################################# _constatpush() _constat() a = BINMODE @@ -1516,14 +1804,12 @@ function _conin(t, a, b) #_______________________________________________________________________ function _conl(t, ts) { - #################################################### return _con(t ((t ~ /\x0A$/ ? "" : _CHR["EOL"])), ts) } #_______________________________________________________________________ function _conline(t, ts) { - ################################################# return _con(_chrline(t, ts)) } @@ -1540,7 +1826,6 @@ function _conlq(t, ts) #_______________________________________________________________________ function _constat(t, ts, ln, a) { - ########################################### if (_constatstrln > (ln = length(t = _constatgtstr(_constatstr = _tabtospc(t, ts), _CON_WIDTH - 1 - _conlastrln)))) { t = t _getchrln(" ", _constatstrln - ln) } @@ -1577,7 +1862,6 @@ function _constatgtstr(t, ln, a, b) #_______________________________________________________________________ function _constatpop() { - ################################################## if (_CONSTATPUSH[0] > 0) { return _constat(_CONSTATPUSH[_CONSTATPUSH[0]--]) } @@ -1587,7 +1871,6 @@ function _constatpop() #_______________________________________________________________________ function _constatpush(t, ts) { - ############################################# _CONSTATPUSH[++_CONSTATPUSH[0]] = _constatstr if (t) { _constat(t, ts) @@ -1604,7 +1887,6 @@ function _creport(p, t, f, z) #_________________________________________________________________________________________ function _defdir(pp, n, f, v, p) { - ############################################################# _[p = _wLCHLD(pp, _n("TYPE", "defdir"))]["NAME"] = n _[p]["DIR"] = f return p @@ -1613,7 +1895,6 @@ function _defdir(pp, n, f, v, p) #_________________________________________________________________________________________ function _defdll(pp, n, rn, p) { - ############################################################## _[p = _wLCHLD(pp, _n("TYPE", "defdll"))]["NAME"] = n _[p]["REGPATH"] = _[pp]["REGPATH"] rn _[p]["ERRHOST"] = pp @@ -1654,7 +1935,6 @@ function _defescarr(D, r, S, i, c, t) #_________________________________________________________________________________________ function _defile(pp, n, f, v, p) { - ############################################################# _[p = _wLCHLD(pp, _n("TYPE", "defile"))]["NAME"] = n _[p]["FILE"] = f if (! (v == 0 && v == "")) { @@ -1666,14 +1946,12 @@ function _defile(pp, n, f, v, p) #_______________________________________________________________________ function _defn(f, c, v) { - ################################################### FUNCTAB[c f] = v } #_________________________________________________________________________________________ function _defreg(pp, n, f, v, p) { - ############################################################# _[p = _wLCHLD(pp, _n("TYPE", "defreg"))]["NAME"] = n _[p]["REGPATH"] = f if (! (v == 0 && v == "")) { @@ -1684,7 +1962,6 @@ function _defreg(pp, n, f, v, p) #_______________________________________________________________________________________________ function _defsolution(pp, n, rn, p) { - ############################################################### _[p = _wLCHLD(pp, _n("TYPE", "solution"))]["NAME"] = n _[p]["REGPATH"] = rn _[p]["ERRHOST"] = pp @@ -1694,7 +1971,6 @@ function _defsolution(pp, n, rn, p) #_________________________________________________________________________________________ function _defsrv(pp, n, f, v, p) { - ############################################################# _[p = _wLCHLD(pp, _n("TYPE", "defsrv"))]["NAME"] = n _[p]["SERVNAME"] = f return p @@ -1703,7 +1979,6 @@ function _defsrv(pp, n, f, v, p) #_______________________________________________________________________ function _del(f, c, a, A) { - ################################################# if (match(f, /\\[ \t]*$/)) { if ((c = toupper(_filerd(f))) && length(f) == FLENGTH) { _cmd("rd " c " /S /Q 2>NUL") @@ -1732,7 +2007,6 @@ function _del(f, c, a, A) #_______________________________________________________________________ function _delay(t, a) { - ################################################### for (a = 1; a <= t; a++) { _delayms() } @@ -1741,7 +2015,6 @@ function _delay(t, a) #_________________________________________________________________ function _delayms(a) { - ############################################# for (a = 1; a <= _delay_perfmsdelay; a++) { } } @@ -1749,7 +2022,6 @@ function _delayms(a) #_______________________________________________________________________ function _deletepfx(A, f, B, le, i) { - ######################################## le = length(f) for (i in A) { if (substr(toupper(i), 1, le) == f) { @@ -1762,7 +2034,6 @@ function _deletepfx(A, f, B, le, i) #_________________________________________________________________ function _delf(A, f) { - ############################################### A["B"][A["F"][A["B"][f]] = A["F"][f]] = A["B"][f] delete A["F"][f] delete A["B"][f] @@ -1771,7 +2042,6 @@ function _delf(A, f) #_______________________________________________________________________ function _deluid(p) { - ################################################# 1 # if (p in _CLASSPTR) { _deluida0 = _CLASSPTR[p] if (_deluida0 in _UIDOBL) { @@ -1785,7 +2055,6 @@ function _deluid(p) #_______________________________________________________________________ function _dir(A, rd, i, r, f, ds, pf, B, C) { - #################################### delete A gsub(/(^[ \t]*)|([ \t]*$)/, "", rd) if (rd == "") { @@ -1815,7 +2084,6 @@ function _dir(A, rd, i, r, f, ds, pf, B, C) #_________________________________________________________________ function _dirtree(A, f, B) { - ######################################### gsub(/(^[ \t]*)|([ \t]*$)/, "", f) delete A A[""] @@ -1852,8 +2120,7 @@ function _dll_check(pp) { _dllchktv = "" _missfl = 1 - _tframe("_dll_check_i0", pp, _REG, pp) - #also check that all dll have same version; also check that all dlls have success and then report that DS plug-in version n - installed + _tframe("_dll_check_i0", pp, _REG, pp) #also check that all dll have same version; also check that all dlls have success and then report that DS plug-in version n - installed if (1 || "AGENT" in _[pp]) { if (_dllchktv != _[pp][".Product Version"]) { _dllerr(_[pp]["AGENT"], "agent version (" _[pp][".Product Version"] ") do not match all lib versions: " _dllchktv "'") @@ -1888,7 +2155,6 @@ function _dll_check_i0(p, R, pp, p2, i, i2, r, f, v, rs, d, tv, tf) } } } - #{ rs=_missfl=1; _[p]["." gensub(/^([^\\]+\\)+(.*)\..../,"\\2","G",i)]=R[i] } } if (rs) { if ((i = ".Install Path") in _[p] && (i = ".Product Version") in _[p]) { _[p]["STATUS"] = "PRESENT" @@ -1982,7 +2248,6 @@ function _drawuid(p, cn, ch, o) #_______________________________________________________________________ function _dumparr(A, t, lv, a) { - ############################################ b = PROCINFO["sorted_in"] PROCINFO["sorted_in"] = "_lengthsort" if (isarray(A)) { @@ -2047,7 +2312,6 @@ function _dumparr_i1(A, lv, ls, ln, t, t2, i, a, f) #_____________________________________________________________________________ function _dumpobj(p, f, t, s) { - ################################################### s = _dumpobj_i0(p, f, t = t "." p "{") if (p = _rFCHLD(p)) { return (s = s _dumpobjm(p, f, (s ? _getchrln(" ", length(t) - 1) : t " "))) @@ -2115,14 +2379,12 @@ function _dumpobj_i4(t) #_________________________________________________________________ function _dumpobj_nc(p, f, t) { - ####################################### return _dumpobj_i0(p, f, t "." p "{ ") } #_________________________________________________________________ function _dumpobjm(p, f, t, s, t2) { - ################################### t2 = _getchrln(" ", length(t)) do { s = s _dumpobj(p, f, t) @@ -2134,7 +2396,6 @@ function _dumpobjm(p, f, t, s, t2) #_________________________________________________________________ function _dumpobjm_nc(p, f, t, s, t2) { - ################################ t2 = _getchrln(" ", length(t)) do { s = s _dumpobj_nc(p, f, t) @@ -2174,7 +2435,6 @@ function _dumpval(v, n) } ######################################################## - function _eXTFN(c, t, P) { switch (c) { @@ -2212,7 +2472,6 @@ function _endpass(t) #_______________________________________________________________________ function _err(t, a, b) { - ################################################### a = BINMODE b = ORS BINMODE = "rw" @@ -2227,14 +2486,12 @@ function _err(t, a, b) #_________________________________________________________________ function _errnl(t) { - ################################################ return _err(t ((t ~ /\x0A$/ ? "" : _CHR["EOL"]))) } #_______________________________________________________________________ function _error(t, d, A) { - ################################################# if (_ERRLOG_EF) { A["TYPE"] = "ERROR" A["TEXT"] = t @@ -2245,14 +2502,12 @@ function _error(t, d, A) #_______________________________________________________________________ function _exit(c) { - ####################################################### exit c } #_____________________________________________________________________________ function _export_data(t, i, A) { - ################################################# A["DATA"] = t A["ID"] = i _expout("_DATA: " _Zexparr(A) "\n") @@ -2264,7 +2519,6 @@ function _export_data(t, i, A) #_____________________________________________________________________________ function _expout(t, d, a, b) { - #################################################### a = BINMODE b = ORS BINMODE = "rw" @@ -2287,8 +2541,6 @@ function _expout(t, d, a, b) function _extfn_init() { - ############################################################## - _formatstrs_init() _formatstrd_init() _formatrexp_init() @@ -2321,7 +2573,6 @@ function _faccr_i0(A, t, p, P, f, r) #_______________________________________________________________________ function _fatal(t, d, A) { - ################################################# if (_ERRLOG_FF) { A["TYPE"] = "FATAL" A["TEXT"] = t @@ -2352,11 +2603,9 @@ function _ffaccr(A, t, p, P) return _faccr_i0(A["F"], t, p, P) } -################## #_______________________________________________________________________ function _fframe(A, t, p) { - ################################################# return _fframe_i0(A, t, p, A[""]) } @@ -2369,7 +2618,6 @@ function _fframe_i0(A, t, p, f) #_________________________________________________________________ function _file(f) { - ################################################# if ((f = _filerdnehnd(f)) == "") { return "" } @@ -2418,7 +2666,6 @@ function _file_check_i0(p, pp, p1, p2, f, v) #_________________________________________________________________ function _filed(f, dd, d) { - ########################################## if ((f = _filerdnehnd(f)) == "") { return "" } @@ -2443,7 +2690,6 @@ function _filed(f, dd, d) #_________________________________________________________________ function _filen(f) { - ################################################ if ((f = _filerdnehnd(f)) == "") { return "" } @@ -2453,7 +2699,6 @@ function _filen(f) #_________________________________________________________________ function _filene(f) { - ############################################### if ((f = _filerdnehnd(f)) == "") { return "" } @@ -2463,7 +2708,6 @@ function _filene(f) #_________________________________________________________________ function _filenotexist(f, a) { - ###################################### if (f == "") { return "" } @@ -2481,7 +2725,6 @@ function _filenotexist(f, a) #_______________________________________________________________________ function _filepath(f, dd) { - ################################################ if ((f = _filerdnehnd(f)) == "") { return "" } @@ -2491,7 +2734,6 @@ function _filepath(f, dd) #_________________________________________________________________ function _filer(f, dd) { - ############################################# if ((f = _filerdnehnd(f)) == "") { return "" } @@ -2507,7 +2749,6 @@ function _filer(f, dd) #_________________________________________________________________ function _filerd(f, dd) { - ############################################ if ((f = _filerdnehnd(f)) == "") { return "" } @@ -2517,7 +2758,6 @@ function _filerd(f, dd) #_________________________________________________________________ function _filerdn(f, dd) { - ########################################### if ((f = _filerdnehnd(f)) == "") { return "" } @@ -2527,7 +2767,6 @@ function _filerdn(f, dd) #_________________________________________________________________ function _filerdne(f, dd) { - ########################################## if ((f = _filerdnehnd(f)) == "") { return "" } @@ -2598,7 +2837,6 @@ function _filerdnehnd(st, c, r, d, n, A) #_______________________________________________________________________ function _filexist(f, a) { - ################################################ if (f == "") { return "" } @@ -2617,7 +2855,6 @@ function _filexist(f, a) #_______________________________________________________________________ function _fn(f, p0, p1, p2) { - ################################################ if (f in FUNCTAB) { return @f(p0, p1, p2) } @@ -2626,7 +2863,6 @@ function _fn(f, p0, p1, p2) #_______________________________________________________________________ function _foreach(A, f, r, p0, p1, p2, i, p) { - #################################### if (isarray(A)) { _TMP0[p = _n()]["."] = 1 _foreach_i0(A, f, _TMP0[p], p0, p1, p2) @@ -2695,7 +2931,6 @@ function _formatstrd_init() _FORMATSTRDESC["\t"] = "\\t" } -#__________________________________________________________________________________ #################################################################################### @@ -2765,7 +3000,6 @@ function _gen(D, t) #_____________________________________________________________________________ function _gensubfn(t, r, f, p0, A) { - ############################################### if (match(t, r, A)) { return (substr(t, 1, RSTART - 1) (@f(_th0(substr(t, RSTART, RLENGTH), t = substr(t, RSTART + RLENGTH)), A, p0)) _gensubfn(t, r, f, p0)) } @@ -2775,7 +3009,6 @@ function _gensubfn(t, r, f, p0, A) #_____________________________________________________________________________ function _get_errout(p) { - ####################################################### return _tframe("_get_errout_i0", p) } @@ -2830,7 +3063,6 @@ function _get_errout_i3(p, t, ts, cl, cp, cr, a, b) #_____________________________________________________________________________ function _get_logout(p) { - ####################################################### return _tframe("_get_logout_i0", p) } @@ -2854,7 +3086,6 @@ function _get_logout_i0(p, t, n, a) #_______________________________________________________________________ function _getchrln(s, w) { - ################################################# if (s == "") { return } @@ -2880,14 +3111,12 @@ function _getchrln(s, w) #_______________________________________________________________________ function _getdate() { - ##################################################### return strftime("%F") } #_____________________________________________________________________________ function _getfilepath(t, f, al, b, A) { - ############################################ ERRNO = "" if (match(t, /^[ \t]*(("([^"]*)"[ \t]*)|([`']([^']*)'[ \t]*)|(([^ \t]+)[ \t]*))/, A)) { al = RLENGTH @@ -2906,7 +3135,6 @@ function _getfilepath(t, f, al, b, A) function _getfilever(f) { - ############################################################# split(_cmd(_fileverpath " \"" f "\""), _GETFILEVERA0, /[ \t]+/) if (_GETFILEVERA0[5]) { return _GETFILEVERA0[5] @@ -2916,14 +3144,12 @@ function _getfilever(f) #_________________________________________________________________ function _getime() { - ################################################ return strftime("%H:%M:%S") } #_________________________________________________________________ function _getmpdir(f, dd) { - ########################################## if (! dd || ! (dd = _filerd(dd))) { dd = _FILEIO_TMPRD } @@ -2936,7 +3162,6 @@ function _getmpdir(f, dd) #_________________________________________________________________ function _getmpfile(f, dd) { - ######################################### if (! dd || ! (dd = _filerd(dd))) { dd = _FILEIO_TMPRD } @@ -2949,7 +3174,6 @@ function _getmpfile(f, dd) #_______________________________________________________________________ function _getperf(o, t, a) { - ############################################### (o == "" ? ++_getperf_opcurr : _getperf_opcurr = o) if ((a = _getsecond()) != _getperf_last) { _getperf_opsec = (_getperf_opcurr - _getperf_opstart) / ((_getperf_last = a) - _getperf_start) @@ -3045,14 +3269,12 @@ function _getreg_i1(D, r, R, a, i, il, ir, rc, B) #_________________________________________________________________ function _getsecond() { - ############################################# return systime() } #___________________________________________________________ function _getsecondsync(a, c, b, c2) { - ########################## a = systime() while (a == systime()) { ++c @@ -3063,7 +3285,6 @@ function _getsecondsync(a, c, b, c2) #_______________________________________________________________________ function _getuid(p) { - ################################################# 1 # if (p in _UIDOBL) { for (_tptr in _UIDOBLV[_getuida0 = _UIDOBL[p]]) { delete _UIDOBLV[_getuida0][_tptr] @@ -3096,7 +3317,6 @@ function _handle8494(t) #_____________________________________________________________________________ function _hexnum(n, l) { - ######################################################### if (l + 0 < 1) { l = 2 } @@ -3106,7 +3326,6 @@ function _hexnum(n, l) #_________________________________________________________________ function _igetperf(t, s, o) { - ######################################### # t-test period in seconds(==0 ? no period; s(=true/false)-output/not output status; o-qnt of ops before test start if (t == 0 && t == "" && s == 0 && s == "" && o == 0 && o == "") { if (_getperf_fn !~ /not$/ && _constatstr == _getperf_stat) { _constat(_getperf_statstr) @@ -3137,7 +3356,6 @@ function _import_data(t, p, p2, a) #_______________________________________________________________________ function _info(t, d, A) { - ################################################## if (_ERRLOG_IF) { A["TYPE"] = "INFO" A["TEXT"] = t @@ -3209,7 +3427,6 @@ function _initsys() #_______________________________________________________________________ function _inituid(p, cs, dptr, pfx, sfx, hstr, lstr, A) { - ################### 1 # if (cs == 0 && cs == "") { cs = p p = _getuid() @@ -3271,7 +3488,6 @@ function _inituidefault(h, l, H, L) #_______________________________________________________________________ function _ins(S, sf, D, df) { - ################################################ if (sf in S) { if (isarray(S[sf])) { if (df in D) { @@ -3295,19 +3511,16 @@ function _ins(S, sf, D, df) #_________________________________________________________________ function _insf(A, f) { - ############################################### A["F"][""] = A["B"][A["F"][f] = A["F"][""]] = f } #_________________________________________________________________ function _insframe(A, f) { - ########################################### A[f] = A[""] A[""] = f } -######################## #_________________________________________________________________ function _inspass(A, f) { @@ -3320,7 +3533,6 @@ function _inspass(A, f) #_______________________________________________________________________ function _isptr(p) { - ################################################## 1 # if (isarray(p)) { is = _NOP it = "A" @@ -3341,7 +3553,6 @@ function _isptr(p) #_______________________________________________________________________ function _istr(p) { - ################################################### 1 # if (isarray(p)) { is = _NOP it = "A" @@ -3358,7 +3569,6 @@ function _istr(p) #_________________________________________________________________ function _lengthsort(i1, v1, i2, v2) { - ############################## return ((length(i1) < length(i2) ? -1 : (length(i1) > length(i2) ? 1 : (i1 < i2 ? -1 : 1)))) } @@ -3401,14 +3611,12 @@ function _lib_NAMEVER() #_____________________________________________________________________________ function _ln(t) { - ############################################################### return ((t ~ /\x0A$/ ? t : t _CHR["EOL"])) } #_________________________________________________________________ function _log(A, p, a, B) { - ########################################### if (isarray(A)) { A["TIME"] = _getime() A["DATE"] = _getdate() @@ -3429,7 +3637,6 @@ function _log(A, p, a, B) #_________________________________________________________________ function _lspctab(t, ts, l, l1, l2, A) { - ################################ while (match(t, /^(\t*)( *)((\t*)(.*))$/, A)) { if (A[1, "length"] >= l) { return substr(t, l + 1) @@ -3471,7 +3678,6 @@ function _macsfx94(F, D, C, p1, p2, p3) #_______________________________________________________________________ function _movarr(D, S) { - ################################################### delete D D[""] delete D[""] @@ -3589,7 +3795,6 @@ function _mpusub(F, D, C, d, p1, p2, p3, q) #_______________________________________________________________________ function _n(F, v, p) { - ##################################################### for (p in _UIDSDEL) { delete _UIDSDEL[p] delete _ptr[p] @@ -3652,7 +3857,6 @@ function _nN_i0(p, F, v) #_________________________________________________________________ function _newclrdir(f) { - ############################################ if ((f = _filerd(f)) == "") { return } @@ -3665,7 +3869,6 @@ function _newclrdir(f) #_______________________________________________________________________ function _newdir(f) { - ##################################################### if ((f = _filerd(f)) == "") { return } @@ -3676,7 +3879,6 @@ function _newdir(f) return f } -############################## #_______________________________________________________________________ function _nop(p0, p1, p2, p3) { @@ -3700,7 +3902,6 @@ function _nop(p0, p1, p2, p3) #_________________________________________________________________ function _nretarr(A, i, v, r, q) { - ##################################### if ((i = (i == "" ? 1 : i + 0)) <= (q = A[_ARRLEN])) { if (i <= (r = q - 16)) { _ARRSTR = A[i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] @@ -3720,7 +3921,6 @@ function _nretarr(A, i, v, r, q) #___________________________________________________________ function _nretarrd(A, i, v, r, q) { - ############################## if ((i = (i == "" ? 1 : i + 0)) <= (q = A[_ARRLEN])) { if (i <= (r = q - 16)) { _ARRSTR = A[i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] A[++i] @@ -3745,7 +3945,6 @@ function _nretarrd(A, i, v, r, q) #___________________________________________________________________________________ function _out(t, a, b) { - ############################################################### a = BINMODE b = ORS BINMODE = "rw" @@ -3760,7 +3959,6 @@ function _out(t, a, b) #_________________________________________________________________ function _outnl(t) { - ################################################ return _out(t ((t ~ /\x0A$/ ? "" : _CHR["EOL"]))) } @@ -3815,7 +4013,6 @@ function _p8(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) #_______________________________________________________________________ function _pass(A, f, t, p2, i, a) { - ########################################### a = _endpass_v0 _endpass_v0 = "" i = 1 @@ -3838,7 +4035,6 @@ function _pass(A, f, t, p2, i, a) #_____________________________________________________________________________ function _patharr0(D, q, i, h, A, B) { - ############################################## delete D if (0 < (q = split(gensub(/\\/, "/", "G", gensub(/ *([:$\\\/]) */, "\\1", "G", gensub(/(^[ \t]+)|([ \t]+$)/, "", "G", q))), A, /\/+/, B))) { if (2 > (h = length(B[1]))) { @@ -3927,9 +4123,6 @@ function _patharr0_i1(D, A, i, q, t, c) } ############################################################################# - - - function _pmap(m, s1, s2, s3, s4, s5, s6, s7, s8) { if (match(m, /^([^\(]+)\(([^\)]*)\)$/, _QMAP)) { @@ -3988,7 +4181,6 @@ function _pr8(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) #_________________________________________________________________ function _printarr(A, t, lv, r, a) { - #################################### a = PROCINFO["sorted_in"] PROCINFO["sorted_in"] = "_lengthsort" _printarrexp = (r ? r : "") @@ -4094,7 +4286,6 @@ function _qparam_i0(p0, p1, p2, p3, p4, p5, p6, p7) #_______________________________________________________________________ function _qstr(t, c, A, B) { - ################################################ c = "" for (t = split(t, A, /[\x00-\x1F\\"]/, B); t >= 0; t--) { c = _QSTR[B[t]] A[t + 1] c @@ -4105,17 +4296,14 @@ function _qstr(t, c, A, B) #_________________________________________________________________ function _qstrq(t) { - ################################################ gsub(/\\/, "\\\\", t) gsub(/"/, "\\\"", t) return t } -################################################################ #_____________________________________________________________________________ function _rEG(c, t, P, a, A) { - ##################################################### switch (c) { case "_lib_CMDLN": #___________________________________________________________ @@ -4141,7 +4329,6 @@ function _rEG(c, t, P, a, A) #_______________________________________________________________________ function _rFBRO(p) { - ###################################################### if (p) { if (p in _tPARENT) { return _tFCHLD[_tPARENT[p]] @@ -4157,18 +4344,15 @@ function _rFBRO(p) #_______________________________________________________________________ function _rFCHLD(p) { - ##################################################### if (p && p in _tFCHLD) { return _tFCHLD[p] } return "" } -######################## p="", !v #_______________________________________________________________________ function _rLBRO(p) { - ###################################################### if (p) { if (p in _tPARENT) { return _tLCHLD[_tPARENT[p]] @@ -4181,11 +4365,9 @@ function _rLBRO(p) return p } -######################## p="" #_______________________________________________________________________ function _rLCHLD(p) { - ##################################################### if (p && p in _tLCHLD) { return _tLCHLD[p] } @@ -4195,48 +4377,39 @@ function _rLCHLD(p) #_______________________________________________________________________ function _rLINK(p) { - ###################################################### return ((p in _tLINK ? _tLINK[p] : "")) } -######################## p="" #_______________________________________________________________________ function _rNEXT(p) { - ###################################################### if (p && p in _tNEXT) { return _tNEXT[p] } return "" } -######################## p="" #_______________________________________________________________________ function _rPARENT(p) { - #################################################### if (p && p in _tPARENT) { return _tPARENT[p] } return "" } -######################## p="" #_______________________________________________________________________ function _rPREV(p) { - ###################################################### if (p && p in _tPREV) { return _tPREV[p] } return "" } -######################## p="" #_______________________________________________________________________ function _rQBRO(p, c, p1) { - ################################################ if (p) { if (p in _tPARENT) { return _tQCHLD[_tPARENT[p]] @@ -4256,11 +4429,9 @@ function _rQBRO(p, c, p1) return p } -######################## p="" #_______________________________________________________________________ function _rQCHLD(p) { - ##################################################### if (p && p in _tQCHLD) { return _tQCHLD[p] } @@ -4273,7 +4444,6 @@ function _rQCHLD(p) #_____________________________________________________________________________ function _rSQFIRST(g, p, A) { - ##################################################### if (isarray(A)) { return _rSQFIRSTA(g, p, A) } @@ -4285,7 +4455,6 @@ function _rSQFIRST(g, p, A) #_________________________________________________________________ function _rSQFIRSTA(g, p, A) { - ######################################## _SQTOPTR[g] = p _SQSTACK[g][0] = 0 if ((p = _rsqgetptr(g, p)) in A) { @@ -4297,7 +4466,6 @@ function _rSQFIRSTA(g, p, A) #_______________________________________________________________________ function _rSQNEXT(g, p, A) { - ################################################ if (isarray(A)) { return _rSQNEXTA(g, p, A) } @@ -4307,7 +4475,6 @@ function _rSQNEXT(g, p, A) #_________________________________________________________________ function _rSQNEXTA(g, p, A) { - ######################################### if (p == _SQTOPTR[g]) { if (_SQSTACK[g][0] > 0) { _SQTOPTR[g] = _SQSTACK[g][_SQSTACK[g][0]--] @@ -4353,7 +4520,6 @@ function _rd_shortcut(D, f) #_______________________________________________________________________ function _rdfile(f, i, A) { - ################################################ if ((f = _filerdne(f)) == "" || _filene(f) == "") { ERRNO = "Filename error" return @@ -4406,7 +4572,6 @@ function _rdfile(f, i, A) # fn _getsecondsync() function _rdreg(D, p) { - ################################################################ _rdregp0 = "reg query \"" p "\" /S /reg:64 2>NUL" _rdregfld = _rdregkey = 0 _rdregq0 = split(gensub(/[\x0D?\x0A]{2,}/, _CHR["EOL"], "G", _cmd(_rdregp0)), _RDREGA0, /\x0D?\x0A/) @@ -4545,7 +4710,6 @@ function _registryinit() #_____________________________________________________________________________ function _regpath0(D, i, s, q, S) { - ############################################ 0 # if (i = _patharr0(S, i)) { if ("name" in S) { D["name"] = S["name"] @@ -4569,7 +4733,6 @@ function _regpath0(D, i, s, q, S) #_________________________________________________________________________________________ function _report(p) { - ####################################################################### _report_t0 = _reportparnt = "" _report_i0(p) _tframe("_report_i0", p) @@ -4667,7 +4830,6 @@ function _reporterr(p, t3, pp, t, t2) #_____________________________________________________________________________ function _retarr(A, i, p, a, q) { - ################################################## if (isarray(A)) { i = (i == "" ? 0 : i + 0) q = A[_ARRLEN] + 0 @@ -4691,7 +4853,6 @@ function _retarr_i0(A, q, i, a) #_________________________________________________________________ function _retarrd(A, v, i) { - ######################################### if (1 in A) { return (A[1] A[2] A[3] A[4] A[5] A[6] A[7] A[8] A[9] A[10] A[11] A[12] A[13] A[14] A[15] A[16] (((i = 17) in A ? _retarrd_i0(A, i) v : v))) } @@ -4729,7 +4890,6 @@ function _rexpfnend(t) #_____________________________________________________________________________ function _rexpstr(r, i, c, A) { - ################################################### c = split(r, A, "") r = "" for (i = 1; i <= c; i++) { @@ -4771,7 +4931,6 @@ function _rpp(q, D, S) #_________________________________________________________________________________________ function _rrdreg(DD, p, k, t, v, c, i, q, tT, A, B, C, D) { - ############################################# old; regedit if (! _registrytmpfile) { _registryinit() } @@ -4889,11 +5048,9 @@ function _rxpfn(R, t, p, i, f, A) return _rexpfnend(t) } -############################################################## #_____________________________________________________________________________ function _sHARE(c, t, P, a, A) { - ################################################### switch (c) { case "_lib_CMDLN": #___________________________________________________________ @@ -4916,11 +5073,9 @@ function _sHARE(c, t, P, a, A) } } -################################################################ #_____________________________________________________________________________ function _sYS(c, t, P, a, A) { - ##################################################### switch (c) { case "_lib_CMDLN": #___________________________________________________________ @@ -4967,7 +5122,6 @@ function _serv_check_i0(p, p0, p1, p2, p3, i, q, c) #_______________________________________________________________________ function _setarrsort(f, a) { - ############################################## a = PROCINFO["sorted_in"] if (! f) { delete PROCINFO["sorted_in"] @@ -4980,7 +5134,6 @@ function _setarrsort(f, a) #_______________________________________________________________________ function _setmpath(p, a) { - ################################################ ERRNO = "" if (p && (a = _filerd(p))) { if (_FILEIO_TMPRD) { @@ -5018,7 +5171,6 @@ function _setmpath(p, a) function _sharelist(D, h, q, c, l, A, B) { - ################################################# delete D c = _sharextool " \\\\" ((h == "" ? h = ENVIRON["COMPUTERNAME"] : h)) " 2>&1" if (match(c = _cmd(c), /\x0AShare[^\x0A]*Remark/)) { @@ -5038,7 +5190,6 @@ function _sharelist(D, h, q, c, l, A, B) #_____________________________________________________________________________ function _sharepath(h, s, A) { - ################################################### s = _sharextool " \\\\" ((h == "" ? h = ENVIRON["COMPUTERNAME"] : h)) "\\\"" s "\" 2>&1" if (match(s = _cmd(s), /\x0APath[ \t]+([^\x0D\x0A]+)/, _SHAREPATHA0)) { return gensub(/[ \t\\\/]*$/, "\\\\", 1, _SHAREPATHA0[1]) @@ -5048,17 +5199,14 @@ function _sharepath(h, s, A) function _shortcut(D, S) { - ############################################################# if (isarray(D)) { if (isarray(S)) { _addarrmask(D, S, _SHORTCUTWSTRUC) } else { if (S == 0 && S == "") { - # array,array2* - copy from array2 to array shorcut-specific elements _addarrmask(D, _SHORTCUTDEFAULT, _SHORTCUTWSTRUC) } else { if (_isnotfileptr(S)) { - # array* - define shortcut-specific elements in array by default values _addarrmask(D, _[S], _SHORTCUTWSTRUC) } else { if (_rd_shortcut(D, S)) { @@ -5067,22 +5215,18 @@ function _shortcut(D, S) } } } - # array,ptr* - copy from array _[ptr] to array shorcut-specific elements } else { if (D == 0 && D == "") { return _NOP } else { if (_isnotfileptr(D)) { - # -* - no action(return -) if (isarray(S)) { _addarrmask(_[D], S, _SHORTCUTWSTRUC) } else { if (S == 0 && S == "") { - # ptr,array* - copy from array to array _[ptr] shorcut-specific elements _addarrmask(_[D], _SHORTCUTDEFAULT, _SHORTCUTWSTRUC) } else { if (_isnotfileptr(S)) { - # ptr* - define shortcut-specifc elements in array _[ptr] by default values _addarrmask(_[D], _[S], _SHORTCUTWSTRUC) } else { if (_rd_shortcut(_[D], S)) { @@ -5091,9 +5235,7 @@ function _shortcut(D, S) } } } - # ptr,ptr2* - copy from array _[ptr2] to array _[ptr] shorcut-specific elements } else { - # ptr,filepath* - define in array _[ptr] shortcut-specific elements by reading its from shortcut file filepath(load shortcut) if (isarray(S) && _wr_shortcut(D, S)) { return } else { @@ -5109,11 +5251,9 @@ function _shortcut(D, S) } } } - # filepath,ptr* - [over]write shorcut file filepath; shortcut parameters will be defined by shortcut-specific elements in array _[ptr](save shortcut) } } } - # filepath,filepath2* - [over]write shorcut file filepath; shortcut parameters will be defined from shortcut file filepath2(copy shortcut) return 1 } @@ -5299,7 +5439,6 @@ function _splitpath_test() #_______________________________________________________________________ function _splitstr(A, t, r) { - ########################################### 1 # if (_istr(t)) { if (_splitstr_i0(A, t) > 0) { return _splitstrp0 @@ -5475,7 +5614,6 @@ function _subseqon(B, r, F, f, s, e, q, i, A) function _sysinfo(D, h) { - ############################################################## h = "wmic /NODE: \"" h "\" OS 2>NUL" if (split(_cmd(h), _SYSINFOA0, /[\x0D\x0A]+/) == 3) { _sysinfol0 = length(h = _SYSINFOA0[2]) + 1 @@ -5488,7 +5626,6 @@ function _sysinfo(D, h) } ######################################################### - function _tOBJ(c, t, P) { switch (c) { @@ -5519,7 +5656,6 @@ function _tOBJ(c, t, P) #_______________________________________________________________________ function _tOBJ_CLEANUP(p) { - ############################################## for (p in UIDSDEL) { delete _ptr[p] delete _tPREV[p] @@ -5538,7 +5674,6 @@ function _tOBJ_CLEANUP(p) #_______________________________________________________________________ function _tabtospc(t, ts, xc, a, c, n, A, B) { - ################################## if (! ts) { ts = _TAB_STEP_DEFAULT } @@ -5575,7 +5710,6 @@ function _tapi(p, f, p0, p1, p2, p3, c) #_____________________________________________________________________________ function _tbframe(f, p, p0, p1) { - ################################################## delete _t_ENDF[++_t_ENDF[0]] f = (p ? _tbframe_i0(f, p, p0, p1) : "") --_t_ENDF[0] @@ -5594,7 +5728,6 @@ function _tbframe_i0(f, p, p0, p1, a) #_______________________________________________________________________ function _tbframex(f, p, p0, p1) { - ########################################### delete _t_ENDF[++_t_ENDF[0]] f = (p ? _tbframex_i0(f, p, p0, p1) : "") --_t_ENDF[0] @@ -5613,7 +5746,6 @@ function _tbframex_i0(f, p, p0, p1) #_____________________________________________________________________________ function _tbpass(f, p, p0, p1) { - ################################################### delete _t_ENDF[++_t_ENDF[0]] f = (p ? _tbpass_i0(f, p, p0, p1) : "") --_t_ENDF[0] @@ -5632,7 +5764,6 @@ function _tbpass_i0(f, p, p0, p1, a) #_____________________________________________________________________________ function _tbpassx(f, p, p0, p1) { - ################################################## delete _t_ENDF[++_t_ENDF[0]] f = (p ? _tbpassx_i0(f, p, p0, p1) : "") --_t_ENDF[0] @@ -5651,7 +5782,6 @@ function _tbpassx_i0(f, p, p0, p1) #_____________________________________________________________________________ function _tbrochld(p, f, pp) { - ################################################### # TEST!!! if (p) { if (p in _tFCHLD) { f = _tFCHLD[p] @@ -5743,35 +5873,30 @@ function _tbrochld(p, f, pp) #_________________________________________________________________ function _tbrunframe(f, p, p0, p1) { - ################################### return _tbframe((f ? f : "_trunframe_i0"), p, p0, p1) } #_________________________________________________________________ function _tbrunframex(f, p, p0, p1) { - ################################## return _tbframex((f ? f : "_trunframe_i0"), p, p0, p1) } #_________________________________________________________________ function _tbrunpass(f, p, p0, p1) { - #################################### return _tbpass((f ? f : "_trunframe_i0"), p, p0, p1) } #_________________________________________________________________ function _tbrunpassx(f, p, p0, p1) { - ################################### return _tbpassx((f ? f : "_trunframe_i0"), p, p0, p1) } #_____________________________________________________________________________ function _tdel(p, i) { - ########################################################## if (p in _) { _texclude(p) for (i in _ptr[p]) { @@ -5833,7 +5958,6 @@ function _tdel_i1(A, i) #_____________________________________________________________________________ function _tdelete(p, v) { - ####################################################### # REMAKE EXCLUDE if (p) { _wLCHLD(_tDELPTR, p) } @@ -5843,7 +5967,6 @@ function _tdelete(p, v) #_________________________________________________________________ function _tdelitem(p) { - ############################################# if (p) { if ("HOST" in _PTR[p] && "ITEMNAME" in _[p]) { return _wLCHLD(_PTR[_PTR[p]["HOST"]]["ITEM"][_[p]["ITEMNAME"]], p) @@ -5856,7 +5979,6 @@ function _tdelitem(p) #_______________________________________________________________________ function _tend(a, b) { - ##################################################### if (b == "") { return (_t_ENDF[_t_ENDF[0]] = a) } else { @@ -5867,7 +5989,6 @@ function _tend(a, b) #_____________________________________________________________________________ function _texclude(p, v, pp) { - ################################################### # TEST!!! if (p in _) { if (p in _tPARENT) { pp = _tPARENT[p] @@ -5916,7 +6037,6 @@ function _texclude(p, v, pp) #_____________________________________________________________________________ function _tframe(fF, p, p0, p1, p2) { - ############################################### delete _t_ENDF[++_t_ENDF[0]] p = (_isptr(p) ? (isarray(fF) ? _tframe_i1(fF, p, p0, p1, p2) : _tframe_i0(fF, p, p0, p1, p2)) : "") --_t_ENDF[0] @@ -5926,7 +6046,6 @@ function _tframe(fF, p, p0, p1, p2) #_____________________________________________________________________________ function _tframe0(f, p, p0, p1, p2, p3, A) { - ######################################### if (_isptr(p)) { if (isarray(f)) { return _tframe0_i0(f, p) @@ -5993,7 +6112,6 @@ function _tframe0_i2(A, m, p) #_________________________________________________________________ function _tframe1(f, p, p0, p1, p2, p3, A) { - ############################# if (_isptr(p)) { if (isarray(f)) { return _tframe1_i0(f, p, p0) @@ -6049,7 +6167,6 @@ function _tframe1_i2(A, m, p, p0) #_________________________________________________________________ function _tframe2(f, p, p0, p1, p2, p3, A) { - ############################# if (_isptr(p)) { if (isarray(f)) { return _tframe2_i0(f, p, p0, p1) @@ -6105,7 +6222,6 @@ function _tframe2_i2(A, m, p, p0, p1) #_________________________________________________________________ function _tframe3(f, p, p0, p1, p2, p3, A) { - ############################# if (_isptr(p)) { if (isarray(f)) { return _tframe3_i0(f, p, p0, p1, p2) @@ -6161,7 +6277,6 @@ function _tframe3_i2(A, m, p, p0, p1, p2) #_________________________________________________________________ function _tframe4(f, p, p0, p1, p2, p3, A) { - ############################# if (_isptr(p)) { if (isarray(f)) { return _tframe4_i0(f, p, p0, p1, p2, p3) @@ -6235,7 +6350,6 @@ function _tframe_i1(F, p, p0, p1, p2, a) #_______________________________________________________________________ function _tframex(f, p, p0, p1) { - ############################################ delete _t_ENDF[++_t_ENDF[0]] f = (p ? _tframex_i0(f, p, p0, p1) : "") --_t_ENDF[0] @@ -6347,7 +6461,6 @@ function _tgenuid_init(a, b, A) #_______________________________________________________________________ function _tgetitem(p, n, a, b) { - ############################################ if (p) { if (isarray(_PTR[p]["ITEM"]) && n in _PTR[p]["ITEM"]) { a = _PTR[p]["ITEM"][n] @@ -6366,7 +6479,6 @@ function _tgetitem(p, n, a, b) #_________________________________________________________________ function _tgetsp(p) { - ############################################### return _tSTACK[p][0] } @@ -6378,28 +6490,24 @@ function _th0(p, p1, p2, p3) return p } -########################################## #_________________________________________________________________ function _th1(p0, p, p2, p3) { return p } -############################## #_________________________________________________________________ function _th10(p0, p1) { return (p1 p0) } -############################## #_________________________________________________________________ function _th2(p0, p1, r, p3) { return p } -############################## #_________________________________________________________________ function _th3(p0, p1, p2, r) { @@ -6409,7 +6517,6 @@ function _th3(p0, p1, p2, r) #_________________________________________________________________ function _tifend(l) { - ############################################### return ((_t_ENDF[0] + l in _t_ENDF ? (_t_ENDF[_t_ENDF[0] + l] ? _t_ENDF[_t_ENDF[0] + l] : 1) : "")) } @@ -6579,7 +6686,6 @@ function _tlist_i1(L, p) #_________________________________________________________________ function _tmbframe(f, p, p0, p1, t) { - ################################## while (p && ! (_t_ENDF[0] in _t_ENDF)) { t = t _tbframe_i0(f, p, p0, p1, p = (p in _tPREV ? _tPREV[p] : "")) } @@ -6589,7 +6695,6 @@ function _tmbframe(f, p, p0, p1, t) #_________________________________________________________________ function _tmbframex(f, p, p0, p1, t) { - ################################# while (p && ! (_t_ENDF[0] in _t_ENDF)) { t = t _tbframex_i0(f, p, p0, p1) p = (p in _tPREV ? _tPREV[p] : "") @@ -6600,7 +6705,6 @@ function _tmbframex(f, p, p0, p1, t) #_________________________________________________________________ function _tmbpass(f, p, p0, p1) { - ###################################### while (p && ! (_t_ENDF[0] in _t_ENDF)) { p0 = _tbpass_i0(f, p, p0, p1, p = (p in _tPREV ? _tPREV[p] : "")) } @@ -6610,7 +6714,6 @@ function _tmbpass(f, p, p0, p1) #_________________________________________________________________ function _tmbpassx(f, p, p0, p1) { - ##################################### while (p && ! (_t_ENDF[0] in _t_ENDF)) { p0 = _tbpassx_i0(f, p, p0, p1) p = (p in _tPREV ? _tPREV[p] : "") @@ -6621,7 +6724,6 @@ function _tmbpassx(f, p, p0, p1) #_________________________________________________________________ function _tmframe(f, p, p0, p1, p2) { - ################################### delete _t_ENDF[++_t_ENDF[0]] f = (p ? _tmframe_i0(f, p, p0, p1, p2) : "") --_t_ENDF[0] @@ -6649,7 +6751,6 @@ function _tmframe_i1(F, p, p0, p1, p2, t) #_________________________________________________________________ function _tmframex(f, p, p0, p1, t) { - ################################## while (p && ! (_t_ENDF[0] in _t_ENDF)) { t = t _tframex_i0(f, p, p0, p1) p = (p in _tNEXT ? _tNEXT[p] : "") @@ -6660,7 +6761,6 @@ function _tmframex(f, p, p0, p1, t) #_________________________________________________________________ function _tmpass(f, p, p0, p1) { - ####################################### while (p && ! (_t_ENDF[0] in _t_ENDF)) { p0 = _tbpass_i0(f, p, p0, p1, p = (p in _tNEXT ? _tNEXT[p] : "")) } @@ -6670,7 +6770,6 @@ function _tmpass(f, p, p0, p1) #_________________________________________________________________ function _tmpassx(f, p, p0, p1) { - ###################################### while (p && ! (_t_ENDF[0] in _t_ENDF)) { p0 = _tbpassx_i0(f, p, p0, p1) p = (p in _tNEXT ? _tNEXT[p] : "") @@ -6714,7 +6813,6 @@ function _torexp_rexp(t) #_____________________________________________________________________________ function _tpass(f, p, p0, p1) { - #################################################### delete _t_ENDF[++_t_ENDF[0]] f = (p ? _tpass_i0(f, p, p0, p1) : "") --_t_ENDF[0] @@ -6733,7 +6831,6 @@ function _tpass_i0(f, p, p0, p1, a) #_____________________________________________________________________________ function _tpassx(f, p, p0, p1) { - ################################################### delete _t_ENDF[++_t_ENDF[0]] f = (p ? _tpassx_i0(f, p, p0, p1) : "") --_t_ENDF[0] @@ -6752,7 +6849,6 @@ function _tpassx_i0(f, p, p0, p1) #_________________________________________________________________ function _tpop(p, aA, a) { - ########################################### if ((a = _tSTACK[p][0]) > 0) { _tSTACK[p][0]-- if (isarray(_tSTACK[p][a])) { @@ -6768,7 +6864,6 @@ function _tpop(p, aA, a) #_____________________________________________________________________________ function _tpush(p, aA, a) { - ###################################################### if (isarray(aA)) { delete _tSTACK[p][a = ++_tSTACK[p][0]] _tSTACK[p][a][""] @@ -6807,7 +6902,6 @@ function _tr(n, cs, H) #_______________________________________________________________________ function _trace(t, d, A) { - ################################################# if (_ERRLOG_TF) { A["TYPE"] = "TRACE" A["TEXT"] = t @@ -6818,7 +6912,6 @@ function _trace(t, d, A) #_________________________________________________________________ function _trunframe(f, p, p0, p1, p2) { - ################################# return _tframe((f ? f : "_trunframe_i0"), p, p0, p1, p2) } @@ -6834,28 +6927,24 @@ function _trunframe_i0(p, p0, p1, p2, f) #_________________________________________________________________ function _trunframex(f, p, p0, p1) { - ################################### return _tframex((f ? f : "_trunframe_i0"), p, p0, p1) } #_________________________________________________________________ function _trunpass(f, p, p0, p1) { - ##################################### return _tpass((f ? f : "_trunframe_i0"), p, p0, p1) } #_________________________________________________________________ function _trunpassx(f, p, p0, p1) { - #################################### return _tpassx((f ? f : "_trunframe_i0"), p, p0, p1) } #_________________________________________________________________ function _tsetsp(p, v) { - ############################################# return (_tSTACK[p][0] = v) } @@ -7036,7 +7125,6 @@ function _typa(p, A) #_______________________________________________________________________ function _tzend(a, b) { - ##################################################### if (b == 0 && b == "") { return (_TEND[_TEND[_ARRLEN]] = a) } else { @@ -7176,7 +7264,6 @@ function _unstr(t) #_________________________________________________________________ function _untmp(f, a) { - ############################################# if (f = filepath(f)) { if (match(f, /\\$/)) { _deletepfx(_FILEIO_RDTMP, a = toupper(f)) @@ -7228,7 +7315,6 @@ function _var(v, t) #_______________________________________________________________________ function _verb(t, d, A) { - ################################################## if (_ERRLOG_VF) { A["TYPE"] = "VERB" A["TEXT"] = t @@ -7239,7 +7325,6 @@ function _verb(t, d, A) #_________________________________________________________________ function _wFBRO(p, v, a) { - ########################################### if (p) { if (v) { for (a = p; a in _tPARENT; ) { @@ -7247,7 +7332,6 @@ function _wFBRO(p, v, a) return v } } - ######################## v is parentesis of p if (p in _tPARENT) { p = _tPARENT[p] if (v in _tNEXT) { @@ -7346,19 +7430,15 @@ function _wFBRO(p, v, a) if (v == 0) { return v } - ######################## p=ptr, v=0 return v } } else { - ######################## p=ptr, v="" if (p == 0) { return v } - ######################## p=0 if (v) { return _texclude(v) } - ######################## p="", v=ptr - exclude v return v } } @@ -7366,19 +7446,16 @@ function _wFBRO(p, v, a) #_________________________________________________________________ function _wFCHLD(p, v, a) { - ########################################## if (p) { if (v) { if (p == v) { return v } - ######################## p=v=ptr for (a = p; a in _tPARENT; ) { if ((a = _tPARENT[a]) == v) { return v } } - ######################## v is parentesis of p if (v in _tNEXT) { if (v in _tPREV) { _tPREV[_tNEXT[a] = _tNEXT[v]] = a = _tPREV[v] @@ -7438,7 +7515,6 @@ function _wFCHLD(p, v, a) } else { if (v == 0) { if (p in _tFCHLD) { - ######################## p=ptr, v=0 > delete all chld v = _tFCHLD[p] delete _tFCHLD[p] delete _tLCHLD[p] @@ -7451,11 +7527,9 @@ function _wFCHLD(p, v, a) return v } } else { - ######################## p=ptr, v="" > ignore action if (p == 0) { return v } - ######################## p=0 return v } } @@ -7463,7 +7537,6 @@ function _wFCHLD(p, v, a) #_________________________________________________________________ function _wLBRO(p, v, a) { - ########################################### if (p) { if (v) { for (a = p; a in _tPARENT; ) { @@ -7471,7 +7544,6 @@ function _wLBRO(p, v, a) return v } } - ######################## v is parentesis of p if (p in _tPARENT) { p = _tPARENT[p] if (v in _tPREV) { @@ -7570,19 +7642,15 @@ function _wLBRO(p, v, a) if (v == 0) { return v } - ######################## p=ptr, v=0 return v } } else { - ######################## p=ptr, v="" if (p == 0) { return v } - ######################## p=0 if (v) { return _texclude(v) } - ######################## p="", v=ptr - exclude v return v } } @@ -7590,19 +7658,16 @@ function _wLBRO(p, v, a) #_________________________________________________________________ function _wLCHLD(p, v, a) { - ########################################## if (p) { if (v) { if (p == v) { return v } - ######################## p=v=ptr for (a = p; a in _tPARENT; ) { if ((a = _tPARENT[a]) == v) { return v } } - ######################## v is parentesis of p if (v in _tPREV) { if (v in _tNEXT) { _tNEXT[_tPREV[a] = _tPREV[v]] = a = _tNEXT[v] @@ -7662,7 +7727,6 @@ function _wLCHLD(p, v, a) } else { if (v == 0) { if (p in _tFCHLD) { - ######################## p=ptr, v=0 > delete all chld v = _tFCHLD[p] delete _tFCHLD[p] delete _tLCHLD[p] @@ -7675,11 +7739,9 @@ function _wLCHLD(p, v, a) return v } } else { - ######################## p=ptr, v="" > ignore action if (p == 0) { return v } - ######################## p=0 return v } } @@ -7687,26 +7749,22 @@ function _wLCHLD(p, v, a) #_________________________________________________________________ function _wLINK(p, v) { - ############################################## return (_tLINK[p] = v) } #_________________________________________________________________ function _wNEXT(p, v, a, b) { - ######################################### if (p) { if (v) { if (p == v) { return v } - ######################## p=v=ptr for (a = p; a in _tPARENT; ) { if ((a = _tPARENT[a]) == v) { return v } } - ######################## v is parentesis of p if (v in _tPREV) { if (p == (a = _tPREV[v])) { return v @@ -7759,19 +7817,15 @@ function _wNEXT(p, v, a, b) if (v == 0) { return v } - ######################## p=ptr, v=0 return v } } else { - ######################## p=ptr, v="" if (p == 0) { return v } - ######################## p=0 if (v) { return _texclude(v) } - ######################## p="", v=ptr - exclude v return v } } @@ -7779,26 +7833,22 @@ function _wNEXT(p, v, a, b) #_________________________________________________________________ function _wPARENT(p, v) { - ############################################ return v } #_________________________________________________________________ function _wPREV(p, v, a, b) { - ######################################### if (p) { if (v) { if (p == v) { return v } - ######################## p=v=ptr for (a = p; a in _tPARENT; ) { if ((a = _tPARENT[a]) == v) { return v } } - ######################## v is parentesis of p if (v in _tNEXT) { if (p == (a = _tNEXT[v])) { return v @@ -7851,19 +7901,15 @@ function _wPREV(p, v, a, b) if (v == 0) { return v } - ######################## p=ptr, v=0 return v } } else { - ######################## p=ptr, v="" if (p == 0) { return v } - ######################## p=0 if (v) { return _texclude(v) } - ######################## p="", v=ptr - exclude v return v } } @@ -7871,21 +7917,17 @@ function _wPREV(p, v, a, b) #_________________________________________________________________ function _wQBRO(p, v) { - ############################################## return v } #_________________________________________________________________ function _wQCHLD(p, v) { - ############################################# if (p) { if (v) { } else { - ######################## p=ptr, v=ptr if (v == 0) { if (p in _tFCHLD) { - ######################## p=ptr, v=0 > delete all chld v = _tFCHLD[p] delete _tFCHLD[p] delete _tLCHLD[p] @@ -7898,11 +7940,9 @@ function _wQCHLD(p, v) return v } } else { - ######################## p=ptr, v="" > ignore action if (p == 0) { return v } - ######################## p=0 return v } } @@ -7910,7 +7950,6 @@ function _wQCHLD(p, v) #_______________________________________________________________________ function _warning(t, d, A) { - ############################################### if (_ERRLOG_WF) { A["TYPE"] = "WARNING" A["TEXT"] = t @@ -7962,7 +8001,6 @@ function _wr_shortcut(f, S) #_________________________________________________________________ function _wrfile(f, d, a, b) { - ######################################### if ((f = _wfilerdnehnd(f)) == "" || _filene(f) == "") { ERRNO = "Filename error" return @@ -7988,7 +8026,6 @@ function _wrfile(f, d, a, b) #___________________________________________________________ function _wrfile1(f, d, a, b) { - ################################## if ((f = _wfilerdnehnd(f)) == "" || _filene(f) == "") { ERRNO = "Filename error" return @@ -8014,7 +8051,6 @@ function _wrfile1(f, d, a, b) #_______________________________________________________________________ function _yexport(p) { - ##################################################### return _tframe("_yexport_i0", p) } @@ -8035,7 +8071,6 @@ function _yexport_i0(p, p0, p1, p2) #_________________________________________________________________ function cmp_str_idx(i1, v1, i2, v2) { - ############################## return ((i1 < i2 ? -1 : 1)) } @@ -8190,7 +8225,6 @@ function hujf(a, b, c) #___________________________________________________________ function ncmp_str_idx(i1, v1, i2, v2) { - ####################### return ((i1 < i2 ? 1 : -1)) } @@ -8317,5 +8351,4 @@ function zorr(A, i, r) #_____________________________________________________________________________ function zzer() { - ################################################################ } diff --git a/test/sortglos.awk b/test/sortglos.awk new file mode 100755 index 00000000..e4f910d7 --- /dev/null +++ b/test/sortglos.awk @@ -0,0 +1,51 @@ +BEGIN { + pr="y"; + npre=0; + po="n"; + npos=0; + } + +pr=="y" { npre++; pre[npre]=$0; } +$1=="@table" && $2=="@asis" { pr="n";nite++; next; } + +po=="y" { npos++; pos[npos]=$0; } +$1=="@end" && $2=="table" { + po="y"; + npos++; + pos[npos]=$0; + # last item... + vec[nite]=nlin; +} + + { nite++; } + +END { + for ( i=1; i<=npre; i++ ) { print pre[i]; } + if ( srt=="y" ) { + n=asorti(entr,ital); + ##print "n=",n; + for ( i=1; i<=n; i++ ) { + #printf("=========> %3.3d %s\n",i,ital[i]); + # ital[i] is the sorted key; + j=entr[ital[i]]; + # j is the original item number + for ( k=1; k<=vec[j]; k++ ) { + print dat[j,k]; + } + } + } + if ( srt=="n" ) { + for ( i=1; i<=nite; i++ ) { + printf("=========> %3.3d %2.2d %s\n",i,vec[i],titl[i]); + for ( j=1; j<=vec[i]; j++ ) { + print dat[i,j]; + } + } + print "========================= END"; + } + for ( i=1; i<=npos; i++ ) { print pos[i]; } + print "@c npre=" npre; + print "@c nite=" nite; + print "@c npos=" npos; +} + diff --git a/test/sortglos.in b/test/sortglos.in new file mode 100755 index 00000000..b24373de --- /dev/null +++ b/test/sortglos.in @@ -0,0 +1,22 @@ +@node Glossario +@unnumbered Glossario + +@table @asis +@item Azione +Una serie di istruzioni @command{awk} associate a una regola. Se +l'espressione di ricerca della regola individua un record in input, +@command{awk} esegue su quel record l'azione relativa. Le azioni sono +sempre racchiuse fra parentesi graffe. +(@xref{Panoramica sulle azioni}). + +@item Spazio bianco +Una sequenza di spazi, TAB, o caratteri di "a capo" presenti in un record in +input o in una stringa. +@end table + +@end ifclear + +@c The GNU General Public License. + +@c aggiornato alla versione: settembre 2014 +@c ultimo aggiornamento: 14 novembre 2014 diff --git a/test/sortglos.ok b/test/sortglos.ok new file mode 100644 index 00000000..69ddbe67 --- /dev/null +++ b/test/sortglos.ok @@ -0,0 +1,15 @@ +@node Glossario +@unnumbered Glossario + +@table @asis +@end table + +@end ifclear + +@c The GNU General Public License. + +@c aggiornato alla versione: settembre 2014 +@c ultimo aggiornamento: 14 novembre 2014 +@c npre=4 +@c nite=22 +@c npos=8 |