diff options
| author | Arnold D. Robbins <arnold@skeeve.com> | 2014-10-13 11:27:13 +0300 |
|---|---|---|
| committer | Arnold D. Robbins <arnold@skeeve.com> | 2014-10-13 11:27:13 +0300 |
| commit | 0485d6bfe2417a7640ef95c9de6f48e1f35003fd (patch) | |
| tree | f26c8a24a4a12bf9be5038f40e6a20a4f6e9aa79 | |
| parent | 7504a8fbc86b327ad07c79c943b8fe2d253f256d (diff) | |
| parent | 2a8c128ca91b42261720368e5d25431ee4362c70 (diff) | |
| download | egawk-0485d6bfe2417a7640ef95c9de6f48e1f35003fd.tar.gz egawk-0485d6bfe2417a7640ef95c9de6f48e1f35003fd.tar.bz2 egawk-0485d6bfe2417a7640ef95c9de6f48e1f35003fd.zip | |
Merge branch 'master' into cmake
85 files changed, 17042 insertions, 12744 deletions
@@ -1,3 +1,239 @@ +2014-10-13 Arnold D. Robbins <arnold@skeeve.com> + + * regcomp.c (__re_error_msgid): Make error message for REG_EBRACK + more helpful - also used for unmatched [:, [., [=. + Thanks to Davide Brini for raising the issue. + +2014-10-12 Arnold D. Robbins <arnold@skeeve.com> + + * README: Remove Pat Rankin from VMS duties, per his request. + +2014-10-08 Arnold D. Robbins <arnold@skeeve.com> + + * dfa.c: Sync wit GNU grep. + +2014-10-05 Arnold D. Robbins <arnold@skeeve.com> + + * profile.c (pprint): Fix typo in header. Sheesh. + + Unrelated: + + * awkgram.y (mk_program): Add a comment that we don't need to + clear the comment* variables. + +2014-10-04 Arnold D. Robbins <arnold@skeeve.com> + + * profile.c (pp_string_fp): Fix breaklines case to actually + output the current letter. This broke at gawk 4.0.0. Sigh. + Thanks to Bert Bos (bert@w3.org) for the report. + +2014-10-03 Stephen Davies <sdavies@sdc.com.au> + + * awkgram.y (program_comment): Renamed from comment0. + (function_comment): Renamed from commentf. + +2014-10-02 Arnold D. Robbins <arnold@skeeve.com> + + * awkgram.y, profile.c: Minor white space cleanups. + +2014-10-01 Arnold D. Robbins <arnold@skeeve.com> + + Fix a few compile warnings: + + * awkgram.y (split_comment): Make static. + General: Remove some unused variables, clean up some whitepace nits. + + * profile.c (indent): Add some braces to turn off compiler warnings. + +2014-09-29 Andrew J. Schorr <aschorr@telemetry-investments.com> + + * main.c (main): In optlist, it should say "h", not "h:", since there + is no argument for the help option. Thanks to Joep van Delft for + the bug report. + +2014-09-29 Arnold D. Robbins <arnold@skeeve.com> + + * gawkapi.h: Minor edits to sync with documentation. Does not + influence the behavior of the API. + +2014-09-28 Arnold D. Robbins <arnold@skeeve.com> + + * command.y (cmdtab): Add "where" as an alias for "backtrace". + Finally! + + Unrelated: + + * dfa.c: Sync with GNU grep. + +2014-09-27 Arnold D. Robbins <arnold@skeeve.com> + + * awkgram.y (check_for_bad): Bitwise-and the bad character with 0xFF + to avoid sign extension into a large integer. + + Unrelated: + + * configure.ac: Add an option to enable locale letters in identifiers. + Undocumented and subject to being rescinded at any time in the future. + * NEWS: Mention to look at configure --help. + + Unrelated: + + * profile.c (pprint): Use "rule(s)" instead of "block(s)" in the + header. + +2014-09-23 Arnold D. Robbins <arnold@skeeve.com> + + * awkgram.y (yylex): Don't check for junk characters inside + quoted strings. Caused issues on DJGPP and Solaris. + + Unrelated: + + * io.c (devopen): Straighten things out with respect to + compatibility with BWK awk. + +2014-09-19 Arnold D. Robbins <arnold@skeeve.com> + + * awkgram.y: Further commentary as to the treacherousness + of isalnum and isalpha. + +2014-09-15 Arnold D. Robbins <arnold@skeeve.com> + + Finish removing use of isalpha and isalnum. + + * awk.h (is_alpha, is_alnum, is_identchar): Add declarations. + * awkgram.y (yylex): Use is_alpha. + (is_alpha, is_alnum): New functions. + (is_identchar): Use is_alnum. + * builtin.c (r_format_tree): Use is_alpha, is_alnum. + * command.y (yylex): Use is_alpha, is_identchar. + * ext.c (is_letter): Use is_alpha. + (is_identifier_char): Removed; replaced uses with is_identchar. + * main.c (arg_assign): Use is_alpha, is_alnum. + * node.c (r_force_number): Use is_alpha. + +2014-09-14 Arnold D. Robbins <arnold@skeeve.com> + + * awkgram.y (is_identchar): Change from simple macro to function + since use of isalnum() let non-ASCII letters slip through into + identifiers. + +2014-09-13 Stephen Davies <sdavies@sdc.com.au> + + When doing pretty-printing (but not profiling), include the original + comments in the output. + + General rules: + + Pretty printing: + - Do NOT indent by a tab + - Do NOT print the header comments ("# BEGIN rules", etc.) + - DO print the comments that are in the program + + Profiling: + - DO indent by a tab + - DO print the header comments + - Do NOT print the program's original comments + + * awkgram.y (comment0, commentf): New varibles that are pointers to + program and function comments. + (get_comment): New function that retrieves consecutive comment lines + and empty lines as a unit). + (split_comment): New function: iff first block in the program is a + function and it is predeeded by comments, take the last non-blank + line as function comment and any preceeding lines as program comment.) + + Following token rules were changed to handle comments: + + * awkgram.y (pattern, LEX_BEGIN, LEX_END, LEX_BEGINFILE, LEX_ENDFILE, + action, function_prologue, statements): Update to handle comments. + + Following functions were changed to handle comments: + + * awkgram.y (mk_program, mk_function, allow_newline and yylex): Update + to handle comments. (Also fixed typo in case '\\'.) + + * profile.c (print_comment): New function to format comment printing. + (indent, pprint, dump_prog, pp_func): Changed to handle comments and + the revised indentation rules. + +2014-09-07 Arnold D. Robbins <arnold@skeeve.com> + + * awk.h: Move libsigsegv stuff to ... + * main.c: here. Thanks to Yehezkel Bernat for motivating + the cleanup. + * symbol.c (make_symbol, install, install_symbol): Add const to + first parameter. Adjust decls and fix up uses. + +2014-09-05 Arnold D. Robbins <arnold@skeeve.com> + + Add builtin functions to FUNCTAB for consistency. + + * awk.h (Node_builtin_func): New node type. + (install_builtins): Declare new function. + * awkgram.y [DEBUG_USE]: New flag value for debug functions; they + don't go into FUNCTAB. + (install_builtins): New function. + * eval.c (nodetypes): Add Node_builtin_func. + * interpret.h (r_interpret): Rework indirect calls of built-ins + since they're now in the symbol table. + * main.c (main): Call `install_builtins'. + * symbol.c (install): Adjust for Node_builtin_func. + (load_symbols): Ditto. + +2014-09-04 Arnold D. Robbins <arnold@skeeve.com> + + * profile.c (pprint): Case Op_K_for: Improve printing of + empty for loop header. + + Unrelated: Make indirect function calls work for built-in and + extension functions. + + * awkgram.y (lookup_builtin): New function. + * awk.h (builtin_func_t): New typedef. + (lookup_builtin): Declare it. + * interpret.h (r_interpret): For indirect calls, add code to + find and call builtin functions, and call extension functions. + +2014-09-01 Arnold D. Robbins <arnold@skeeve.com> + + * builtin.c (do_substr): Return "" instead of null string in case + result is passed to length() with --lint. Based on discussions in + comp.lang.awk. + + Unrelated: + + * interpret.h (r_interpret): For indirect function call, separate + error message if lookup returned NULL. Otherwise got a core dump. + Thanks to "Kenny McKormack" for the report in comp.lang.awk. + +2014-08-27 Arnold D. Robbins <arnold@skeeve.com> + + * configure.ac: Add test for strcasecmp. + * regcomp.c: Remove special case code around use of strcasecmp(). + * replace.c: Include missing/strncasecmp.c if either strcasecmp() + or strncasecmp() aren't available. + +2014-08-26 Arnold D. Robbins <arnold@skeeve.com> + + * regcomp.c, regex_internal.c: Sync with GBLIC. Why not. + + Unrelated: + + Remove support for MirBSD. It uglified the code too much + for no discernable gain. + + * configure.ac: Remove check for MirBSD and define of + LIBC_IS_BORKED. + * dfa.c: Remove code depending on LIBC_IS_BORKED. + * main.c: Ditto. + * regcomp.c: Ditto. + * NEWS: Updated. + +2014-08-24 Arnold D. Robbins <arnold@skeeve.com> + + * regex.h: Remove underscores in names of parameters in function + declarations. Tweak names as neeeded. + 2014-08-20 Arnold D. Robbins <arnold@skeeve.com> * node.c (parse_escape): Max of 2 digits after \x. @@ -827,6 +1063,24 @@ * debug.c (print_memory): Fix whitespace / indentation. +2013-08-02 Arnold D. Robbins <arnold@skeeve.com> + + * awkgram.y (append_rule): Add attempt to insert any comment + before a rule. Commented out at the moment. + +2013-07-30 Arnold D. Robbins <arnold@skeeve.com> + + * awk.h (enum opcodeval): Add Op_comment. + * awkgram.y (comment): New variable to hold comment text. + (statement): Add saved comments to lists being built. + (allow_newline): Save comment text if necessary. Append if have + existing text. + (yylex): Ditto. + * debug.c (print_instruction): Handle Op_comment. + * eval.c (optypes): Add entry for Op_comment. + * interpret.h (r_interpret): Ditto. + * profile.c (pprint): For Op_comment, print the comment text. + 2013-07-24 Arnold D. Robbins <arnold@skeeve.com> * io.c (FAKE_FD_VALUE): Move definition from here ... @@ -32,6 +32,11 @@ Changes from 4.1.x to 4.2.0 7. Gawk now processes a maximum of two hexadecimal digits in \x escape sequences inside strings. +8. MirBSD is no longer supported. + +9. Pretty printing now preserves comments and places them into the + pretty-printed file. + Changes from 4.1.1 to 4.1.2 --------------------------- @@ -48,6 +53,19 @@ Changes from 4.1.1 to 4.1.2 4. A number of bugs have been fixed in the MPFR code. +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" + 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 + for "backtrace". This will make life easier for long-time GDB users. + XX. A number of bugs have been fixed. See the ChangeLog. Changes from 4.1.0 to 4.1.1 @@ -91,9 +91,6 @@ OS/2: andreas.buening@nexgo.de VMS: - Pat Rankin - r.pat.rankin@gmail.com - John Malmberg wb8tyw@qsl.net @@ -1,13 +1,9 @@ -Wed Jun 25 22:28:05 IDT 2014 +Sun Sep 28 22:19:10 IDT 2014 ============================ There were too many files tracking different thoughts and ideas for things to do, or consider doing. This file merges them into one. As -tasks are completed, they should be moved to the DONE section, below, -or simply removed. - -Upon creation of a release (major or patch release), items from the -previous release should be removed. +tasks are completed, they should be removed. This file should exist only in the master branch or branches based off of it for development, but not in the stable branch. This may require some @@ -23,9 +19,6 @@ Minor Cleanups and Code Improvements order to nuke the use of libtool. [ Partially started in the nolibtool branch. ] - Enhance profiling to save comments in a byte-code that does nothing - but that can be used when pretty printing the program. - API: ??? #if !defined(GAWK) && !defined(GAWK_OMIT_CONVENIENCE_MACROS) @@ -33,8 +26,6 @@ Minor Cleanups and Code Improvements Look at function order within files. - regex.h - remove underscores in param names - Consider removing use of and/or need for the protos.h file. Recheck if gnulib regex can be dropped in @@ -45,6 +36,8 @@ Minor Cleanups and Code Improvements Minor New Features ------------------ + Enable command line source text in the debugger. + Enhance extension/fork.c waitpid to allow the caller to specify the options. And add an optional array argument to wait and waitpid in which to return exit status information. @@ -148,18 +141,6 @@ Things To Think About That May Never Happen E.g., a length of 0 or -1 or something. Maybe "n"? -DONE -==== - -Minor Cleanups and Code Improvements ------------------------------------- - -Minor New Features ------------------- - -Major New Features ------------------- - Things That We Decided We Will Never Do ======================================= @@ -193,15 +193,6 @@ extern void *memset_ulong(void *dest, int val, unsigned long l); #define memset memset_ulong #endif -#ifdef HAVE_LIBSIGSEGV -#include <sigsegv.h> -#else -typedef void *stackoverflow_context_t; -#define sigsegv_install_handler(catchsegv) signal(SIGSEGV, catchsig) -/* define as 0 rather than empty so that (void) cast on it works */ -#define stackoverflow_install_handler(catchstackoverflow, extra_stack, STACK_SIZE) 0 -#endif - #if defined(__EMX__) || defined(__MINGW32__) #include "nonposix.h" #endif /* defined(__EMX__) || defined(__MINGW32__) */ @@ -297,6 +288,7 @@ typedef enum nodevals { Node_func, /* lnode is param. list, rnode is body */ Node_ext_func, /* extension function, code_ptr is builtin code */ Node_old_ext_func, /* extension function, code_ptr is builtin code */ + Node_builtin_func, /* built-in function, main use is for FUNCTAB */ Node_array_ref, /* array passed by ref as parameter */ Node_array_tree, /* Hashed array tree (HAT) */ @@ -676,6 +668,7 @@ typedef enum opcodeval { Op_func, + Op_comment, /* for pretty printing */ Op_exec_count, Op_breakpoint, Op_lint, @@ -1378,6 +1371,12 @@ extern void register_deferred_variable(const char *name, NODE *(*load_func)(void extern int files_are_same(char *path, SRCFILE *src); extern void valinfo(NODE *n, Func_print print_func, FILE *fp); extern void negate_num(NODE *n); +typedef NODE *(*builtin_func_t)(int); /* function that implements a built-in */ +extern builtin_func_t lookup_builtin(const char *name); +extern void install_builtins(void); +extern bool is_alpha(int c); +extern bool is_alnum(int c); +extern bool is_identchar(int c); /* builtin.c */ extern double double_to_int(double d); extern NODE *do_exp(int nargs); @@ -1641,7 +1640,7 @@ extern void load_symbols(); extern void init_symbol_table(); extern NODE *symbol_table; extern NODE *func_table; -extern NODE *install_symbol(char *name, NODETYPE type); +extern NODE *install_symbol(const char *name, NODETYPE type); extern NODE *remove_symbol(NODE *r); extern void destroy_symbol(NODE *r); extern void release_symbols(NODE *symlist, int keep_globals); @@ -127,6 +127,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 bool want_source = false; static bool want_regexp = false; /* lexical scanning kludge */ @@ -186,6 +187,12 @@ static INSTRUCTION *ip_end; static INSTRUCTION *ip_endfile; static INSTRUCTION *ip_beginfile; +static INSTRUCTION *comment = NULL; +static INSTRUCTION *program_comment = NULL; +static INSTRUCTION *function_comment = NULL; + +static bool func_first = true; + static inline INSTRUCTION *list_create(INSTRUCTION *x); static inline INSTRUCTION *list_append(INSTRUCTION *l, INSTRUCTION *x); static inline INSTRUCTION *list_prepend(INSTRUCTION *l, INSTRUCTION *x); @@ -195,9 +202,7 @@ extern double fmod(double x, double y); #define YYSTYPE INSTRUCTION * -#define is_identchar(c) (isalnum(c) || (c) == '_') - -#line 201 "awkgram.c" /* yacc.c:339 */ +#line 206 "awkgram.c" /* yacc.c:339 */ # ifndef YY_NULLPTR # if defined __cplusplus && 201103L <= __cplusplus @@ -351,7 +356,7 @@ int yyparse (void); /* Copy the second part of user declarations. */ -#line 355 "awkgram.c" /* yacc.c:358 */ +#line 360 "awkgram.c" /* yacc.c:358 */ #ifdef short # undef short @@ -653,25 +658,25 @@ static const yytype_uint8 yytranslate[] = /* YYRLINE[YYN] -- Source line where rule number YYN was defined. */ static const yytype_uint16 yyrline[] = { - 0, 200, 200, 202, 207, 208, 214, 226, 230, 241, - 247, 252, 260, 268, 270, 275, 283, 285, 291, 292, - 294, 320, 331, 342, 348, 357, 367, 369, 371, 377, - 382, 383, 387, 406, 405, 439, 441, 446, 447, 460, - 465, 466, 470, 472, 474, 481, 571, 613, 655, 768, - 775, 782, 792, 801, 810, 819, 830, 846, 845, 869, - 881, 881, 979, 979, 1012, 1042, 1048, 1049, 1055, 1056, - 1063, 1068, 1080, 1094, 1096, 1104, 1109, 1111, 1119, 1121, - 1130, 1131, 1139, 1144, 1144, 1155, 1159, 1167, 1168, 1171, - 1173, 1178, 1179, 1188, 1189, 1194, 1199, 1205, 1207, 1209, - 1216, 1217, 1223, 1224, 1229, 1231, 1236, 1238, 1246, 1251, - 1260, 1267, 1269, 1271, 1287, 1297, 1304, 1306, 1311, 1313, - 1315, 1323, 1325, 1330, 1332, 1337, 1339, 1341, 1391, 1393, - 1395, 1397, 1399, 1401, 1403, 1405, 1419, 1424, 1429, 1454, - 1460, 1462, 1464, 1466, 1468, 1470, 1475, 1479, 1511, 1513, - 1519, 1525, 1538, 1539, 1540, 1545, 1550, 1554, 1558, 1573, - 1586, 1591, 1627, 1645, 1646, 1652, 1653, 1658, 1660, 1667, - 1684, 1701, 1703, 1710, 1715, 1723, 1733, 1745, 1754, 1758, - 1762, 1766, 1770, 1774, 1777, 1779, 1783, 1787, 1791 + 0, 205, 205, 207, 212, 213, 219, 231, 235, 246, + 252, 257, 265, 273, 275, 280, 288, 290, 296, 304, + 314, 340, 353, 366, 373, 383, 395, 397, 399, 405, + 410, 411, 415, 450, 449, 483, 485, 490, 496, 524, + 529, 530, 534, 536, 538, 545, 635, 677, 719, 832, + 839, 846, 856, 865, 874, 883, 894, 910, 909, 933, + 945, 945, 1043, 1043, 1076, 1106, 1112, 1113, 1119, 1120, + 1127, 1132, 1144, 1158, 1160, 1168, 1173, 1175, 1183, 1185, + 1194, 1195, 1203, 1208, 1208, 1219, 1223, 1231, 1232, 1235, + 1237, 1242, 1243, 1252, 1253, 1258, 1263, 1269, 1271, 1273, + 1280, 1281, 1287, 1288, 1293, 1295, 1300, 1302, 1310, 1315, + 1324, 1331, 1333, 1335, 1351, 1361, 1368, 1370, 1375, 1377, + 1379, 1387, 1389, 1394, 1396, 1401, 1403, 1405, 1455, 1457, + 1459, 1461, 1463, 1465, 1467, 1469, 1483, 1488, 1493, 1518, + 1524, 1526, 1528, 1530, 1532, 1534, 1539, 1543, 1575, 1577, + 1583, 1589, 1602, 1603, 1604, 1609, 1614, 1618, 1622, 1637, + 1650, 1655, 1691, 1709, 1710, 1716, 1717, 1722, 1724, 1731, + 1748, 1765, 1767, 1774, 1779, 1787, 1797, 1809, 1818, 1822, + 1826, 1830, 1834, 1838, 1841, 1843, 1847, 1851, 1855 }; #endif @@ -1844,26 +1849,26 @@ yyreduce: switch (yyn) { case 3: -#line 203 "awkgram.y" /* yacc.c:1646 */ +#line 208 "awkgram.y" /* yacc.c:1646 */ { rule = 0; yyerrok; } -#line 1853 "awkgram.c" /* yacc.c:1646 */ +#line 1858 "awkgram.c" /* yacc.c:1646 */ break; case 5: -#line 209 "awkgram.y" /* yacc.c:1646 */ +#line 214 "awkgram.y" /* yacc.c:1646 */ { next_sourcefile(); if (sourcefile == srcfiles) process_deferred(); } -#line 1863 "awkgram.c" /* yacc.c:1646 */ +#line 1868 "awkgram.c" /* yacc.c:1646 */ break; case 6: -#line 215 "awkgram.y" /* yacc.c:1646 */ +#line 220 "awkgram.y" /* yacc.c:1646 */ { rule = 0; /* @@ -1872,19 +1877,19 @@ yyreduce: */ /* yyerrok; */ } -#line 1876 "awkgram.c" /* yacc.c:1646 */ +#line 1881 "awkgram.c" /* yacc.c:1646 */ break; case 7: -#line 227 "awkgram.y" /* yacc.c:1646 */ +#line 232 "awkgram.y" /* yacc.c:1646 */ { (void) append_rule((yyvsp[-1]), (yyvsp[0])); } -#line 1884 "awkgram.c" /* yacc.c:1646 */ +#line 1889 "awkgram.c" /* yacc.c:1646 */ break; case 8: -#line 231 "awkgram.y" /* yacc.c:1646 */ +#line 236 "awkgram.y" /* yacc.c:1646 */ { if (rule != Rule) { msg(_("%s blocks must have an action part"), ruletab[rule]); @@ -1895,39 +1900,39 @@ yyreduce: } else /* pattern rule with non-empty pattern */ (void) append_rule((yyvsp[-1]), NULL); } -#line 1899 "awkgram.c" /* yacc.c:1646 */ +#line 1904 "awkgram.c" /* yacc.c:1646 */ break; case 9: -#line 242 "awkgram.y" /* yacc.c:1646 */ +#line 247 "awkgram.y" /* yacc.c:1646 */ { in_function = NULL; (void) mk_function((yyvsp[-1]), (yyvsp[0])); yyerrok; } -#line 1909 "awkgram.c" /* yacc.c:1646 */ +#line 1914 "awkgram.c" /* yacc.c:1646 */ break; case 10: -#line 248 "awkgram.y" /* yacc.c:1646 */ +#line 253 "awkgram.y" /* yacc.c:1646 */ { want_source = false; yyerrok; } -#line 1918 "awkgram.c" /* yacc.c:1646 */ +#line 1923 "awkgram.c" /* yacc.c:1646 */ break; case 11: -#line 253 "awkgram.y" /* yacc.c:1646 */ +#line 258 "awkgram.y" /* yacc.c:1646 */ { want_source = false; yyerrok; } -#line 1927 "awkgram.c" /* yacc.c:1646 */ +#line 1932 "awkgram.c" /* yacc.c:1646 */ break; case 12: -#line 261 "awkgram.y" /* yacc.c:1646 */ +#line 266 "awkgram.y" /* yacc.c:1646 */ { if (include_source((yyvsp[0])) < 0) YYABORT; @@ -1935,23 +1940,23 @@ yyreduce: bcfree((yyvsp[0])); (yyval) = NULL; } -#line 1939 "awkgram.c" /* yacc.c:1646 */ +#line 1944 "awkgram.c" /* yacc.c:1646 */ break; case 13: -#line 269 "awkgram.y" /* yacc.c:1646 */ +#line 274 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 1945 "awkgram.c" /* yacc.c:1646 */ +#line 1950 "awkgram.c" /* yacc.c:1646 */ break; case 14: -#line 271 "awkgram.y" /* yacc.c:1646 */ +#line 276 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 1951 "awkgram.c" /* yacc.c:1646 */ +#line 1956 "awkgram.c" /* yacc.c:1646 */ break; case 15: -#line 276 "awkgram.y" /* yacc.c:1646 */ +#line 281 "awkgram.y" /* yacc.c:1646 */ { if (load_library((yyvsp[0])) < 0) YYABORT; @@ -1959,35 +1964,49 @@ yyreduce: bcfree((yyvsp[0])); (yyval) = NULL; } -#line 1963 "awkgram.c" /* yacc.c:1646 */ +#line 1968 "awkgram.c" /* yacc.c:1646 */ break; case 16: -#line 284 "awkgram.y" /* yacc.c:1646 */ +#line 289 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 1969 "awkgram.c" /* yacc.c:1646 */ +#line 1974 "awkgram.c" /* yacc.c:1646 */ break; case 17: -#line 286 "awkgram.y" /* yacc.c:1646 */ +#line 291 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 1975 "awkgram.c" /* yacc.c:1646 */ +#line 1980 "awkgram.c" /* yacc.c:1646 */ break; case 18: -#line 291 "awkgram.y" /* yacc.c:1646 */ - { (yyval) = NULL; rule = Rule; } -#line 1981 "awkgram.c" /* yacc.c:1646 */ +#line 296 "awkgram.y" /* yacc.c:1646 */ + { + rule = Rule; + if (comment != NULL) { + (yyval) = list_create(comment); + comment = NULL; + } else + (yyval) = NULL; + } +#line 1993 "awkgram.c" /* yacc.c:1646 */ break; case 19: -#line 293 "awkgram.y" /* yacc.c:1646 */ - { (yyval) = (yyvsp[0]); rule = Rule; } -#line 1987 "awkgram.c" /* yacc.c:1646 */ +#line 305 "awkgram.y" /* yacc.c:1646 */ + { + rule = Rule; + if (comment != NULL) { + (yyval) = list_prepend((yyvsp[0]), comment); + comment = NULL; + } else + (yyval) = (yyvsp[0]); + } +#line 2006 "awkgram.c" /* yacc.c:1646 */ break; case 20: -#line 295 "awkgram.y" /* yacc.c:1646 */ +#line 315 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *tp; @@ -2013,13 +2032,15 @@ yyreduce: (yyval) = list_append(list_merge((yyvsp[-3]), (yyvsp[0])), tp); rule = Rule; } -#line 2017 "awkgram.c" /* yacc.c:1646 */ +#line 2036 "awkgram.c" /* yacc.c:1646 */ break; case 21: -#line 321 "awkgram.y" /* yacc.c:1646 */ +#line 341 "awkgram.y" /* yacc.c:1646 */ { static int begin_seen = 0; + + func_first = false; if (do_lint_old && ++begin_seen == 2) warning_ln((yyvsp[0])->source_line, _("old awk does not support multiple `BEGIN' or `END' rules")); @@ -2028,13 +2049,15 @@ yyreduce: (yyvsp[0])->source_file = source; (yyval) = (yyvsp[0]); } -#line 2032 "awkgram.c" /* yacc.c:1646 */ +#line 2053 "awkgram.c" /* yacc.c:1646 */ break; case 22: -#line 332 "awkgram.y" /* yacc.c:1646 */ +#line 354 "awkgram.y" /* yacc.c:1646 */ { static int end_seen = 0; + + func_first = false; if (do_lint_old && ++end_seen == 2) warning_ln((yyvsp[0])->source_line, _("old awk does not support multiple `BEGIN' or `END' rules")); @@ -2043,71 +2066,91 @@ yyreduce: (yyvsp[0])->source_file = source; (yyval) = (yyvsp[0]); } -#line 2047 "awkgram.c" /* yacc.c:1646 */ +#line 2070 "awkgram.c" /* yacc.c:1646 */ break; case 23: -#line 343 "awkgram.y" /* yacc.c:1646 */ +#line 367 "awkgram.y" /* yacc.c:1646 */ { + func_first = false; (yyvsp[0])->in_rule = rule = BEGINFILE; (yyvsp[0])->source_file = source; (yyval) = (yyvsp[0]); } -#line 2057 "awkgram.c" /* yacc.c:1646 */ +#line 2081 "awkgram.c" /* yacc.c:1646 */ break; case 24: -#line 349 "awkgram.y" /* yacc.c:1646 */ +#line 374 "awkgram.y" /* yacc.c:1646 */ { + func_first = false; (yyvsp[0])->in_rule = rule = ENDFILE; (yyvsp[0])->source_file = source; (yyval) = (yyvsp[0]); } -#line 2067 "awkgram.c" /* yacc.c:1646 */ +#line 2092 "awkgram.c" /* yacc.c:1646 */ break; case 25: -#line 358 "awkgram.y" /* yacc.c:1646 */ +#line 384 "awkgram.y" /* yacc.c:1646 */ { + INSTRUCTION *ip; if ((yyvsp[-3]) == NULL) - (yyval) = list_create(instruction(Op_no_op)); + ip = list_create(instruction(Op_no_op)); else - (yyval) = (yyvsp[-3]); + ip = (yyvsp[-3]); + (yyval) = ip; } -#line 2078 "awkgram.c" /* yacc.c:1646 */ +#line 2105 "awkgram.c" /* yacc.c:1646 */ break; case 26: -#line 368 "awkgram.y" /* yacc.c:1646 */ +#line 396 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2084 "awkgram.c" /* yacc.c:1646 */ +#line 2111 "awkgram.c" /* yacc.c:1646 */ break; case 27: -#line 370 "awkgram.y" /* yacc.c:1646 */ +#line 398 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2090 "awkgram.c" /* yacc.c:1646 */ +#line 2117 "awkgram.c" /* yacc.c:1646 */ break; case 28: -#line 372 "awkgram.y" /* yacc.c:1646 */ +#line 400 "awkgram.y" /* yacc.c:1646 */ { yyerror(_("`%s' is a built-in function, it cannot be redefined"), tokstart); YYABORT; } -#line 2100 "awkgram.c" /* yacc.c:1646 */ +#line 2127 "awkgram.c" /* yacc.c:1646 */ break; case 29: -#line 378 "awkgram.y" /* yacc.c:1646 */ +#line 406 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2106 "awkgram.c" /* yacc.c:1646 */ +#line 2133 "awkgram.c" /* yacc.c:1646 */ break; case 32: -#line 388 "awkgram.y" /* yacc.c:1646 */ +#line 416 "awkgram.y" /* yacc.c:1646 */ { + /* + * treat any comments between BOF and the first function + * definition (with no intervening BEGIN etc block) as + * program comments. Special kludge: iff there are more + * than one such comments, treat the last as a function + * comment. + */ + if (comment != NULL && func_first + && strstr(comment->memory->stptr, "\n\n") != NULL) + split_comment(); + /* save any other pre-function comment as function comment */ + if (comment != NULL) { + function_comment = comment; + comment = NULL; + } + func_first = false; (yyvsp[-5])->source_file = source; if (install_function((yyvsp[-4])->lextok, (yyvsp[-5]), (yyvsp[-2])) < 0) YYABORT; @@ -2117,17 +2160,17 @@ yyreduce: /* $4 already free'd in install_function */ (yyval) = (yyvsp[-5]); } -#line 2121 "awkgram.c" /* yacc.c:1646 */ +#line 2164 "awkgram.c" /* yacc.c:1646 */ break; case 33: -#line 406 "awkgram.y" /* yacc.c:1646 */ +#line 450 "awkgram.y" /* yacc.c:1646 */ { want_regexp = true; } -#line 2127 "awkgram.c" /* yacc.c:1646 */ +#line 2170 "awkgram.c" /* yacc.c:1646 */ break; case 34: -#line 408 "awkgram.y" /* yacc.c:1646 */ +#line 452 "awkgram.y" /* yacc.c:1646 */ { NODE *n, *exp; char *re; @@ -2156,69 +2199,89 @@ yyreduce: (yyval)->opcode = Op_match_rec; (yyval)->memory = n; } -#line 2160 "awkgram.c" /* yacc.c:1646 */ +#line 2203 "awkgram.c" /* yacc.c:1646 */ break; case 35: -#line 440 "awkgram.y" /* yacc.c:1646 */ +#line 484 "awkgram.y" /* yacc.c:1646 */ { bcfree((yyvsp[0])); } -#line 2166 "awkgram.c" /* yacc.c:1646 */ +#line 2209 "awkgram.c" /* yacc.c:1646 */ break; case 37: -#line 446 "awkgram.y" /* yacc.c:1646 */ - { (yyval) = NULL; } -#line 2172 "awkgram.c" /* yacc.c:1646 */ +#line 490 "awkgram.y" /* yacc.c:1646 */ + { + if (comment != NULL) { + (yyval) = list_create(comment); + comment = NULL; + } else (yyval) = NULL; + } +#line 2220 "awkgram.c" /* yacc.c:1646 */ break; case 38: -#line 448 "awkgram.y" /* yacc.c:1646 */ +#line 497 "awkgram.y" /* yacc.c:1646 */ { - if ((yyvsp[0]) == NULL) - (yyval) = (yyvsp[-1]); - else { + if ((yyvsp[0]) == NULL) { + if (comment == NULL) + (yyval) = (yyvsp[-1]); + else { + (yyval) = list_append((yyvsp[-1]), comment); + comment = NULL; + } + } else { add_lint((yyvsp[0]), LINT_no_effect); - if ((yyvsp[-1]) == NULL) - (yyval) = (yyvsp[0]); - else + if ((yyvsp[-1]) == NULL) { + if (comment == NULL) + (yyval) = (yyvsp[0]); + else { + (yyval) = list_append((yyvsp[0]), comment); + comment = NULL; + } + } else { + if (comment != NULL) { + list_append((yyvsp[0]), comment); + comment = NULL; + } (yyval) = list_merge((yyvsp[-1]), (yyvsp[0])); + } } - yyerrok; + yyerrok; } -#line 2189 "awkgram.c" /* yacc.c:1646 */ +#line 2252 "awkgram.c" /* yacc.c:1646 */ break; case 39: -#line 461 "awkgram.y" /* yacc.c:1646 */ +#line 525 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2195 "awkgram.c" /* yacc.c:1646 */ +#line 2258 "awkgram.c" /* yacc.c:1646 */ break; case 42: -#line 471 "awkgram.y" /* yacc.c:1646 */ +#line 535 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2201 "awkgram.c" /* yacc.c:1646 */ +#line 2264 "awkgram.c" /* yacc.c:1646 */ break; case 43: -#line 473 "awkgram.y" /* yacc.c:1646 */ +#line 537 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 2207 "awkgram.c" /* yacc.c:1646 */ +#line 2270 "awkgram.c" /* yacc.c:1646 */ break; case 44: -#line 475 "awkgram.y" /* yacc.c:1646 */ +#line 539 "awkgram.y" /* yacc.c:1646 */ { if (do_pretty_print) (yyval) = list_prepend((yyvsp[0]), instruction(Op_exec_count)); else (yyval) = (yyvsp[0]); } -#line 2218 "awkgram.c" /* yacc.c:1646 */ +#line 2281 "awkgram.c" /* yacc.c:1646 */ break; case 45: -#line 482 "awkgram.y" /* yacc.c:1646 */ +#line 546 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *dflt, *curr = NULL, *cexp, *cstmt; INSTRUCTION *ip, *nextc, *tbreak; @@ -2239,7 +2302,7 @@ yyreduce: } /* else curr = NULL; */ - for(; curr != NULL; curr = nextc) { + for (; curr != NULL; curr = nextc) { INSTRUCTION *caseexp = curr->case_exp; INSTRUCTION *casestmt = curr->case_stmt; @@ -2308,11 +2371,11 @@ yyreduce: break_allowed--; fix_break_continue(ip, tbreak, NULL); } -#line 2312 "awkgram.c" /* yacc.c:1646 */ +#line 2375 "awkgram.c" /* yacc.c:1646 */ break; case 46: -#line 572 "awkgram.y" /* yacc.c:1646 */ +#line 636 "awkgram.y" /* yacc.c:1646 */ { /* * ----------------- @@ -2354,11 +2417,11 @@ yyreduce: continue_allowed--; fix_break_continue(ip, tbreak, tcont); } -#line 2358 "awkgram.c" /* yacc.c:1646 */ +#line 2421 "awkgram.c" /* yacc.c:1646 */ break; case 47: -#line 614 "awkgram.y" /* yacc.c:1646 */ +#line 678 "awkgram.y" /* yacc.c:1646 */ { /* * ----------------- @@ -2400,11 +2463,11 @@ yyreduce: } /* else $1 and $4 are NULLs */ } -#line 2404 "awkgram.c" /* yacc.c:1646 */ +#line 2467 "awkgram.c" /* yacc.c:1646 */ break; case 48: -#line 656 "awkgram.y" /* yacc.c:1646 */ +#line 720 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *ip; char *var_name = (yyvsp[-5])->lextok; @@ -2517,44 +2580,44 @@ regular_loop: break_allowed--; continue_allowed--; } -#line 2521 "awkgram.c" /* yacc.c:1646 */ +#line 2584 "awkgram.c" /* yacc.c:1646 */ break; case 49: -#line 769 "awkgram.y" /* yacc.c:1646 */ +#line 833 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_for_loop((yyvsp[-11]), (yyvsp[-9]), (yyvsp[-6]), (yyvsp[-3]), (yyvsp[0])); break_allowed--; continue_allowed--; } -#line 2532 "awkgram.c" /* yacc.c:1646 */ +#line 2595 "awkgram.c" /* yacc.c:1646 */ break; case 50: -#line 776 "awkgram.y" /* yacc.c:1646 */ +#line 840 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_for_loop((yyvsp[-10]), (yyvsp[-8]), (INSTRUCTION *) NULL, (yyvsp[-3]), (yyvsp[0])); break_allowed--; continue_allowed--; } -#line 2543 "awkgram.c" /* yacc.c:1646 */ +#line 2606 "awkgram.c" /* yacc.c:1646 */ break; case 51: -#line 783 "awkgram.y" /* yacc.c:1646 */ +#line 847 "awkgram.y" /* yacc.c:1646 */ { if (do_pretty_print) (yyval) = list_prepend((yyvsp[0]), instruction(Op_exec_count)); else (yyval) = (yyvsp[0]); } -#line 2554 "awkgram.c" /* yacc.c:1646 */ +#line 2617 "awkgram.c" /* yacc.c:1646 */ break; case 52: -#line 793 "awkgram.y" /* yacc.c:1646 */ +#line 857 "awkgram.y" /* yacc.c:1646 */ { if (! break_allowed) error_ln((yyvsp[-1])->source_line, @@ -2563,11 +2626,11 @@ regular_loop: (yyval) = list_create((yyvsp[-1])); } -#line 2567 "awkgram.c" /* yacc.c:1646 */ +#line 2630 "awkgram.c" /* yacc.c:1646 */ break; case 53: -#line 802 "awkgram.y" /* yacc.c:1646 */ +#line 866 "awkgram.y" /* yacc.c:1646 */ { if (! continue_allowed) error_ln((yyvsp[-1])->source_line, @@ -2576,11 +2639,11 @@ regular_loop: (yyval) = list_create((yyvsp[-1])); } -#line 2580 "awkgram.c" /* yacc.c:1646 */ +#line 2643 "awkgram.c" /* yacc.c:1646 */ break; case 54: -#line 811 "awkgram.y" /* yacc.c:1646 */ +#line 875 "awkgram.y" /* yacc.c:1646 */ { /* if inside function (rule = 0), resolve context at run-time */ if (rule && rule != Rule) @@ -2589,11 +2652,11 @@ regular_loop: (yyvsp[-1])->target_jmp = ip_rec; (yyval) = list_create((yyvsp[-1])); } -#line 2593 "awkgram.c" /* yacc.c:1646 */ +#line 2656 "awkgram.c" /* yacc.c:1646 */ break; case 55: -#line 820 "awkgram.y" /* yacc.c:1646 */ +#line 884 "awkgram.y" /* yacc.c:1646 */ { /* if inside function (rule = 0), resolve context at run-time */ if (rule == BEGIN || rule == END || rule == ENDFILE) @@ -2604,11 +2667,11 @@ regular_loop: (yyvsp[-1])->target_endfile = ip_endfile; (yyval) = list_create((yyvsp[-1])); } -#line 2608 "awkgram.c" /* yacc.c:1646 */ +#line 2671 "awkgram.c" /* yacc.c:1646 */ break; case 56: -#line 831 "awkgram.y" /* yacc.c:1646 */ +#line 895 "awkgram.y" /* yacc.c:1646 */ { /* Initialize the two possible jump targets, the actual target * is resolved at run-time. @@ -2623,20 +2686,20 @@ regular_loop: } else (yyval) = list_append((yyvsp[-1]), (yyvsp[-2])); } -#line 2627 "awkgram.c" /* yacc.c:1646 */ +#line 2690 "awkgram.c" /* yacc.c:1646 */ break; case 57: -#line 846 "awkgram.y" /* yacc.c:1646 */ +#line 910 "awkgram.y" /* yacc.c:1646 */ { if (! in_function) yyerror(_("`return' used outside function context")); } -#line 2636 "awkgram.c" /* yacc.c:1646 */ +#line 2699 "awkgram.c" /* yacc.c:1646 */ break; case 58: -#line 849 "awkgram.y" /* yacc.c:1646 */ +#line 913 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[-1]) == NULL) { (yyval) = list_create((yyvsp[-3])); @@ -2657,17 +2720,17 @@ regular_loop: (yyval) = list_append((yyvsp[-1]), (yyvsp[-3])); } } -#line 2661 "awkgram.c" /* yacc.c:1646 */ +#line 2724 "awkgram.c" /* yacc.c:1646 */ break; case 60: -#line 881 "awkgram.y" /* yacc.c:1646 */ +#line 945 "awkgram.y" /* yacc.c:1646 */ { in_print = true; in_parens = 0; } -#line 2667 "awkgram.c" /* yacc.c:1646 */ +#line 2730 "awkgram.c" /* yacc.c:1646 */ break; case 61: -#line 882 "awkgram.y" /* yacc.c:1646 */ +#line 946 "awkgram.y" /* yacc.c:1646 */ { /* * Optimization: plain `print' has no expression list, so $3 is null. @@ -2764,17 +2827,17 @@ regular_print: } } } -#line 2768 "awkgram.c" /* yacc.c:1646 */ +#line 2831 "awkgram.c" /* yacc.c:1646 */ break; case 62: -#line 979 "awkgram.y" /* yacc.c:1646 */ +#line 1043 "awkgram.y" /* yacc.c:1646 */ { sub_counter = 0; } -#line 2774 "awkgram.c" /* yacc.c:1646 */ +#line 2837 "awkgram.c" /* yacc.c:1646 */ break; case 63: -#line 980 "awkgram.y" /* yacc.c:1646 */ +#line 1044 "awkgram.y" /* yacc.c:1646 */ { char *arr = (yyvsp[-2])->lextok; @@ -2807,11 +2870,11 @@ regular_print: (yyval) = list_append(list_append((yyvsp[0]), (yyvsp[-2])), (yyvsp[-3])); } } -#line 2811 "awkgram.c" /* yacc.c:1646 */ +#line 2874 "awkgram.c" /* yacc.c:1646 */ break; case 64: -#line 1017 "awkgram.y" /* yacc.c:1646 */ +#line 1081 "awkgram.y" /* yacc.c:1646 */ { static bool warned = false; char *arr = (yyvsp[-1])->lextok; @@ -2837,52 +2900,52 @@ regular_print: fatal(_("`delete' is not allowed with FUNCTAB")); } } -#line 2841 "awkgram.c" /* yacc.c:1646 */ +#line 2904 "awkgram.c" /* yacc.c:1646 */ break; case 65: -#line 1043 "awkgram.y" /* yacc.c:1646 */ +#line 1107 "awkgram.y" /* yacc.c:1646 */ { (yyval) = optimize_assignment((yyvsp[0])); } -#line 2847 "awkgram.c" /* yacc.c:1646 */ +#line 2910 "awkgram.c" /* yacc.c:1646 */ break; case 66: -#line 1048 "awkgram.y" /* yacc.c:1646 */ +#line 1112 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2853 "awkgram.c" /* yacc.c:1646 */ +#line 2916 "awkgram.c" /* yacc.c:1646 */ break; case 67: -#line 1050 "awkgram.y" /* yacc.c:1646 */ +#line 1114 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2859 "awkgram.c" /* yacc.c:1646 */ +#line 2922 "awkgram.c" /* yacc.c:1646 */ break; case 68: -#line 1055 "awkgram.y" /* yacc.c:1646 */ +#line 1119 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2865 "awkgram.c" /* yacc.c:1646 */ +#line 2928 "awkgram.c" /* yacc.c:1646 */ break; case 69: -#line 1057 "awkgram.y" /* yacc.c:1646 */ +#line 1121 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[-1]) == NULL) (yyval) = list_create((yyvsp[0])); else (yyval) = list_prepend((yyvsp[-1]), (yyvsp[0])); } -#line 2876 "awkgram.c" /* yacc.c:1646 */ +#line 2939 "awkgram.c" /* yacc.c:1646 */ break; case 70: -#line 1064 "awkgram.y" /* yacc.c:1646 */ +#line 1128 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 2882 "awkgram.c" /* yacc.c:1646 */ +#line 2945 "awkgram.c" /* yacc.c:1646 */ break; case 71: -#line 1069 "awkgram.y" /* yacc.c:1646 */ +#line 1133 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *casestmt = (yyvsp[0]); if ((yyvsp[0]) == NULL) @@ -2894,11 +2957,11 @@ regular_print: bcfree((yyvsp[-2])); (yyval) = (yyvsp[-4]); } -#line 2898 "awkgram.c" /* yacc.c:1646 */ +#line 2961 "awkgram.c" /* yacc.c:1646 */ break; case 72: -#line 1081 "awkgram.y" /* yacc.c:1646 */ +#line 1145 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *casestmt = (yyvsp[0]); if ((yyvsp[0]) == NULL) @@ -2909,17 +2972,17 @@ regular_print: (yyvsp[-3])->case_stmt = casestmt; (yyval) = (yyvsp[-3]); } -#line 2913 "awkgram.c" /* yacc.c:1646 */ +#line 2976 "awkgram.c" /* yacc.c:1646 */ break; case 73: -#line 1095 "awkgram.y" /* yacc.c:1646 */ +#line 1159 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2919 "awkgram.c" /* yacc.c:1646 */ +#line 2982 "awkgram.c" /* yacc.c:1646 */ break; case 74: -#line 1097 "awkgram.y" /* yacc.c:1646 */ +#line 1161 "awkgram.y" /* yacc.c:1646 */ { NODE *n = (yyvsp[0])->memory; (void) force_number(n); @@ -2927,71 +2990,71 @@ regular_print: bcfree((yyvsp[-1])); (yyval) = (yyvsp[0]); } -#line 2931 "awkgram.c" /* yacc.c:1646 */ +#line 2994 "awkgram.c" /* yacc.c:1646 */ break; case 75: -#line 1105 "awkgram.y" /* yacc.c:1646 */ +#line 1169 "awkgram.y" /* yacc.c:1646 */ { bcfree((yyvsp[-1])); (yyval) = (yyvsp[0]); } -#line 2940 "awkgram.c" /* yacc.c:1646 */ +#line 3003 "awkgram.c" /* yacc.c:1646 */ break; case 76: -#line 1110 "awkgram.y" /* yacc.c:1646 */ +#line 1174 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2946 "awkgram.c" /* yacc.c:1646 */ +#line 3009 "awkgram.c" /* yacc.c:1646 */ break; case 77: -#line 1112 "awkgram.y" /* yacc.c:1646 */ +#line 1176 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_push_re; (yyval) = (yyvsp[0]); } -#line 2955 "awkgram.c" /* yacc.c:1646 */ +#line 3018 "awkgram.c" /* yacc.c:1646 */ break; case 78: -#line 1120 "awkgram.y" /* yacc.c:1646 */ +#line 1184 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2961 "awkgram.c" /* yacc.c:1646 */ +#line 3024 "awkgram.c" /* yacc.c:1646 */ break; case 79: -#line 1122 "awkgram.y" /* yacc.c:1646 */ +#line 1186 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 2967 "awkgram.c" /* yacc.c:1646 */ +#line 3030 "awkgram.c" /* yacc.c:1646 */ break; case 81: -#line 1132 "awkgram.y" /* yacc.c:1646 */ +#line 1196 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 2975 "awkgram.c" /* yacc.c:1646 */ +#line 3038 "awkgram.c" /* yacc.c:1646 */ break; case 82: -#line 1139 "awkgram.y" /* yacc.c:1646 */ +#line 1203 "awkgram.y" /* yacc.c:1646 */ { in_print = false; in_parens = 0; (yyval) = NULL; } -#line 2985 "awkgram.c" /* yacc.c:1646 */ +#line 3048 "awkgram.c" /* yacc.c:1646 */ break; case 83: -#line 1144 "awkgram.y" /* yacc.c:1646 */ +#line 1208 "awkgram.y" /* yacc.c:1646 */ { in_print = false; in_parens = 0; } -#line 2991 "awkgram.c" /* yacc.c:1646 */ +#line 3054 "awkgram.c" /* yacc.c:1646 */ break; case 84: -#line 1145 "awkgram.y" /* yacc.c:1646 */ +#line 1209 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[-2])->redir_type == redirect_twoway && (yyvsp[0])->lasti->opcode == Op_K_getline_redir @@ -2999,136 +3062,136 @@ regular_print: yyerror(_("multistage two-way pipelines don't work")); (yyval) = list_prepend((yyvsp[0]), (yyvsp[-2])); } -#line 3003 "awkgram.c" /* yacc.c:1646 */ +#line 3066 "awkgram.c" /* yacc.c:1646 */ break; case 85: -#line 1156 "awkgram.y" /* yacc.c:1646 */ +#line 1220 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_condition((yyvsp[-3]), (yyvsp[-5]), (yyvsp[0]), NULL, NULL); } -#line 3011 "awkgram.c" /* yacc.c:1646 */ +#line 3074 "awkgram.c" /* yacc.c:1646 */ break; case 86: -#line 1161 "awkgram.y" /* yacc.c:1646 */ +#line 1225 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_condition((yyvsp[-6]), (yyvsp[-8]), (yyvsp[-3]), (yyvsp[-2]), (yyvsp[0])); } -#line 3019 "awkgram.c" /* yacc.c:1646 */ +#line 3082 "awkgram.c" /* yacc.c:1646 */ break; case 91: -#line 1178 "awkgram.y" /* yacc.c:1646 */ +#line 1242 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3025 "awkgram.c" /* yacc.c:1646 */ +#line 3088 "awkgram.c" /* yacc.c:1646 */ break; case 92: -#line 1180 "awkgram.y" /* yacc.c:1646 */ +#line 1244 "awkgram.y" /* yacc.c:1646 */ { bcfree((yyvsp[-1])); (yyval) = (yyvsp[0]); } -#line 3034 "awkgram.c" /* yacc.c:1646 */ +#line 3097 "awkgram.c" /* yacc.c:1646 */ break; case 93: -#line 1188 "awkgram.y" /* yacc.c:1646 */ +#line 1252 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3040 "awkgram.c" /* yacc.c:1646 */ +#line 3103 "awkgram.c" /* yacc.c:1646 */ break; case 94: -#line 1190 "awkgram.y" /* yacc.c:1646 */ - { (yyval) = (yyvsp[0]) ; } -#line 3046 "awkgram.c" /* yacc.c:1646 */ +#line 1254 "awkgram.y" /* yacc.c:1646 */ + { (yyval) = (yyvsp[0]); } +#line 3109 "awkgram.c" /* yacc.c:1646 */ break; case 95: -#line 1195 "awkgram.y" /* yacc.c:1646 */ +#line 1259 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->param_count = 0; (yyval) = list_create((yyvsp[0])); } -#line 3055 "awkgram.c" /* yacc.c:1646 */ +#line 3118 "awkgram.c" /* yacc.c:1646 */ break; case 96: -#line 1200 "awkgram.y" /* yacc.c:1646 */ +#line 1264 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->param_count = (yyvsp[-2])->lasti->param_count + 1; (yyval) = list_append((yyvsp[-2]), (yyvsp[0])); yyerrok; } -#line 3065 "awkgram.c" /* yacc.c:1646 */ +#line 3128 "awkgram.c" /* yacc.c:1646 */ break; case 97: -#line 1206 "awkgram.y" /* yacc.c:1646 */ +#line 1270 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3071 "awkgram.c" /* yacc.c:1646 */ +#line 3134 "awkgram.c" /* yacc.c:1646 */ break; case 98: -#line 1208 "awkgram.y" /* yacc.c:1646 */ +#line 1272 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 3077 "awkgram.c" /* yacc.c:1646 */ +#line 3140 "awkgram.c" /* yacc.c:1646 */ break; case 99: -#line 1210 "awkgram.y" /* yacc.c:1646 */ +#line 1274 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-2]); } -#line 3083 "awkgram.c" /* yacc.c:1646 */ +#line 3146 "awkgram.c" /* yacc.c:1646 */ break; case 100: -#line 1216 "awkgram.y" /* yacc.c:1646 */ +#line 1280 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3089 "awkgram.c" /* yacc.c:1646 */ +#line 3152 "awkgram.c" /* yacc.c:1646 */ break; case 101: -#line 1218 "awkgram.y" /* yacc.c:1646 */ +#line 1282 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3095 "awkgram.c" /* yacc.c:1646 */ +#line 3158 "awkgram.c" /* yacc.c:1646 */ break; case 102: -#line 1223 "awkgram.y" /* yacc.c:1646 */ +#line 1287 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3101 "awkgram.c" /* yacc.c:1646 */ +#line 3164 "awkgram.c" /* yacc.c:1646 */ break; case 103: -#line 1225 "awkgram.y" /* yacc.c:1646 */ +#line 1289 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3107 "awkgram.c" /* yacc.c:1646 */ +#line 3170 "awkgram.c" /* yacc.c:1646 */ break; case 104: -#line 1230 "awkgram.y" /* yacc.c:1646 */ +#line 1294 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_expression_list(NULL, (yyvsp[0])); } -#line 3113 "awkgram.c" /* yacc.c:1646 */ +#line 3176 "awkgram.c" /* yacc.c:1646 */ break; case 105: -#line 1232 "awkgram.y" /* yacc.c:1646 */ +#line 1296 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_expression_list((yyvsp[-2]), (yyvsp[0])); yyerrok; } -#line 3122 "awkgram.c" /* yacc.c:1646 */ +#line 3185 "awkgram.c" /* yacc.c:1646 */ break; case 106: -#line 1237 "awkgram.y" /* yacc.c:1646 */ +#line 1301 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3128 "awkgram.c" /* yacc.c:1646 */ +#line 3191 "awkgram.c" /* yacc.c:1646 */ break; case 107: -#line 1239 "awkgram.y" /* yacc.c:1646 */ +#line 1303 "awkgram.y" /* yacc.c:1646 */ { /* * Returning the expression list instead of NULL lets @@ -3136,52 +3199,52 @@ regular_print: */ (yyval) = (yyvsp[-1]); } -#line 3140 "awkgram.c" /* yacc.c:1646 */ +#line 3203 "awkgram.c" /* yacc.c:1646 */ break; case 108: -#line 1247 "awkgram.y" /* yacc.c:1646 */ +#line 1311 "awkgram.y" /* yacc.c:1646 */ { /* Ditto */ (yyval) = mk_expression_list((yyvsp[-2]), (yyvsp[0])); } -#line 3149 "awkgram.c" /* yacc.c:1646 */ +#line 3212 "awkgram.c" /* yacc.c:1646 */ break; case 109: -#line 1252 "awkgram.y" /* yacc.c:1646 */ +#line 1316 "awkgram.y" /* yacc.c:1646 */ { /* Ditto */ (yyval) = (yyvsp[-2]); } -#line 3158 "awkgram.c" /* yacc.c:1646 */ +#line 3221 "awkgram.c" /* yacc.c:1646 */ break; case 110: -#line 1261 "awkgram.y" /* yacc.c:1646 */ +#line 1325 "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 3169 "awkgram.c" /* yacc.c:1646 */ +#line 3232 "awkgram.c" /* yacc.c:1646 */ break; case 111: -#line 1268 "awkgram.y" /* yacc.c:1646 */ +#line 1332 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_boolean((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3175 "awkgram.c" /* yacc.c:1646 */ +#line 3238 "awkgram.c" /* yacc.c:1646 */ break; case 112: -#line 1270 "awkgram.y" /* yacc.c:1646 */ +#line 1334 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_boolean((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3181 "awkgram.c" /* yacc.c:1646 */ +#line 3244 "awkgram.c" /* yacc.c:1646 */ break; case 113: -#line 1272 "awkgram.y" /* yacc.c:1646 */ +#line 1336 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[-2])->lasti->opcode == Op_match_rec) warning_ln((yyvsp[-1])->source_line, @@ -3197,11 +3260,11 @@ regular_print: (yyval) = list_append(list_merge((yyvsp[-2]), (yyvsp[0])), (yyvsp[-1])); } } -#line 3201 "awkgram.c" /* yacc.c:1646 */ +#line 3264 "awkgram.c" /* yacc.c:1646 */ break; case 114: -#line 1288 "awkgram.y" /* yacc.c:1646 */ +#line 1352 "awkgram.y" /* yacc.c:1646 */ { if (do_lint_old) warning_ln((yyvsp[-1])->source_line, @@ -3211,91 +3274,91 @@ regular_print: (yyvsp[-1])->expr_count = 1; (yyval) = list_append(list_merge((yyvsp[-2]), (yyvsp[0])), (yyvsp[-1])); } -#line 3215 "awkgram.c" /* yacc.c:1646 */ +#line 3278 "awkgram.c" /* yacc.c:1646 */ break; case 115: -#line 1298 "awkgram.y" /* yacc.c:1646 */ +#line 1362 "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 3226 "awkgram.c" /* yacc.c:1646 */ +#line 3289 "awkgram.c" /* yacc.c:1646 */ break; case 116: -#line 1305 "awkgram.y" /* yacc.c:1646 */ +#line 1369 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_condition((yyvsp[-4]), (yyvsp[-3]), (yyvsp[-2]), (yyvsp[-1]), (yyvsp[0])); } -#line 3232 "awkgram.c" /* yacc.c:1646 */ +#line 3295 "awkgram.c" /* yacc.c:1646 */ break; case 117: -#line 1307 "awkgram.y" /* yacc.c:1646 */ +#line 1371 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3238 "awkgram.c" /* yacc.c:1646 */ +#line 3301 "awkgram.c" /* yacc.c:1646 */ break; case 118: -#line 1312 "awkgram.y" /* yacc.c:1646 */ +#line 1376 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3244 "awkgram.c" /* yacc.c:1646 */ +#line 3307 "awkgram.c" /* yacc.c:1646 */ break; case 119: -#line 1314 "awkgram.y" /* yacc.c:1646 */ +#line 1378 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3250 "awkgram.c" /* yacc.c:1646 */ +#line 3313 "awkgram.c" /* yacc.c:1646 */ break; case 120: -#line 1316 "awkgram.y" /* yacc.c:1646 */ +#line 1380 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_assign_quotient; (yyval) = (yyvsp[0]); } -#line 3259 "awkgram.c" /* yacc.c:1646 */ +#line 3322 "awkgram.c" /* yacc.c:1646 */ break; case 121: -#line 1324 "awkgram.y" /* yacc.c:1646 */ +#line 1388 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3265 "awkgram.c" /* yacc.c:1646 */ +#line 3328 "awkgram.c" /* yacc.c:1646 */ break; case 122: -#line 1326 "awkgram.y" /* yacc.c:1646 */ +#line 1390 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3271 "awkgram.c" /* yacc.c:1646 */ +#line 3334 "awkgram.c" /* yacc.c:1646 */ break; case 123: -#line 1331 "awkgram.y" /* yacc.c:1646 */ +#line 1395 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3277 "awkgram.c" /* yacc.c:1646 */ +#line 3340 "awkgram.c" /* yacc.c:1646 */ break; case 124: -#line 1333 "awkgram.y" /* yacc.c:1646 */ +#line 1397 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3283 "awkgram.c" /* yacc.c:1646 */ +#line 3346 "awkgram.c" /* yacc.c:1646 */ break; case 125: -#line 1338 "awkgram.y" /* yacc.c:1646 */ +#line 1402 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3289 "awkgram.c" /* yacc.c:1646 */ +#line 3352 "awkgram.c" /* yacc.c:1646 */ break; case 126: -#line 1340 "awkgram.y" /* yacc.c:1646 */ +#line 1404 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3295 "awkgram.c" /* yacc.c:1646 */ +#line 3358 "awkgram.c" /* yacc.c:1646 */ break; case 127: -#line 1342 "awkgram.y" /* yacc.c:1646 */ +#line 1406 "awkgram.y" /* yacc.c:1646 */ { int count = 2; bool is_simple_var = false; @@ -3342,47 +3405,47 @@ regular_print: max_args = count; } } -#line 3346 "awkgram.c" /* yacc.c:1646 */ +#line 3409 "awkgram.c" /* yacc.c:1646 */ break; case 129: -#line 1394 "awkgram.y" /* yacc.c:1646 */ +#line 1458 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3352 "awkgram.c" /* yacc.c:1646 */ +#line 3415 "awkgram.c" /* yacc.c:1646 */ break; case 130: -#line 1396 "awkgram.y" /* yacc.c:1646 */ +#line 1460 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3358 "awkgram.c" /* yacc.c:1646 */ +#line 3421 "awkgram.c" /* yacc.c:1646 */ break; case 131: -#line 1398 "awkgram.y" /* yacc.c:1646 */ +#line 1462 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3364 "awkgram.c" /* yacc.c:1646 */ +#line 3427 "awkgram.c" /* yacc.c:1646 */ break; case 132: -#line 1400 "awkgram.y" /* yacc.c:1646 */ +#line 1464 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3370 "awkgram.c" /* yacc.c:1646 */ +#line 3433 "awkgram.c" /* yacc.c:1646 */ break; case 133: -#line 1402 "awkgram.y" /* yacc.c:1646 */ +#line 1466 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3376 "awkgram.c" /* yacc.c:1646 */ +#line 3439 "awkgram.c" /* yacc.c:1646 */ break; case 134: -#line 1404 "awkgram.y" /* yacc.c:1646 */ +#line 1468 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3382 "awkgram.c" /* yacc.c:1646 */ +#line 3445 "awkgram.c" /* yacc.c:1646 */ break; case 135: -#line 1406 "awkgram.y" /* yacc.c:1646 */ +#line 1470 "awkgram.y" /* yacc.c:1646 */ { /* * In BEGINFILE/ENDFILE, allow `getline [var] < file' @@ -3396,29 +3459,29 @@ regular_print: _("non-redirected `getline' undefined inside END action")); (yyval) = mk_getline((yyvsp[-2]), (yyvsp[-1]), (yyvsp[0]), redirect_input); } -#line 3400 "awkgram.c" /* yacc.c:1646 */ +#line 3463 "awkgram.c" /* yacc.c:1646 */ break; case 136: -#line 1420 "awkgram.y" /* yacc.c:1646 */ +#line 1484 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_postincrement; (yyval) = mk_assignment((yyvsp[-1]), NULL, (yyvsp[0])); } -#line 3409 "awkgram.c" /* yacc.c:1646 */ +#line 3472 "awkgram.c" /* yacc.c:1646 */ break; case 137: -#line 1425 "awkgram.y" /* yacc.c:1646 */ +#line 1489 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_postdecrement; (yyval) = mk_assignment((yyvsp[-1]), NULL, (yyvsp[0])); } -#line 3418 "awkgram.c" /* yacc.c:1646 */ +#line 3481 "awkgram.c" /* yacc.c:1646 */ break; case 138: -#line 1430 "awkgram.y" /* yacc.c:1646 */ +#line 1494 "awkgram.y" /* yacc.c:1646 */ { if (do_lint_old) { warning_ln((yyvsp[-1])->source_line, @@ -3438,64 +3501,64 @@ regular_print: (yyval) = list_append(list_merge(t, (yyvsp[0])), (yyvsp[-1])); } } -#line 3442 "awkgram.c" /* yacc.c:1646 */ +#line 3505 "awkgram.c" /* yacc.c:1646 */ break; case 139: -#line 1455 "awkgram.y" /* yacc.c:1646 */ +#line 1519 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_getline((yyvsp[-1]), (yyvsp[0]), (yyvsp[-3]), (yyvsp[-2])->redir_type); bcfree((yyvsp[-2])); } -#line 3451 "awkgram.c" /* yacc.c:1646 */ +#line 3514 "awkgram.c" /* yacc.c:1646 */ break; case 140: -#line 1461 "awkgram.y" /* yacc.c:1646 */ +#line 1525 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3457 "awkgram.c" /* yacc.c:1646 */ +#line 3520 "awkgram.c" /* yacc.c:1646 */ break; case 141: -#line 1463 "awkgram.y" /* yacc.c:1646 */ +#line 1527 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3463 "awkgram.c" /* yacc.c:1646 */ +#line 3526 "awkgram.c" /* yacc.c:1646 */ break; case 142: -#line 1465 "awkgram.y" /* yacc.c:1646 */ +#line 1529 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3469 "awkgram.c" /* yacc.c:1646 */ +#line 3532 "awkgram.c" /* yacc.c:1646 */ break; case 143: -#line 1467 "awkgram.y" /* yacc.c:1646 */ +#line 1531 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3475 "awkgram.c" /* yacc.c:1646 */ +#line 3538 "awkgram.c" /* yacc.c:1646 */ break; case 144: -#line 1469 "awkgram.y" /* yacc.c:1646 */ +#line 1533 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3481 "awkgram.c" /* yacc.c:1646 */ +#line 3544 "awkgram.c" /* yacc.c:1646 */ break; case 145: -#line 1471 "awkgram.y" /* yacc.c:1646 */ +#line 1535 "awkgram.y" /* yacc.c:1646 */ { (yyval) = mk_binary((yyvsp[-2]), (yyvsp[0]), (yyvsp[-1])); } -#line 3487 "awkgram.c" /* yacc.c:1646 */ +#line 3550 "awkgram.c" /* yacc.c:1646 */ break; case 146: -#line 1476 "awkgram.y" /* yacc.c:1646 */ +#line 1540 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_create((yyvsp[0])); } -#line 3495 "awkgram.c" /* yacc.c:1646 */ +#line 3558 "awkgram.c" /* yacc.c:1646 */ break; case 147: -#line 1480 "awkgram.y" /* yacc.c:1646 */ +#line 1544 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[0])->opcode == Op_match_rec) { (yyvsp[0])->opcode = Op_nomatch; @@ -3527,37 +3590,37 @@ regular_print: } } } -#line 3531 "awkgram.c" /* yacc.c:1646 */ +#line 3594 "awkgram.c" /* yacc.c:1646 */ break; case 148: -#line 1512 "awkgram.y" /* yacc.c:1646 */ +#line 1576 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 3537 "awkgram.c" /* yacc.c:1646 */ +#line 3600 "awkgram.c" /* yacc.c:1646 */ break; case 149: -#line 1514 "awkgram.y" /* yacc.c:1646 */ +#line 1578 "awkgram.y" /* yacc.c:1646 */ { (yyval) = snode((yyvsp[-1]), (yyvsp[-3])); if ((yyval) == NULL) YYABORT; } -#line 3547 "awkgram.c" /* yacc.c:1646 */ +#line 3610 "awkgram.c" /* yacc.c:1646 */ break; case 150: -#line 1520 "awkgram.y" /* yacc.c:1646 */ +#line 1584 "awkgram.y" /* yacc.c:1646 */ { (yyval) = snode((yyvsp[-1]), (yyvsp[-3])); if ((yyval) == NULL) YYABORT; } -#line 3557 "awkgram.c" /* yacc.c:1646 */ +#line 3620 "awkgram.c" /* yacc.c:1646 */ break; case 151: -#line 1526 "awkgram.y" /* yacc.c:1646 */ +#line 1590 "awkgram.y" /* yacc.c:1646 */ { static bool warned = false; @@ -3570,45 +3633,45 @@ regular_print: if ((yyval) == NULL) YYABORT; } -#line 3574 "awkgram.c" /* yacc.c:1646 */ +#line 3637 "awkgram.c" /* yacc.c:1646 */ break; case 154: -#line 1541 "awkgram.y" /* yacc.c:1646 */ +#line 1605 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[-1])->opcode = Op_preincrement; (yyval) = mk_assignment((yyvsp[0]), NULL, (yyvsp[-1])); } -#line 3583 "awkgram.c" /* yacc.c:1646 */ +#line 3646 "awkgram.c" /* yacc.c:1646 */ break; case 155: -#line 1546 "awkgram.y" /* yacc.c:1646 */ +#line 1610 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[-1])->opcode = Op_predecrement; (yyval) = mk_assignment((yyvsp[0]), NULL, (yyvsp[-1])); } -#line 3592 "awkgram.c" /* yacc.c:1646 */ +#line 3655 "awkgram.c" /* yacc.c:1646 */ break; case 156: -#line 1551 "awkgram.y" /* yacc.c:1646 */ +#line 1615 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_create((yyvsp[0])); } -#line 3600 "awkgram.c" /* yacc.c:1646 */ +#line 3663 "awkgram.c" /* yacc.c:1646 */ break; case 157: -#line 1555 "awkgram.y" /* yacc.c:1646 */ +#line 1619 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_create((yyvsp[0])); } -#line 3608 "awkgram.c" /* yacc.c:1646 */ +#line 3671 "awkgram.c" /* yacc.c:1646 */ break; case 158: -#line 1559 "awkgram.y" /* yacc.c:1646 */ +#line 1623 "awkgram.y" /* yacc.c:1646 */ { if ((yyvsp[0])->lasti->opcode == Op_push_i && ((yyvsp[0])->lasti->memory->flags & (STRCUR|STRING)) == 0 @@ -3623,11 +3686,11 @@ regular_print: (yyval) = list_append((yyvsp[0]), (yyvsp[-1])); } } -#line 3627 "awkgram.c" /* yacc.c:1646 */ +#line 3690 "awkgram.c" /* yacc.c:1646 */ break; case 159: -#line 1574 "awkgram.y" /* yacc.c:1646 */ +#line 1638 "awkgram.y" /* yacc.c:1646 */ { /* * was: $$ = $2 @@ -3637,20 +3700,20 @@ regular_print: (yyvsp[-1])->memory = make_number(0.0); (yyval) = list_append((yyvsp[0]), (yyvsp[-1])); } -#line 3641 "awkgram.c" /* yacc.c:1646 */ +#line 3704 "awkgram.c" /* yacc.c:1646 */ break; case 160: -#line 1587 "awkgram.y" /* yacc.c:1646 */ +#line 1651 "awkgram.y" /* yacc.c:1646 */ { func_use((yyvsp[0])->lasti->func_name, FUNC_USE); (yyval) = (yyvsp[0]); } -#line 3650 "awkgram.c" /* yacc.c:1646 */ +#line 3713 "awkgram.c" /* yacc.c:1646 */ break; case 161: -#line 1592 "awkgram.y" /* yacc.c:1646 */ +#line 1656 "awkgram.y" /* yacc.c:1646 */ { /* indirect function call */ INSTRUCTION *f, *t; @@ -3683,11 +3746,11 @@ regular_print: (yyval) = list_prepend((yyvsp[0]), t); } -#line 3687 "awkgram.c" /* yacc.c:1646 */ +#line 3750 "awkgram.c" /* yacc.c:1646 */ break; case 162: -#line 1628 "awkgram.y" /* yacc.c:1646 */ +#line 1692 "awkgram.y" /* yacc.c:1646 */ { param_sanity((yyvsp[-1])); (yyvsp[-3])->opcode = Op_func_call; @@ -3701,49 +3764,49 @@ regular_print: (yyval) = list_append(t, (yyvsp[-3])); } } -#line 3705 "awkgram.c" /* yacc.c:1646 */ +#line 3768 "awkgram.c" /* yacc.c:1646 */ break; case 163: -#line 1645 "awkgram.y" /* yacc.c:1646 */ +#line 1709 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3711 "awkgram.c" /* yacc.c:1646 */ +#line 3774 "awkgram.c" /* yacc.c:1646 */ break; case 164: -#line 1647 "awkgram.y" /* yacc.c:1646 */ +#line 1711 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3717 "awkgram.c" /* yacc.c:1646 */ +#line 3780 "awkgram.c" /* yacc.c:1646 */ break; case 165: -#line 1652 "awkgram.y" /* yacc.c:1646 */ +#line 1716 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3723 "awkgram.c" /* yacc.c:1646 */ +#line 3786 "awkgram.c" /* yacc.c:1646 */ break; case 166: -#line 1654 "awkgram.y" /* yacc.c:1646 */ +#line 1718 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 3729 "awkgram.c" /* yacc.c:1646 */ +#line 3792 "awkgram.c" /* yacc.c:1646 */ break; case 167: -#line 1659 "awkgram.y" /* yacc.c:1646 */ +#line 1723 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3735 "awkgram.c" /* yacc.c:1646 */ +#line 3798 "awkgram.c" /* yacc.c:1646 */ break; case 168: -#line 1661 "awkgram.y" /* yacc.c:1646 */ +#line 1725 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_merge((yyvsp[-1]), (yyvsp[0])); } -#line 3743 "awkgram.c" /* yacc.c:1646 */ +#line 3806 "awkgram.c" /* yacc.c:1646 */ break; case 169: -#line 1668 "awkgram.y" /* yacc.c:1646 */ +#line 1732 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *ip = (yyvsp[0])->lasti; int count = ip->sub_count; /* # of SUBSEP-seperated expressions */ @@ -3757,11 +3820,11 @@ regular_print: sub_counter++; /* count # of dimensions */ (yyval) = (yyvsp[0]); } -#line 3761 "awkgram.c" /* yacc.c:1646 */ +#line 3824 "awkgram.c" /* yacc.c:1646 */ break; case 170: -#line 1685 "awkgram.y" /* yacc.c:1646 */ +#line 1749 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *t = (yyvsp[-1]); if ((yyvsp[-1]) == NULL) { @@ -3775,31 +3838,31 @@ regular_print: (yyvsp[0])->sub_count = count_expressions(&t, false); (yyval) = list_append(t, (yyvsp[0])); } -#line 3779 "awkgram.c" /* yacc.c:1646 */ +#line 3842 "awkgram.c" /* yacc.c:1646 */ break; case 171: -#line 1702 "awkgram.y" /* yacc.c:1646 */ +#line 1766 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); } -#line 3785 "awkgram.c" /* yacc.c:1646 */ +#line 3848 "awkgram.c" /* yacc.c:1646 */ break; case 172: -#line 1704 "awkgram.y" /* yacc.c:1646 */ +#line 1768 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_merge((yyvsp[-1]), (yyvsp[0])); } -#line 3793 "awkgram.c" /* yacc.c:1646 */ +#line 3856 "awkgram.c" /* yacc.c:1646 */ break; case 173: -#line 1711 "awkgram.y" /* yacc.c:1646 */ +#line 1775 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[-1]); } -#line 3799 "awkgram.c" /* yacc.c:1646 */ +#line 3862 "awkgram.c" /* yacc.c:1646 */ break; case 174: -#line 1716 "awkgram.y" /* yacc.c:1646 */ +#line 1780 "awkgram.y" /* yacc.c:1646 */ { char *var_name = (yyvsp[0])->lextok; @@ -3807,22 +3870,22 @@ regular_print: (yyvsp[0])->memory = variable((yyvsp[0])->source_line, var_name, Node_var_new); (yyval) = list_create((yyvsp[0])); } -#line 3811 "awkgram.c" /* yacc.c:1646 */ +#line 3874 "awkgram.c" /* yacc.c:1646 */ break; case 175: -#line 1724 "awkgram.y" /* yacc.c:1646 */ +#line 1788 "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 3822 "awkgram.c" /* yacc.c:1646 */ +#line 3885 "awkgram.c" /* yacc.c:1646 */ break; case 176: -#line 1734 "awkgram.y" /* yacc.c:1646 */ +#line 1798 "awkgram.y" /* yacc.c:1646 */ { INSTRUCTION *ip = (yyvsp[0])->nexti; if (ip->opcode == Op_push @@ -3834,73 +3897,73 @@ regular_print: } else (yyval) = (yyvsp[0]); } -#line 3838 "awkgram.c" /* yacc.c:1646 */ +#line 3901 "awkgram.c" /* yacc.c:1646 */ break; case 177: -#line 1746 "awkgram.y" /* yacc.c:1646 */ +#line 1810 "awkgram.y" /* yacc.c:1646 */ { (yyval) = list_append((yyvsp[-1]), (yyvsp[-2])); if ((yyvsp[0]) != NULL) mk_assignment((yyvsp[-1]), NULL, (yyvsp[0])); } -#line 3848 "awkgram.c" /* yacc.c:1646 */ +#line 3911 "awkgram.c" /* yacc.c:1646 */ break; case 178: -#line 1755 "awkgram.y" /* yacc.c:1646 */ +#line 1819 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_postincrement; } -#line 3856 "awkgram.c" /* yacc.c:1646 */ +#line 3919 "awkgram.c" /* yacc.c:1646 */ break; case 179: -#line 1759 "awkgram.y" /* yacc.c:1646 */ +#line 1823 "awkgram.y" /* yacc.c:1646 */ { (yyvsp[0])->opcode = Op_postdecrement; } -#line 3864 "awkgram.c" /* yacc.c:1646 */ +#line 3927 "awkgram.c" /* yacc.c:1646 */ break; case 180: -#line 1762 "awkgram.y" /* yacc.c:1646 */ +#line 1826 "awkgram.y" /* yacc.c:1646 */ { (yyval) = NULL; } -#line 3870 "awkgram.c" /* yacc.c:1646 */ +#line 3933 "awkgram.c" /* yacc.c:1646 */ break; case 182: -#line 1770 "awkgram.y" /* yacc.c:1646 */ +#line 1834 "awkgram.y" /* yacc.c:1646 */ { yyerrok; } -#line 3876 "awkgram.c" /* yacc.c:1646 */ +#line 3939 "awkgram.c" /* yacc.c:1646 */ break; case 183: -#line 1774 "awkgram.y" /* yacc.c:1646 */ +#line 1838 "awkgram.y" /* yacc.c:1646 */ { yyerrok; } -#line 3882 "awkgram.c" /* yacc.c:1646 */ +#line 3945 "awkgram.c" /* yacc.c:1646 */ break; case 186: -#line 1783 "awkgram.y" /* yacc.c:1646 */ +#line 1847 "awkgram.y" /* yacc.c:1646 */ { yyerrok; } -#line 3888 "awkgram.c" /* yacc.c:1646 */ +#line 3951 "awkgram.c" /* yacc.c:1646 */ break; case 187: -#line 1787 "awkgram.y" /* yacc.c:1646 */ +#line 1851 "awkgram.y" /* yacc.c:1646 */ { (yyval) = (yyvsp[0]); yyerrok; } -#line 3894 "awkgram.c" /* yacc.c:1646 */ +#line 3957 "awkgram.c" /* yacc.c:1646 */ break; case 188: -#line 1791 "awkgram.y" /* yacc.c:1646 */ +#line 1855 "awkgram.y" /* yacc.c:1646 */ { yyerrok; } -#line 3900 "awkgram.c" /* yacc.c:1646 */ +#line 3963 "awkgram.c" /* yacc.c:1646 */ break; -#line 3904 "awkgram.c" /* yacc.c:1646 */ +#line 3967 "awkgram.c" /* yacc.c:1646 */ default: break; } /* User semantic actions sometimes alter yychar, and that requires @@ -4128,7 +4191,7 @@ yyreturn: #endif return yyresult; } -#line 1793 "awkgram.y" /* yacc.c:1906 */ +#line 1857 "awkgram.y" /* yacc.c:1906 */ struct token { @@ -4144,6 +4207,7 @@ struct token { # define GAWKX 0x0400 /* gawk extension */ # define BREAK 0x0800 /* break allowed inside */ # define CONTINUE 0x1000 /* continue allowed inside */ +# define DEBUG_USE 0x2000 /* for use by developers */ NODE *(*ptr)(int); /* function that implements this keyword */ NODE *(*ptr2)(int); /* alternate arbitrary-precision function */ @@ -4182,7 +4246,7 @@ static const struct token tokentab[] = { {"END", Op_rule, LEX_END, 0, 0, 0}, {"ENDFILE", Op_rule, LEX_ENDFILE, GAWKX, 0, 0}, #ifdef ARRAYDEBUG -{"adump", Op_builtin, LEX_BUILTIN, GAWKX|A(1)|A(2), do_adump, 0}, +{"adump", Op_builtin, LEX_BUILTIN, GAWKX|A(1)|A(2)|DEBUG_USE, do_adump, 0}, #endif {"and", Op_builtin, LEX_BUILTIN, GAWKX, do_and, MPF(and)}, {"asort", Op_builtin, LEX_BUILTIN, GAWKX|A(1)|A(2)|A(3), do_asort, 0}, @@ -4242,7 +4306,7 @@ static const struct token tokentab[] = { {"sqrt", Op_builtin, LEX_BUILTIN, A(1), do_sqrt, MPF(sqrt)}, {"srand", Op_builtin, LEX_BUILTIN, NOT_OLD|A(0)|A(1), do_srand, MPF(srand)}, #if defined(GAWKDEBUG) || defined(ARRAYDEBUG) /* || ... */ -{"stopme", Op_builtin, LEX_BUILTIN, GAWKX|A(0), stopme, 0}, +{"stopme", Op_builtin, LEX_BUILTIN, GAWKX|A(0)|DEBUG_USE, stopme, 0}, #endif {"strftime", Op_builtin, LEX_BUILTIN, GAWKX|A(0)|A(1)|A(2)|A(3), do_strftime, 0}, {"strtonum", Op_builtin, LEX_BUILTIN, GAWKX|A(1), do_strtonum, MPF(strtonum)}, @@ -4561,6 +4625,13 @@ 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 (comment != NULL) + (void) list_append(cp, comment); (void) list_append(cp, ip_atexit); (void) list_append(cp, instruction(Op_stop)); @@ -4593,6 +4664,12 @@ mk_program() if (begin_block != NULL) cp = list_merge(begin_block, cp); + if (program_comment != NULL) { + (void) list_prepend(cp, program_comment); + } + if (comment != NULL) { + (void) list_append(cp, comment); + } (void) list_append(cp, ip_atexit); (void) list_append(cp, instruction(Op_stop)); @@ -5094,7 +5171,7 @@ get_src_buf() lexend = lexptr + n; if (n == 0) { static bool warned = false; - if (do_lint && newfile && ! warned){ + if (do_lint && newfile && ! warned) { warned = true; sourceline = 0; lintwarn(_("source file `%s' is empty"), source); @@ -5156,7 +5233,7 @@ check_bad_char(int c) } if (iscntrl(c) && ! isspace(c)) - fatal(_("PEBKAC error: invalid character '\\%03o' in source code"), c); + fatal(_("PEBKAC error: invalid character '\\%03o' in source code"), c & 0xFF); } /* nextc --- get the next input character */ @@ -5187,7 +5264,7 @@ again: mbstate_t tmp_state; size_t mbclen; - for (idx = 0 ; lexptr + idx < lexend ; idx++) { + for (idx = 0; lexptr + idx < lexend; idx++) { tmp_state = cur_mbstate; mbclen = mbrlen(lexptr, idx + 1, &tmp_state); @@ -5266,6 +5343,79 @@ pushback(void) } +/* get_comment --- collect comment text */ + +int +get_comment(void) +{ + int c; + int sl; + tok = tokstart; + tokadd('#'); + sl = sourceline; + + while (true) { + while ((c = nextc(false)) != '\n' && c != END_FILE) { + tokadd(c); + } + if (c == '\n') { + tokadd(c); + sourceline++; + do { + c = nextc(false); + if (c == '\n') { + sourceline++; + tokadd(c); + } + } while (isspace(c) && c != END_FILE); + if (c == END_FILE) + break; + else if (c != '#') { + pushback(); + break; + } else + tokadd(c); + } else + break; + } + comment = bcalloc(Op_comment, 1, sl); + comment->source_file = source; + comment->memory = make_str_node(tokstart, tok - tokstart, 0); + + return c; +} + +/* split_comment --- split initial comment text into program and function parts */ + +static void +split_comment(void) +{ + char *p; + int l; + NODE *n; + + p = comment->memory->stptr; + l = comment->memory->stlen - 3; + /* have at least two comments so split at last blank line (\n\n) */ + while (l >= 0) { + if (p[l] == '\n' && p[l+1] == '\n') { + function_comment = comment; + n = function_comment->memory; + function_comment->memory = make_str_node(p + l + 2, n->stlen - l - 2, 0); + /* create program comment */ + program_comment = bcalloc(Op_comment, 1, sourceline); + program_comment->source_file = comment->source_file; + p[l + 2] = 0; + program_comment->memory = make_str_node(p, l + 2, 0); + comment = NULL; + freenode(n); + break; + } + else + l--; + } +} + /* allow_newline --- allow newline after &&, ||, ? and : */ static void @@ -5280,8 +5430,13 @@ allow_newline(void) break; } if (c == '#') { - while ((c = nextc(false)) != '\n' && c != END_FILE) - continue; + if (do_pretty_print && ! do_profile) { + /* collect comment byte code iff doing pretty print but not profiling. */ + c = get_comment(); + } else { + while ((c = nextc(false)) != '\n' && c != END_FILE) + continue; + } if (c == END_FILE) { pushback(); break; @@ -5304,7 +5459,8 @@ allow_newline(void) * removes the warnings. */ -static int newline_eof() +static int +newline_eof() { /* NB: a newline at end does not start a source line. */ if (lasttok != NEWLINE) { @@ -5485,9 +5641,20 @@ retry: return lasttok = NEWLINE; case '#': /* it's a comment */ - while ((c = nextc(false)) != '\n') { + if (do_pretty_print && ! do_profile) { + /* + * Collect comment byte code iff doing pretty print + * but not profiling. + */ + c = get_comment(); + if (c == END_FILE) return lasttok = NEWLINE_EOF; + } else { + while ((c = nextc(false)) != '\n') { + if (c == END_FILE) + return lasttok = NEWLINE_EOF; + } } sourceline++; return lasttok = NEWLINE; @@ -5498,7 +5665,7 @@ retry: case '\\': #ifdef RELAXED_CONTINUATION /* - * This code puports to allow comments and/or whitespace + * This code purports to allow comments and/or whitespace * after the `\' at the end of a line used for continuation. * Use it at your own risk. We think it's a bad idea, which * is why it's not on by default. @@ -5515,9 +5682,13 @@ retry: lintwarn( _("use of `\\ #...' line continuation is not portable")); } - while ((c = nextc(false)) != '\n') - if (c == END_FILE) - break; + if (do_pretty_print && ! do_profile) + c = get_comment(); + else { + while ((c = nextc(false)) != '\n') + if (c == END_FILE) + break; + } } pushback(); } @@ -5729,14 +5900,18 @@ retry: lastline = sourceline; return lasttok = c; } - did_newline++; + did_newline = true; --lexptr; /* pick up } next time */ return lasttok = NEWLINE; case '"': string: esc_seen = false; - while ((c = nextc(true)) != '"') { + /* + * Allow any kind of junk in quoted string, + * so pass false to nextc(). + */ + while ((c = nextc(false)) != '"') { if (c == '\n') { pushback(); yyerror(_("unterminated string")); @@ -5975,7 +6150,7 @@ retry: } } - if (c != '_' && ! isalpha(c)) { + if (c != '_' && ! is_alpha(c)) { yyerror(_("invalid char '%c' in expression"), c); return lasttok = LEX_EOF; } @@ -6578,6 +6753,14 @@ mk_function(INSTRUCTION *fi, INSTRUCTION *def) (t + 1)->tail_call = true; } + /* add any pre-function comment to start of action for profile.c */ + + if (function_comment != NULL) { + function_comment->source_line = 0; + (void) list_prepend(def, function_comment); + function_comment = NULL; + } + /* add an implicit return at end; * also used by 'return' command in debugger */ @@ -7397,7 +7580,6 @@ append_rule(INSTRUCTION *pattern, INSTRUCTION *action) action), tp); } - } list_append(rule_list, rp + 1); @@ -8054,3 +8236,94 @@ one_line_close(int fd) } +/* lookup_builtin --- find a builtin function or return NULL */ + +builtin_func_t +lookup_builtin(const char *name) +{ + int mid = check_special(name); + + if (mid == -1 || tokentab[mid].class != LEX_BUILTIN) + return NULL; +#ifdef HAVE_MPFR + if (do_mpfr) + return tokentab[mid].ptr2; +#endif + + return tokentab[mid].ptr; +} + +/* install_builtins --- add built-in functions to FUNCTAB */ + +void +install_builtins(void) +{ + int i, j; + + j = sizeof(tokentab) / sizeof(tokentab[0]); + for (i = 0; i < j; i++) { + if ( tokentab[i].class == LEX_BUILTIN + && (tokentab[i].flags & DEBUG_USE) == 0) { + (void) install_symbol(tokentab[i].operator, Node_builtin_func); + } + } +} + +/* + * 9/2014: Gawk cannot use <ctype.h> isalpha or isalnum when + * parsing the program since that can let through non-English + * letters. So, we supply our own. !@#$%^&*()-ing locales! + */ + +/* is_alpha --- return true if c is an English letter */ + +/* + * The scene of the murder was grisly to look upon. When the inspector + * arrived, the sergeant turned to him and said, "Another programmer stabbed + * in the back. He never knew what happened." + * + * The inspector replied, "Looks like the MO of isalpha, and his even meaner + * big brother, isalnum. The Locale brothers." The sergeant merely + * shuddered in horror. + */ + +bool +is_alpha(int c) +{ +#ifdef I_DONT_KNOW_WHAT_IM_DOING + return isalpha(c); +#else /* ! I_DONT_KNOW_WHAT_IM_DOING */ + switch (c) { + case 'a': case 'b': case 'c': case 'd': case 'e': case 'f': + case 'g': case 'h': case 'i': case 'j': case 'k': case 'l': + case 'm': case 'n': case 'o': case 'p': case 'q': case 'r': + case 's': case 't': case 'u': case 'v': case 'w': case 'x': + case 'y': case 'z': + case 'A': case 'B': case 'C': case 'D': case 'E': case 'F': + case 'G': case 'H': case 'I': case 'J': case 'K': case 'L': + case 'M': case 'N': case 'O': case 'P': case 'Q': case 'R': + case 'S': case 'T': case 'U': case 'V': case 'W': case 'X': + case 'Y': case 'Z': + return true; + } + return false; +#endif /* ! I_DONT_KNOW_WHAT_IM_DOING */ +} + +/* is_alnum --- return true for alphanumeric, English only letters */ + +bool +is_alnum(int c) +{ + /* digit test is good for EBCDIC too. so there. */ + return (is_alpha(c) || ('0' <= c && c <= '9')); +} + + +/* is_identchar --- return true if c can be in an identifier */ + +bool +is_identchar(int c) +{ + return (is_alnum(c) || c == '_'); +} @@ -87,6 +87,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 bool want_source = false; static bool want_regexp = false; /* lexical scanning kludge */ @@ -146,6 +147,12 @@ static INSTRUCTION *ip_end; static INSTRUCTION *ip_endfile; static INSTRUCTION *ip_beginfile; +static INSTRUCTION *comment = NULL; +static INSTRUCTION *program_comment = NULL; +static INSTRUCTION *function_comment = NULL; + +static bool func_first = true; + static inline INSTRUCTION *list_create(INSTRUCTION *x); static inline INSTRUCTION *list_append(INSTRUCTION *l, INSTRUCTION *x); static inline INSTRUCTION *list_prepend(INSTRUCTION *l, INSTRUCTION *x); @@ -154,8 +161,6 @@ static inline INSTRUCTION *list_merge(INSTRUCTION *l1, INSTRUCTION *l2); extern double fmod(double x, double y); #define YYSTYPE INSTRUCTION * - -#define is_identchar(c) (isalnum(c) || (c) == '_') %} %token FUNC_CALL NAME REGEXP FILENAME @@ -288,9 +293,24 @@ library pattern : /* empty */ - { $$ = NULL; rule = Rule; } + { + rule = Rule; + if (comment != NULL) { + $$ = list_create(comment); + comment = NULL; + } else + $$ = NULL; + } | exp - { $$ = $1; rule = Rule; } + { + rule = Rule; + if (comment != NULL) { + $$ = list_prepend($1, comment); + comment = NULL; + } else + $$ = $1; + } + | exp ',' opt_nls exp { INSTRUCTION *tp; @@ -320,6 +340,8 @@ pattern | LEX_BEGIN { static int begin_seen = 0; + + func_first = false; if (do_lint_old && ++begin_seen == 2) warning_ln($1->source_line, _("old awk does not support multiple `BEGIN' or `END' rules")); @@ -331,6 +353,8 @@ pattern | LEX_END { static int end_seen = 0; + + func_first = false; if (do_lint_old && ++end_seen == 2) warning_ln($1->source_line, _("old awk does not support multiple `BEGIN' or `END' rules")); @@ -341,12 +365,14 @@ pattern } | LEX_BEGINFILE { + func_first = false; $1->in_rule = rule = BEGINFILE; $1->source_file = source; $$ = $1; } | LEX_ENDFILE { + func_first = false; $1->in_rule = rule = ENDFILE; $1->source_file = source; $$ = $1; @@ -356,10 +382,12 @@ pattern action : l_brace statements r_brace opt_semi opt_nls { + INSTRUCTION *ip; if ($2 == NULL) - $$ = list_create(instruction(Op_no_op)); + ip = list_create(instruction(Op_no_op)); else - $$ = $2; + ip = $2; + $$ = ip; } ; @@ -386,6 +414,22 @@ lex_builtin function_prologue : LEX_FUNCTION func_name '(' opt_param_list r_paren opt_nls { + /* + * treat any comments between BOF and the first function + * definition (with no intervening BEGIN etc block) as + * program comments. Special kludge: iff there are more + * than one such comments, treat the last as a function + * comment. + */ + if (comment != NULL && func_first + && strstr(comment->memory->stptr, "\n\n") != NULL) + split_comment(); + /* save any other pre-function comment as function comment */ + if (comment != NULL) { + function_comment = comment; + comment = NULL; + } + func_first = false; $1->source_file = source; if (install_function($2->lextok, $1, $4) < 0) YYABORT; @@ -443,19 +487,39 @@ a_slash statements : /* empty */ - { $$ = NULL; } + { + if (comment != NULL) { + $$ = list_create(comment); + comment = NULL; + } else $$ = NULL; + } | statements statement { - if ($2 == NULL) - $$ = $1; - else { + if ($2 == NULL) { + if (comment == NULL) + $$ = $1; + else { + $$ = list_append($1, comment); + comment = NULL; + } + } else { add_lint($2, LINT_no_effect); - if ($1 == NULL) - $$ = $2; - else + if ($1 == NULL) { + if (comment == NULL) + $$ = $2; + else { + $$ = list_append($2, comment); + comment = NULL; + } + } else { + if (comment != NULL) { + list_append($2, comment); + comment = NULL; + } $$ = list_merge($1, $2); + } } - yyerrok; + yyerrok; } | statements error { $$ = NULL; } @@ -499,7 +563,7 @@ statement } /* else curr = NULL; */ - for(; curr != NULL; curr = nextc) { + for (; curr != NULL; curr = nextc) { INSTRUCTION *caseexp = curr->case_exp; INSTRUCTION *casestmt = curr->case_stmt; @@ -1187,7 +1251,7 @@ opt_param_list : /* empty */ { $$ = NULL; } | param_list - { $$ = $1 ; } + { $$ = $1; } ; param_list @@ -1805,6 +1869,7 @@ struct token { # define GAWKX 0x0400 /* gawk extension */ # define BREAK 0x0800 /* break allowed inside */ # define CONTINUE 0x1000 /* continue allowed inside */ +# define DEBUG_USE 0x2000 /* for use by developers */ NODE *(*ptr)(int); /* function that implements this keyword */ NODE *(*ptr2)(int); /* alternate arbitrary-precision function */ @@ -1843,7 +1908,7 @@ static const struct token tokentab[] = { {"END", Op_rule, LEX_END, 0, 0, 0}, {"ENDFILE", Op_rule, LEX_ENDFILE, GAWKX, 0, 0}, #ifdef ARRAYDEBUG -{"adump", Op_builtin, LEX_BUILTIN, GAWKX|A(1)|A(2), do_adump, 0}, +{"adump", Op_builtin, LEX_BUILTIN, GAWKX|A(1)|A(2)|DEBUG_USE, do_adump, 0}, #endif {"and", Op_builtin, LEX_BUILTIN, GAWKX, do_and, MPF(and)}, {"asort", Op_builtin, LEX_BUILTIN, GAWKX|A(1)|A(2)|A(3), do_asort, 0}, @@ -1903,7 +1968,7 @@ static const struct token tokentab[] = { {"sqrt", Op_builtin, LEX_BUILTIN, A(1), do_sqrt, MPF(sqrt)}, {"srand", Op_builtin, LEX_BUILTIN, NOT_OLD|A(0)|A(1), do_srand, MPF(srand)}, #if defined(GAWKDEBUG) || defined(ARRAYDEBUG) /* || ... */ -{"stopme", Op_builtin, LEX_BUILTIN, GAWKX|A(0), stopme, 0}, +{"stopme", Op_builtin, LEX_BUILTIN, GAWKX|A(0)|DEBUG_USE, stopme, 0}, #endif {"strftime", Op_builtin, LEX_BUILTIN, GAWKX|A(0)|A(1)|A(2)|A(3), do_strftime, 0}, {"strtonum", Op_builtin, LEX_BUILTIN, GAWKX|A(1), do_strtonum, MPF(strtonum)}, @@ -2222,6 +2287,13 @@ 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 (comment != NULL) + (void) list_append(cp, comment); (void) list_append(cp, ip_atexit); (void) list_append(cp, instruction(Op_stop)); @@ -2254,6 +2326,12 @@ mk_program() if (begin_block != NULL) cp = list_merge(begin_block, cp); + if (program_comment != NULL) { + (void) list_prepend(cp, program_comment); + } + if (comment != NULL) { + (void) list_append(cp, comment); + } (void) list_append(cp, ip_atexit); (void) list_append(cp, instruction(Op_stop)); @@ -2755,7 +2833,7 @@ get_src_buf() lexend = lexptr + n; if (n == 0) { static bool warned = false; - if (do_lint && newfile && ! warned){ + if (do_lint && newfile && ! warned) { warned = true; sourceline = 0; lintwarn(_("source file `%s' is empty"), source); @@ -2817,7 +2895,7 @@ check_bad_char(int c) } if (iscntrl(c) && ! isspace(c)) - fatal(_("PEBKAC error: invalid character '\\%03o' in source code"), c); + fatal(_("PEBKAC error: invalid character '\\%03o' in source code"), c & 0xFF); } /* nextc --- get the next input character */ @@ -2848,7 +2926,7 @@ again: mbstate_t tmp_state; size_t mbclen; - for (idx = 0 ; lexptr + idx < lexend ; idx++) { + for (idx = 0; lexptr + idx < lexend; idx++) { tmp_state = cur_mbstate; mbclen = mbrlen(lexptr, idx + 1, &tmp_state); @@ -2927,6 +3005,79 @@ pushback(void) } +/* get_comment --- collect comment text */ + +int +get_comment(void) +{ + int c; + int sl; + tok = tokstart; + tokadd('#'); + sl = sourceline; + + while (true) { + while ((c = nextc(false)) != '\n' && c != END_FILE) { + tokadd(c); + } + if (c == '\n') { + tokadd(c); + sourceline++; + do { + c = nextc(false); + if (c == '\n') { + sourceline++; + tokadd(c); + } + } while (isspace(c) && c != END_FILE); + if (c == END_FILE) + break; + else if (c != '#') { + pushback(); + break; + } else + tokadd(c); + } else + break; + } + comment = bcalloc(Op_comment, 1, sl); + comment->source_file = source; + comment->memory = make_str_node(tokstart, tok - tokstart, 0); + + return c; +} + +/* split_comment --- split initial comment text into program and function parts */ + +static void +split_comment(void) +{ + char *p; + int l; + NODE *n; + + p = comment->memory->stptr; + l = comment->memory->stlen - 3; + /* have at least two comments so split at last blank line (\n\n) */ + while (l >= 0) { + if (p[l] == '\n' && p[l+1] == '\n') { + function_comment = comment; + n = function_comment->memory; + function_comment->memory = make_str_node(p + l + 2, n->stlen - l - 2, 0); + /* create program comment */ + program_comment = bcalloc(Op_comment, 1, sourceline); + program_comment->source_file = comment->source_file; + p[l + 2] = 0; + program_comment->memory = make_str_node(p, l + 2, 0); + comment = NULL; + freenode(n); + break; + } + else + l--; + } +} + /* allow_newline --- allow newline after &&, ||, ? and : */ static void @@ -2941,8 +3092,13 @@ allow_newline(void) break; } if (c == '#') { - while ((c = nextc(false)) != '\n' && c != END_FILE) - continue; + if (do_pretty_print && ! do_profile) { + /* collect comment byte code iff doing pretty print but not profiling. */ + c = get_comment(); + } else { + while ((c = nextc(false)) != '\n' && c != END_FILE) + continue; + } if (c == END_FILE) { pushback(); break; @@ -2965,7 +3121,8 @@ allow_newline(void) * removes the warnings. */ -static int newline_eof() +static int +newline_eof() { /* NB: a newline at end does not start a source line. */ if (lasttok != NEWLINE) { @@ -3146,9 +3303,20 @@ retry: return lasttok = NEWLINE; case '#': /* it's a comment */ - while ((c = nextc(false)) != '\n') { + if (do_pretty_print && ! do_profile) { + /* + * Collect comment byte code iff doing pretty print + * but not profiling. + */ + c = get_comment(); + if (c == END_FILE) return lasttok = NEWLINE_EOF; + } else { + while ((c = nextc(false)) != '\n') { + if (c == END_FILE) + return lasttok = NEWLINE_EOF; + } } sourceline++; return lasttok = NEWLINE; @@ -3159,7 +3327,7 @@ retry: case '\\': #ifdef RELAXED_CONTINUATION /* - * This code puports to allow comments and/or whitespace + * This code purports to allow comments and/or whitespace * after the `\' at the end of a line used for continuation. * Use it at your own risk. We think it's a bad idea, which * is why it's not on by default. @@ -3176,9 +3344,13 @@ retry: lintwarn( _("use of `\\ #...' line continuation is not portable")); } - while ((c = nextc(false)) != '\n') - if (c == END_FILE) - break; + if (do_pretty_print && ! do_profile) + c = get_comment(); + else { + while ((c = nextc(false)) != '\n') + if (c == END_FILE) + break; + } } pushback(); } @@ -3390,14 +3562,18 @@ retry: lastline = sourceline; return lasttok = c; } - did_newline++; + did_newline = true; --lexptr; /* pick up } next time */ return lasttok = NEWLINE; case '"': string: esc_seen = false; - while ((c = nextc(true)) != '"') { + /* + * Allow any kind of junk in quoted string, + * so pass false to nextc(). + */ + while ((c = nextc(false)) != '"') { if (c == '\n') { pushback(); yyerror(_("unterminated string")); @@ -3636,7 +3812,7 @@ retry: } } - if (c != '_' && ! isalpha(c)) { + if (c != '_' && ! is_alpha(c)) { yyerror(_("invalid char '%c' in expression"), c); return lasttok = LEX_EOF; } @@ -4239,6 +4415,14 @@ mk_function(INSTRUCTION *fi, INSTRUCTION *def) (t + 1)->tail_call = true; } + /* add any pre-function comment to start of action for profile.c */ + + if (function_comment != NULL) { + function_comment->source_line = 0; + (void) list_prepend(def, function_comment); + function_comment = NULL; + } + /* add an implicit return at end; * also used by 'return' command in debugger */ @@ -5058,7 +5242,6 @@ append_rule(INSTRUCTION *pattern, INSTRUCTION *action) action), tp); } - } list_append(rule_list, rp + 1); @@ -5715,3 +5898,94 @@ one_line_close(int fd) } +/* lookup_builtin --- find a builtin function or return NULL */ + +builtin_func_t +lookup_builtin(const char *name) +{ + int mid = check_special(name); + + if (mid == -1 || tokentab[mid].class != LEX_BUILTIN) + return NULL; +#ifdef HAVE_MPFR + if (do_mpfr) + return tokentab[mid].ptr2; +#endif + + return tokentab[mid].ptr; +} + +/* install_builtins --- add built-in functions to FUNCTAB */ + +void +install_builtins(void) +{ + int i, j; + + j = sizeof(tokentab) / sizeof(tokentab[0]); + for (i = 0; i < j; i++) { + if ( tokentab[i].class == LEX_BUILTIN + && (tokentab[i].flags & DEBUG_USE) == 0) { + (void) install_symbol(tokentab[i].operator, Node_builtin_func); + } + } +} + +/* + * 9/2014: Gawk cannot use <ctype.h> isalpha or isalnum when + * parsing the program since that can let through non-English + * letters. So, we supply our own. !@#$%^&*()-ing locales! + */ + +/* is_alpha --- return true if c is an English letter */ + +/* + * The scene of the murder was grisly to look upon. When the inspector + * arrived, the sergeant turned to him and said, "Another programmer stabbed + * in the back. He never knew what happened." + * + * The inspector replied, "Looks like the MO of isalpha, and his even meaner + * big brother, isalnum. The Locale brothers." The sergeant merely + * shuddered in horror. + */ + +bool +is_alpha(int c) +{ +#ifdef I_DONT_KNOW_WHAT_IM_DOING + return isalpha(c); +#else /* ! I_DONT_KNOW_WHAT_IM_DOING */ + switch (c) { + case 'a': case 'b': case 'c': case 'd': case 'e': case 'f': + case 'g': case 'h': case 'i': case 'j': case 'k': case 'l': + case 'm': case 'n': case 'o': case 'p': case 'q': case 'r': + case 's': case 't': case 'u': case 'v': case 'w': case 'x': + case 'y': case 'z': + case 'A': case 'B': case 'C': case 'D': case 'E': case 'F': + case 'G': case 'H': case 'I': case 'J': case 'K': case 'L': + case 'M': case 'N': case 'O': case 'P': case 'Q': case 'R': + case 'S': case 'T': case 'U': case 'V': case 'W': case 'X': + case 'Y': case 'Z': + return true; + } + return false; +#endif /* ! I_DONT_KNOW_WHAT_IM_DOING */ +} + +/* is_alnum --- return true for alphanumeric, English only letters */ + +bool +is_alnum(int c) +{ + /* digit test is good for EBCDIC too. so there. */ + return (is_alpha(c) || ('0' <= c && c <= '9')); +} + + +/* is_identchar --- return true if c can be in an identifier */ + +bool +is_identchar(int c) +{ + return (is_alnum(c) || c == '_'); +} diff --git a/awklib/eg/lib/ctime.awk b/awklib/eg/lib/ctime.awk index ca750370..cea25b7a 100644 --- a/awklib/eg/lib/ctime.awk +++ b/awklib/eg/lib/ctime.awk @@ -4,7 +4,8 @@ function ctime(ts, format) { - format = PROCINFO["strftime"] + format = "%a %b %e %H:%M:%S %Z %Y" + if (ts == 0) ts = systime() # use current time as default return strftime(format, ts) diff --git a/awklib/eg/lib/div.awk b/awklib/eg/lib/div.awk index 9d919288..5939024d 100644 --- a/awklib/eg/lib/div.awk +++ b/awklib/eg/lib/div.awk @@ -4,7 +4,7 @@ # Arnold Robbins, arnold@skeeve.com, Public Domain # July, 2014 -function div(numerator, denominator, result, i) +function div(numerator, denominator, result) { split("", result) diff --git a/awklib/eg/lib/ftrans.awk b/awklib/eg/lib/ftrans.awk index 1709ac82..2fec27ef 100644 --- a/awklib/eg/lib/ftrans.awk +++ b/awklib/eg/lib/ftrans.awk @@ -12,4 +12,4 @@ FNR == 1 { beginfile(FILENAME) } -END { endfile(_filename_) } +END { endfile(_filename_) } diff --git a/awklib/eg/lib/getopt.awk b/awklib/eg/lib/getopt.awk index db957ceb..6b1f4c50 100644 --- a/awklib/eg/lib/getopt.awk +++ b/awklib/eg/lib/getopt.awk @@ -38,8 +38,7 @@ function getopt(argc, argv, options, thisopt, i) i = index(options, thisopt) if (i == 0) { if (Opterr) - printf("%c -- invalid option\n", - thisopt) > "/dev/stderr" + printf("%c -- invalid option\n", thisopt) > "/dev/stderr" if (_opti >= length(argv[Optind])) { Optind++ _opti = 0 diff --git a/awklib/eg/lib/gettime.awk b/awklib/eg/lib/gettime.awk index 3da9c8ab..4cb56330 100644 --- a/awklib/eg/lib/gettime.awk +++ b/awklib/eg/lib/gettime.awk @@ -31,7 +31,7 @@ function getlocaltime(time, ret, now, i) now = systime() # return date(1)-style output - ret = strftime(PROCINFO["strftime"], now) + ret = strftime("%a %b %e %H:%M:%S %Z %Y", now) # clear out target array delete time diff --git a/awklib/eg/lib/groupawk.in b/awklib/eg/lib/groupawk.in index 0917b923..54a27f3d 100644 --- a/awklib/eg/lib/groupawk.in +++ b/awklib/eg/lib/groupawk.in @@ -5,8 +5,7 @@ # Revised October 2000 # Revised December 2010 -BEGIN \ -{ +BEGIN { # Change to suit your system _gr_awklib = "/usr/local/libexec/awk/" } @@ -39,8 +38,7 @@ function _gr_init( oldfs, oldrs, olddol0, grcat, n = split($4, a, "[ \t]*,[ \t]*") for (i = 1; i <= n; i++) if (a[i] in _gr_groupsbyuser) - _gr_groupsbyuser[a[i]] = \ - _gr_groupsbyuser[a[i]] " " $1 + _gr_groupsbyuser[a[i]] = gr_groupsbyuser[a[i]] " " $1 else _gr_groupsbyuser[a[i]] = $1 diff --git a/awklib/eg/lib/noassign.awk b/awklib/eg/lib/noassign.awk index 1f750edf..99227b37 100644 --- a/awklib/eg/lib/noassign.awk +++ b/awklib/eg/lib/noassign.awk @@ -7,7 +7,7 @@ function disable_assigns(argc, argv, i) { for (i = 1; i < argc; i++) - if (argv[i] ~ /^[[:alpha:]_][[:alnum:]_]*=.*/) + if (argv[i] ~ /^[a-zA-Z_][a-zA-Z0-9_]*=.*/) argv[i] = ("./" argv[i]) } diff --git a/awklib/eg/lib/processarray.awk b/awklib/eg/lib/processarray.awk new file mode 100644 index 00000000..79a86d1f --- /dev/null +++ b/awklib/eg/lib/processarray.awk @@ -0,0 +1,12 @@ +function process_array(arr, name, process, do_arrays, i, new_name) +{ + for (i in arr) { + new_name = (name "[" i "]") + if (isarray(arr[i])) { + if (do_arrays) + @process(new_name, arr[i]) + process_array(arr[i], new_name, process, do_arrays) + } else + @process(new_name, arr[i]) + } +} diff --git a/awklib/eg/lib/quicksort.awk b/awklib/eg/lib/quicksort.awk index 43357ac6..3ba2d6e3 100644 --- a/awklib/eg/lib/quicksort.awk +++ b/awklib/eg/lib/quicksort.awk @@ -26,7 +26,7 @@ function quicksort(data, left, right, less_than, i, last) # quicksort_swap --- helper function for quicksort, should really be inline -function quicksort_swap(data, i, j, temp) +function quicksort_swap(data, i, j, temp) { temp = data[i] data[i] = data[j] diff --git a/awklib/eg/lib/readable.awk b/awklib/eg/lib/readable.awk index 6942dcca..37970a82 100644 --- a/awklib/eg/lib/readable.awk +++ b/awklib/eg/lib/readable.awk @@ -6,7 +6,7 @@ BEGIN { for (i = 1; i < ARGC; i++) { - if (ARGV[i] ~ /^[[:alpha:]_][[:alnum:]_]*=.*/ \ + if (ARGV[i] ~ /^[a-zA-Z_][a-zA-Z0-9_]*=.*/ \ || ARGV[i] == "-" || ARGV[i] == "/dev/stdin") continue # assignment or standard input else if ((getline junk < ARGV[i]) < 0) # unreadable diff --git a/awklib/eg/lib/shellquote.awk b/awklib/eg/lib/shellquote.awk new file mode 100644 index 00000000..cd943dc7 --- /dev/null +++ b/awklib/eg/lib/shellquote.awk @@ -0,0 +1,22 @@ +# shell_quote --- quote an argument for passing to the shell +# +# Michael Brennan +# brennan@madronabluff.com +# September 2014 + +function shell_quote(s, # parameter + SINGLE, QSINGLE, i, X, n, ret) # locals +{ + if (s == "") + return "\"\"" + + SINGLE = "\x27" # single quote + QSINGLE = "\"\x27\"" + n = split(s, X, SINGLE) + + ret = SINGLE X[1] SINGLE + for (i = 2; i <= n; i++) + ret = ret QSINGLE SINGLE X[i] SINGLE + + return ret +} diff --git a/awklib/eg/lib/strtonum.awk b/awklib/eg/lib/strtonum.awk index 9342e789..cd56a449 100644 --- a/awklib/eg/lib/strtonum.awk +++ b/awklib/eg/lib/strtonum.awk @@ -13,8 +13,9 @@ function mystrtonum(str, ret, n, i, k, c) ret = 0 for (i = 1; i <= n; i++) { c = substr(str, i, 1) - if ((k = index("01234567", c)) > 0) - k-- # adjust for 1-basing in awk + # index() returns 0 if c not in string, + # includes c == "0" + k = index("1234567", c) ret = ret * 8 + k } @@ -26,6 +27,8 @@ function mystrtonum(str, ret, n, i, k, c) for (i = 1; i <= n; i++) { c = substr(str, i, 1) c = tolower(c) + # index() returns 0 if c not in string, + # includes c == "0" k = index("123456789abcdef", c) ret = ret * 16 + k @@ -48,7 +51,7 @@ function mystrtonum(str, ret, n, i, k, c) # a[5] = "123.45" # a[6] = "1.e3" # a[7] = "1.32" -# a[7] = "1.32E2" +# 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/misc/arraymax.awk b/awklib/eg/misc/arraymax.awk index 20dd1768..64197f56 100644 --- a/awklib/eg/misc/arraymax.awk +++ b/awklib/eg/misc/arraymax.awk @@ -1,10 +1,10 @@ { - if ($1 > max) - max = $1 - arr[$1] = $0 + if ($1 > max) + max = $1 + arr[$1] = $0 } END { - for (x = 1; x <= max; x++) - print arr[x] + for (x = 1; x <= max; x++) + print arr[x] } diff --git a/awklib/eg/misc/findpat.awk b/awklib/eg/misc/findpat.awk index e9bef9ea..9d799434 100644 --- a/awklib/eg/misc/findpat.awk +++ b/awklib/eg/misc/findpat.awk @@ -1,10 +1,9 @@ { - if ($1 == "FIND") - regex = $2 - else { - where = match($0, regex) - if (where != 0) - print "Match of", regex, "found at", - where, "in", $0 + if ($1 == "FIND") + regex = $2 + else { + where = match($0, regex) + if (where != 0) + print "Match of", regex, "found at", where, "in", $0 } } diff --git a/awklib/eg/prog/alarm.awk b/awklib/eg/prog/alarm.awk index 63cf64a4..59630ea8 100644 --- a/awklib/eg/prog/alarm.awk +++ b/awklib/eg/prog/alarm.awk @@ -8,8 +8,7 @@ # usage: alarm time [ "message" [ count [ delay ] ] ] -BEGIN \ -{ +BEGIN { # Initial argument sanity checking usage1 = "usage: alarm time ['message' [count [delay]]]" usage2 = sprintf("\t(%s) time ::= hh:mm", ARGV[1]) diff --git a/awklib/eg/prog/cut.awk b/awklib/eg/prog/cut.awk index 04d9bc11..080279bc 100644 --- a/awklib/eg/prog/cut.awk +++ b/awklib/eg/prog/cut.awk @@ -12,16 +12,13 @@ # # Requires getopt() and join() library functions -function usage( e1, e2) +function usage() { - e1 = "usage: cut [-f list] [-d c] [-s] [files...]" - e2 = "usage: cut [-c list] [files...]" - print e1 > "/dev/stderr" - print e2 > "/dev/stderr" + print("usage: cut [-f list] [-d c] [-s] [files...]") > "/dev/stderr" + print("usage: cut [-c list] [files...]") > "/dev/stderr" exit 1 } -BEGIN \ -{ +BEGIN { FS = "\t" # default OFS = FS while ((c = getopt(ARGC, ARGV, "sf:c:d:")) != -1) { diff --git a/awklib/eg/prog/egrep.awk b/awklib/eg/prog/egrep.awk index 86b3cfda..a4165a90 100644 --- a/awklib/eg/prog/egrep.awk +++ b/awklib/eg/prog/egrep.awk @@ -88,14 +88,12 @@ function endfile(file) print } } -END \ -{ +END { exit (total == 0) } -function usage( e) +function usage() { - e = "Usage: egrep [-csvil] [-e pat] [files ...]" - e = e "\n\tegrep [-csvil] pat [files ...]" - print e > "/dev/stderr" + print("Usage: egrep [-csvil] [-e pat] [files ...]") > "/dev/stderr" + print("\n\tegrep [-csvil] pat [files ...]") > "/dev/stderr" exit 1 } diff --git a/awklib/eg/prog/extract.awk b/awklib/eg/prog/extract.awk index 12e30b54..24f40ce5 100644 --- a/awklib/eg/prog/extract.awk +++ b/awklib/eg/prog/extract.awk @@ -1,5 +1,4 @@ -# extract.awk --- extract files and run programs -# from texinfo files +# extract.awk --- extract files and run programs from texinfo files # # Arnold Robbins, arnold@skeeve.com, Public Domain # May 1993 @@ -7,8 +6,7 @@ BEGIN { IGNORECASE = 1 } -/^@c(omment)?[ \t]+system/ \ -{ +/^@c(omment)?[ \t]+system/ { if (NF < 3) { e = ("extract: " FILENAME ":" FNR) e = (e ": badly formed `system' line") @@ -24,8 +22,7 @@ BEGIN { IGNORECASE = 1 } print e > "/dev/stderr" } } -/^@c(omment)?[ \t]+file/ \ -{ +/^@c(omment)?[ \t]+file/ { if (NF != 3) { e = ("extract: " FILENAME ":" FNR ": badly formed `file' line") print e > "/dev/stderr" @@ -66,7 +63,7 @@ BEGIN { IGNORECASE = 1 } function unexpected_eof() { printf("extract: %s:%d: unexpected EOF or error\n", - FILENAME, FNR) > "/dev/stderr" + FILENAME, FNR) > "/dev/stderr" exit 1 } diff --git a/awklib/eg/prog/id.awk b/awklib/eg/prog/id.awk index cf744447..b6061f9b 100644 --- a/awklib/eg/prog/id.awk +++ b/awklib/eg/prog/id.awk @@ -6,13 +6,13 @@ # May 1993 # Revised February 1996 # Revised May 2014 +# Revised September 2014 # output is: # uid=12(foo) euid=34(bar) gid=3(baz) \ # egid=5(blat) groups=9(nine),2(two),1(one) -BEGIN \ -{ +BEGIN { uid = PROCINFO["uid"] euid = PROCINFO["euid"] gid = PROCINFO["gid"] @@ -20,26 +20,22 @@ BEGIN \ printf("uid=%d", uid) pw = getpwuid(uid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (euid != uid) { printf(" euid=%d", euid) pw = getpwuid(euid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) } printf(" gid=%d", gid) pw = getgrgid(gid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (egid != gid) { printf(" egid=%d", egid) pw = getgrgid(egid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) } for (i = 1; ("group" i) in PROCINFO; i++) { @@ -48,8 +44,7 @@ BEGIN \ group = PROCINFO["group" i] printf("%d", group) pw = getgrgid(group) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (("group" (i+1)) in PROCINFO) printf(",") } @@ -59,6 +54,8 @@ BEGIN \ function pr_first_field(str, a) { - split(str, a, ":") - printf("(%s)", a[1]) + if (str != "") { + split(str, a, ":") + printf("(%s)", a[1]) + } } diff --git a/awklib/eg/prog/labels.awk b/awklib/eg/prog/labels.awk index abf53c3b..3195809b 100644 --- a/awklib/eg/prog/labels.awk +++ b/awklib/eg/prog/labels.awk @@ -48,7 +48,6 @@ function printpage( i, j) Count++ } -END \ -{ +END { printpage() } diff --git a/awklib/eg/prog/pi.awk b/awklib/eg/prog/pi.awk new file mode 100644 index 00000000..3297beff --- /dev/null +++ b/awklib/eg/prog/pi.awk @@ -0,0 +1,18 @@ +# pi.awk --- compute the digits of pi +# +# Katie Wasserman, katie@wass.net +# August 2014 + +BEGIN { + digits = 100000 + two = 2 * 10 ^ digits + pi = two + for (m = digits * 4; m > 0; --m) { + d = m * 2 + 1 + x = pi * m + div(x, d, result) + pi = result["quotient"] + pi = pi + two + } + print pi +} diff --git a/awklib/eg/prog/split.awk b/awklib/eg/prog/split.awk index bcc73ae6..6a7198f6 100644 --- a/awklib/eg/prog/split.awk +++ b/awklib/eg/prog/split.awk @@ -50,9 +50,8 @@ BEGIN { } print > out } -function usage( e) +function usage() { - e = "usage: split [-num] [file] [outname]" - print e > "/dev/stderr" + print("usage: split [-num] [file] [outname]") > "/dev/stderr" exit 1 } diff --git a/awklib/eg/prog/tee.awk b/awklib/eg/prog/tee.awk index 639b9f80..fd9985f1 100644 --- a/awklib/eg/prog/tee.awk +++ b/awklib/eg/prog/tee.awk @@ -7,8 +7,7 @@ # May 1993 # Revised December 1995 -BEGIN \ -{ +BEGIN { for (i = 1; i < ARGC; i++) copy[i] = ARGV[i] @@ -35,8 +34,7 @@ BEGIN \ print > copy[i] print } -END \ -{ +END { for (i in copy) close(copy[i]) } diff --git a/awklib/eg/prog/uniq.awk b/awklib/eg/prog/uniq.awk index 990387ac..7dd16099 100644 --- a/awklib/eg/prog/uniq.awk +++ b/awklib/eg/prog/uniq.awk @@ -5,10 +5,9 @@ # Arnold Robbins, arnold@skeeve.com, Public Domain # May 1993 -function usage( e) +function usage() { - e = "Usage: uniq [-udc [-n]] [+n] [ in [ out ]]" - print e > "/dev/stderr" + print("Usage: uniq [-udc [-n]] [+n] [ in [ out ]]") > "/dev/stderr" exit 1 } @@ -18,8 +17,7 @@ function usage( e) # -n skip n fields # +n skip n characters, skip fields first -BEGIN \ -{ +BEGIN { count = 1 outputfile = "/dev/stdout" opts = "udc0:1:2:3:4:5:6:7:8:9:" @@ -31,7 +29,7 @@ BEGIN \ else if (c == "c") do_count++ else if (index("0123456789", c) != 0) { - # getopt requires args to options + # getopt() requires args to options # this messes us up for things like -5 if (Optarg ~ /^[[:digit:]]+$/) fcount = (c Optarg) + 0 @@ -1569,7 +1569,7 @@ mpf1: s0 = s1; break; default: - if (do_lint && isalpha(cs1)) + if (do_lint && is_alpha(cs1)) lintwarn(_("ignoring unknown format specifier character `%c': no argument converted"), cs1); break; } @@ -1759,7 +1759,14 @@ do_substr(int nargs) else if (do_lint == DO_LINT_INVALID && ! (d_length >= 0)) lintwarn(_("substr: length %g is not >= 0"), d_length); DEREF(t1); - return dupnode(Nnull_string); + /* + * Return explicit null string instead of doing + * dupnode(Nnull_string) so that if the result + * is checked with the combination of length() + * and lint, no error is reported about using + * an uninitialized value. Same thing later, too. + */ + return make_string("", 0); } if (do_lint) { if (double_to_int(d_length) != d_length) @@ -1813,7 +1820,7 @@ do_substr(int nargs) if (do_lint && (do_lint == DO_LINT_ALL || ((indx | length) != 0))) lintwarn(_("substr: source string is zero length")); DEREF(t1); - return dupnode(Nnull_string); + return make_string("", 0); } /* get total len of input string, for following checks */ @@ -1830,7 +1837,7 @@ do_substr(int nargs) lintwarn(_("substr: start index %g is past end of string"), d_index); DEREF(t1); - return dupnode(Nnull_string); + return make_string("", 0); } if (length > src_len - indx) { if (do_lint) @@ -2648,6 +2648,8 @@ struct cmdtoken cmdtab[] = { gettext_noop("up [N] - move N frames up the stack.") }, { "watch", "w", D_watch, D_WATCH, do_watch, gettext_noop("watch var - set a watchpoint for a variable.") }, +{ "where", "", D_backtrace, D_BACKTRACE, do_backtrace, + gettext_noop("where [N] - (same as backtrace) print trace of all or N innermost (outermost if N < 0) frames.") }, { NULL, NULL, D_illegal, 0, (Func_cmd) 0, NULL }, }; @@ -2863,7 +2865,7 @@ again: } while (c != '\0' && c != ' ' && c != '\t') { - if (! isalpha(c) && ! in_eval) { + if (! is_alpha(c) && ! in_eval) { yyerror(_("invalid character in command")); return '\n'; } @@ -3031,12 +3033,12 @@ err: || c == ',' || c == '=') return *lexptr++; - if (c != '_' && ! isalpha(c)) { + if (c != '_' && ! is_alpha(c)) { yyerror(_("invalid character")); return '\n'; } - while (isalnum(c) || c == '_') + while (is_identchar(c)) c = *++lexptr; toklen = lexptr - tokstart; @@ -897,6 +897,8 @@ struct cmdtoken cmdtab[] = { gettext_noop("up [N] - move N frames up the stack.") }, { "watch", "w", D_watch, D_WATCH, do_watch, gettext_noop("watch var - set a watchpoint for a variable.") }, +{ "where", "", D_backtrace, D_BACKTRACE, do_backtrace, + gettext_noop("where [N] - (same as backtrace) print trace of all or N innermost (outermost if N < 0) frames.") }, { NULL, NULL, D_illegal, 0, (Func_cmd) 0, NULL }, }; @@ -1112,7 +1114,7 @@ again: } while (c != '\0' && c != ' ' && c != '\t') { - if (! isalpha(c) && ! in_eval) { + if (! is_alpha(c) && ! in_eval) { yyerror(_("invalid character in command")); return '\n'; } @@ -1280,12 +1282,12 @@ err: || c == ',' || c == '=') return *lexptr++; - if (c != '_' && ! isalpha(c)) { + if (c != '_' && ! is_alpha(c)) { yyerror(_("invalid character")); return '\n'; } - while (isalnum(c) || c == '_') + while (is_identchar(c)) c = *++lexptr; toklen = lexptr - tokstart; @@ -195,6 +195,9 @@ /* Define to 1 if you have the <stdlib.h> header file. */ #undef HAVE_STDLIB_H +/* Define to 1 if you have the `strcasecmp' function. */ +#undef HAVE_STRCASECMP + /* Define to 1 if you have the `strchr' function. */ #undef HAVE_STRCHR @@ -317,8 +320,8 @@ /* Define to 1 if the system has the type `_Bool'. */ #undef HAVE__BOOL -/* libc is broken for regex handling */ -#undef LIBC_IS_BORKED +/* enable severe portability problems */ +#undef I_DONT_KNOW_WHAT_IM_DOING /* disable lint checks */ #undef NO_LINT @@ -761,6 +761,7 @@ enable_option_checking enable_silent_rules with_whiny_user_strftime enable_lint +enable_severe_portability_problems enable_dependency_tracking enable_largefile enable_nls @@ -1405,6 +1406,7 @@ Optional Features: --enable-silent-rules less verbose build output (undo: "make V=1") --disable-silent-rules verbose build output (undo: "make V=0") --disable-lint Disable gawk lint checking + --enable-severe-portability-problems Enable really nasty portability problems --enable-dependency-tracking do not reject slow dependency extractors --disable-dependency-tracking @@ -3181,6 +3183,17 @@ $as_echo "#define NO_LINT 1" >>confdefs.h fi +# Check whether --enable-severe-portability-problems was given. +if test "${enable_severe_portability_problems+set}" = set; then : + enableval=$enable_severe_portability_problems; if test "$enableval" = yes + then + +$as_echo "#define I_DONT_KNOW_WHAT_IM_DOING 1" >>confdefs.h + + fi + +fi + # Make sure we can run config.sub. $SHELL "$ac_aux_dir/config.sub" sun4 >/dev/null 2>&1 || @@ -5999,14 +6012,6 @@ then CFLAGS="$CFLAGS -D_SYSV3" fi -case $host_os in -mirbsd*) - -$as_echo "#define LIBC_IS_BORKED 1" >>confdefs.h - - ;; -esac - ac_ext=c ac_cpp='$CPP $CPPFLAGS' ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' @@ -10007,7 +10012,7 @@ for ac_func in atexit btowc fmod getgrent getgroups grantpt \ isascii iswctype iswlower iswupper mbrlen \ memcmp memcpy memcpy_ulong memmove memset \ memset_ulong mkstemp posix_openpt setenv setlocale setsid snprintf strchr \ - strerror strftime strncasecmp strcoll strtod strtoul \ + strerror strftime strcasecmp strncasecmp strcoll strtod strtoul \ system tmpfile towlower towupper tzset usleep wcrtomb \ wcscoll wctype do : diff --git a/configure.ac b/configure.ac index e7e2d5f6..6122ee07 100644 --- a/configure.ac +++ b/configure.ac @@ -58,6 +58,12 @@ AC_ARG_ENABLE([lint], [ --disable-lint Disable gawk lint checking], AC_DEFINE(NO_LINT, 1, [disable lint checks]) fi ) +AC_ARG_ENABLE([severe-portability-problems], [ --enable-severe-portability-problems Enable really nasty portability problems], + if test "$enableval" = yes + then + AC_DEFINE(I_DONT_KNOW_WHAT_IM_DOING, 1, [enable severe portability problems]) + fi +) AC_CANONICAL_HOST AC_USE_SYSTEM_EXTENSIONS @@ -119,13 +125,6 @@ dnl need -D_SYSV3 for ISC CFLAGS="$CFLAGS -D_SYSV3" fi -dnl check for systems where libc is borked for regex handling -case $host_os in -mirbsd*) - AC_DEFINE([LIBC_IS_BORKED], 1, [libc is broken for regex handling]) - ;; -esac - dnl Set the programming language for checks. Fortunately, dnl this only needs to be set once, since everything is in C. AC_LANG([C]) @@ -275,7 +274,7 @@ AC_CHECK_FUNCS(atexit btowc fmod getgrent getgroups grantpt \ isascii iswctype iswlower iswupper mbrlen \ memcmp memcpy memcpy_ulong memmove memset \ memset_ulong mkstemp posix_openpt setenv setlocale setsid snprintf strchr \ - strerror strftime strncasecmp strcoll strtod strtoul \ + strerror strftime strcasecmp strncasecmp strcoll strtod strtoul \ system tmpfile towlower towupper tzset usleep wcrtomb \ wcscoll wctype) dnl this check is for both mbrtowc and the mbstate_t type, which is good @@ -3995,6 +3995,7 @@ print_instruction(INSTRUCTION *pc, Func_print print_func, FILE *fp, int in_dump) case Op_quotient_i: case Op_mod_i: case Op_assign_concat: + case Op_comment: print_memory(pc->memory, func, print_func, fp); /* fall through */ default: @@ -77,14 +77,6 @@ is_blank (int c) } #endif /* GAWK */ -#ifdef LIBC_IS_BORKED -extern int gawk_mb_cur_max; -#undef MB_CUR_MAX -#define MB_CUR_MAX gawk_mb_cur_max -#undef mbrtowc -#define mbrtowc(a, b, c, d) (-1) -#endif - /* HPUX defines these as macros in sys/param.h. */ #ifdef setbit # undef setbit @@ -375,6 +367,9 @@ struct dfa token utf8_anychar_classes[5]; /* To lower ANYCHAR in UTF-8 locales. */ mbstate_t mbs; /* Multibyte conversion state. */ + /* dfaexec implementation. */ + char *(*dfaexec) (struct dfa *, char const *, char *, int, size_t *, int *); + /* The following are valid only if MB_CUR_MAX > 1. */ /* The value of multibyte_prop[i] is defined by following rule. @@ -828,10 +823,6 @@ using_utf8 (void) wchar_t wc; mbstate_t mbs = { 0 }; utf8 = mbrtowc (&wc, "\xc4\x80", 2, &mbs) == 2 && wc == 0x100; -#ifdef LIBC_IS_BORKED - if (gawk_mb_cur_max == 1) - utf8 = 0; -#endif } return utf8; } @@ -3321,6 +3312,24 @@ transit_state (struct dfa *d, state_num s, unsigned char const **pp, return s1; } +/* The initial state may encounter a byte which is not a single byte character + nor the first byte of a multibyte character. But it is incorrect for the + initial state to accept such a byte. For example, in Shift JIS the regular + expression "\\" accepts the codepoint 0x5c, but should not accept the second + byte of the codepoint 0x815c. Then the initial state must skip the bytes + that are not a single byte character nor the first byte of a multibyte + character. */ +static unsigned char const * +skip_remains_mb (struct dfa *d, unsigned char const *p, + unsigned char const *mbp, char const *end) +{ + wint_t wc; + while (mbp < p) + mbp += mbs_to_wchar (&wc, (char const *) mbp, + end - (char const *) mbp, d); + return mbp; +} + /* Search through a buffer looking for a match to the given struct dfa. Find the first occurrence of a string matching the regexp in the buffer, and the shortest possible version thereof. Return a pointer to @@ -3332,10 +3341,14 @@ transit_state (struct dfa *d, state_num s, unsigned char const **pp, If COUNT is non-NULL, increment *COUNT once for each newline processed. Finally, if BACKREF is non-NULL set *BACKREF to indicate whether we encountered a back-reference (1) or not (0). The caller may use this - to decide whether to fall back on a backtracking matcher. */ -char * -dfaexec (struct dfa *d, char const *begin, char *end, - int allow_nl, size_t *count, int *backref) + to decide whether to fall back on a backtracking matcher. + + If MULTIBYTE, the input consists of multibyte characters and/or + encoding-error bytes. Otherwise, the input consists of single-byte + characters. */ +static inline char * +dfaexec_main (struct dfa *d, char const *begin, char *end, + int allow_nl, size_t *count, int *backref, bool multibyte) { state_num s, s1; /* Current state. */ unsigned char const *p, *mbp; /* Current input character. */ @@ -3357,7 +3370,7 @@ dfaexec (struct dfa *d, char const *begin, char *end, saved_end = *(unsigned char *) end; *end = eol; - if (d->multibyte) + if (multibyte) { memset (&d->mbs, 0, sizeof d->mbs); if (! d->mb_match_lens) @@ -3369,7 +3382,7 @@ dfaexec (struct dfa *d, char const *begin, char *end, for (;;) { - if (d->multibyte) + if (multibyte) { while ((t = trans[s]) != NULL) { @@ -3377,27 +3390,18 @@ dfaexec (struct dfa *d, char const *begin, char *end, if (s == 0) { - /* The initial state may encounter a byte which is not - a single byte character nor the first byte of a - multibyte character. But it is incorrect for the - initial state to accept such a byte. For example, - in Shift JIS the regular expression "\\" accepts - the codepoint 0x5c, but should not accept the second - byte of the codepoint 0x815c. Then the initial - state must skip the bytes that are not a single - byte character nor the first byte of a multibyte - character. */ - wint_t wc; - while (mbp < p) - mbp += mbs_to_wchar (&wc, (char const *) mbp, - end - (char const *) mbp, d); - p = mbp; - - if ((char *) p > end) + if (d->states[s].mbps.nelem == 0) { - p = NULL; - goto done; + do + { + while (t[*p] == 0) + p++; + p = mbp = skip_remains_mb (d, p, mbp, end); + } + while (t[*p] == 0); } + else + p = mbp = skip_remains_mb (d, p, mbp, end); } if (d->states[s].mbps.nelem == 0) @@ -3416,15 +3420,49 @@ dfaexec (struct dfa *d, char const *begin, char *end, goto done; } - /* Can match with a multibyte character (and multi character - collating element). Transition table might be updated. */ - s = transit_state (d, s, &p, (unsigned char *) end); - mbp = p; - trans = d->trans; + /* The following code is used twice. + Use a macro to avoid the risk that they diverge. */ +#define State_transition() \ + do { \ + /* Can match with a multibyte character (and multi-character \ + collating element). Transition table might be updated. */ \ + s = transit_state (d, s, &p, (unsigned char *) end); \ + \ + /* If previous character is newline after a transition \ + for ANYCHAR or MBCSET in non-UTF8 multibyte locales, \ + check whether current position is beyond the end of \ + the input buffer. Also, transit to initial state if \ + !ALLOW_NL, even if RE_DOT_NEWLINE is set. */ \ + if (p[-1] == eol) \ + { \ + if ((char *) p > end) \ + { \ + p = NULL; \ + goto done; \ + } \ + \ + nlcount++; \ + \ + if (!allow_nl) \ + s = 0; \ + } \ + \ + mbp = p; \ + trans = d->trans; \ + } while (0) + + State_transition(); } } else { + if (s == 0 && (t = trans[s]) != NULL) + { + while (t[*p] == 0) + p++; + s = t[*p++]; + } + while ((t = trans[s]) != NULL) { s1 = t[*p++]; @@ -3455,14 +3493,8 @@ dfaexec (struct dfa *d, char const *begin, char *end, } s1 = s; - if (d->multibyte) - { - /* Can match with a multibyte character (and multicharacter - collating element). Transition table might be updated. */ - s = transit_state (d, s, &p, (unsigned char *) end); - mbp = p; - trans = d->trans; - } + if (multibyte) + State_transition(); else s = d->fails[s][*p++]; continue; @@ -3500,6 +3532,33 @@ dfaexec (struct dfa *d, char const *begin, char *end, return (char *) p; } +/* Specialized versions of dfaexec_main for multibyte and single-byte + cases. This is for performance. */ + +static char * +dfaexec_mb (struct dfa *d, char const *begin, char *end, + int allow_nl, size_t *count, int *backref) +{ + return dfaexec_main (d, begin, end, allow_nl, count, backref, true); +} + +static char * +dfaexec_sb (struct dfa *d, char const *begin, char *end, + int allow_nl, size_t *count, int *backref) +{ + return dfaexec_main (d, begin, end, allow_nl, count, backref, false); +} + +/* Like dfaexec_main (D, BEGIN, END, ALLOW_NL, COUNT, BACKREF, D->multibyte), + but faster. */ + +char * +dfaexec (struct dfa *d, char const *begin, char *end, + int allow_nl, size_t *count, int *backref) +{ + return d->dfaexec (d, begin, end, allow_nl, count, backref); +} + struct dfa * dfasuperset (struct dfa const *d) { @@ -3549,6 +3608,7 @@ dfainit (struct dfa *d) { memset (d, 0, sizeof *d); d->multibyte = MB_CUR_MAX > 1; + d->dfaexec = d->multibyte ? dfaexec_mb : dfaexec_sb; d->fast = !d->multibyte; } @@ -3589,6 +3649,7 @@ dfaoptimize (struct dfa *d) free_mbdata (d); d->multibyte = false; + d->dfaexec = dfaexec_sb; } static void @@ -3602,6 +3663,7 @@ dfassbuild (struct dfa *d) *sup = *d; sup->multibyte = false; + sup->dfaexec = dfaexec_sb; sup->multibyte_prop = NULL; sup->mbcsets = NULL; sup->superset = NULL; diff --git a/doc/ChangeLog b/doc/ChangeLog index 01da6377..ed2a2761 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,158 @@ +2014-10-13 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Fix example outputs in chapter 2. + Improve description of SYMTAB. + +2014-10-12 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Revise doc for {INT,STR}_CHAIN_MAX. Remove Pat + Rankin from VMS duties (per his request). Add a small TeX fix + for the table in ch 16 for requesting values. + +2014-10-05 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Finished changes! + +2014-10-03 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (EMRED): Renamed from EMISTERED to match original. + Thanks to Warren Toomey at TUHS for access to archives recording + the text. + +2014-10-02 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Pretty much done! + + Unrelated: + + * gawktexi.in: Fix braino in awk version of div function. + Thanks to Katie Wasserman for the catch. + +2014-10-01 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More fixes after reading through the MS. + + Unrelated: + + * gawktexi.in: Add Katie Wasserman's program to compute + the digits of PI. + + Unrelated: + + * gawktexi.in: Document the differences between profiling + and pretty printing. + +2014-09-30 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More fixes after reading through the MS. + +2014-09-29 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More fixes after reading through the MS. + And still more fixes. + +2014-09-28 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More fixes after reading through the MS. + Document the debugger's "where" command. + +2014-09-27 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Lots more fixes after reading through the MS. + +2014-09-23 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Rework the documentation of special files in + Chapter 5; some reordering as well as rewriting. + +2014-09-22 Arnold D. Robbins <arnold@skeeve.com> + + * gawktex.in: Continue fixes after reading through the MS. + +2014-09-21 Arnold D. Robbins <arnold@skeeve.com> + + * gawktex.in: Start on fixes after reading through the MS. + +2014-09-18 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Fix italics in quotations. Some docbook special + cases. + +2014-09-15 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Document that identifiers must use the English + letters. + +2014-09-14 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More edits during review, minor addition. + +2014-09-08 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Remove text that won't get used. + +2014-09-07 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Minor cleanups. + +2014-09-05 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Document builtin functions in FUNCTAB and in + PROCINFO["identifiers"]. + * gawk.1: Ditto. + + Unrelated: + + * gawktexi.in: More stuff from reviewer comments. + +2014-09-04 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Document that indirect calls now work on built-in + and extension functions. + * gawk.1: Same. + +2014-09-03 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Further fixes from reviews and bug reports. + +2014-09-02 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Corrections to walkthrough in debugger chapter. + Thanks to David Ward <dlward134@gmail.com> for the problem report. + +2014-09-01 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Add index entry for @ - @load, @include, + and indirect function calls. Thanks to "Kenny McKormack" in + comp.lang.awk. + +2014-08-29 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Continuing on reviewer comments, and other + bug fixes, miscellanious improvements. + +2014-08-26 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Use a different mechanism to exclude + exercises. Remove use of LC_ALL in an example; doesn't seem + to be needed anymore. + + Unrelated: + + * gawktexi.in: Document that MirBSD is no longer supported. + +2014-08-25 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Exercises are excluded from print edition. + +2014-08-24 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Continuing on reviewer comments. + +2014-08-23 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Continuing on reviewer comments. + 2014-08-22 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Continuing on reviewer comments. @@ -13,7 +13,7 @@ . if \w'\(rq' .ds rq "\(rq . \} .\} -.TH GAWK 1 "Jul 10 2014" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "Aug 03 2014" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -1132,9 +1132,14 @@ For each identifier, the value of the element is one of the following: \fB"array"\fR The identifier is an array. .TP +\fB"builtin"\fR +The identifier is a built-in function. +.TP \fB"extension"\fR The identifier is an extension function loaded via -.BR @load . +.B @load +or +.BR \-l . .TP \fB"scalar"\fR The identifier is a scalar. @@ -3287,7 +3292,7 @@ sign, like so: .RS .ft B .nf -function myfunc() +function myfunc() { print "myfunc called" \&.\|.\|. @@ -3301,6 +3306,8 @@ function myfunc() .fi .ft R .RE +As of version 4.1.2, this works with user-defined functions, +built-in functions, and extension functions. .PP If .B \-\^\-lint diff --git a/doc/gawk.info b/doc/gawk.info index 05434558..caa557e8 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -14,7 +14,7 @@ Free Software Foundation, Inc. This is Edition 4.1 of `GAWK: Effective AWK Programming: A User's -Guide for GNU Awk', for the 4.1.1 (or later) version of the GNU +Guide for GNU Awk', for the 4.1.2 (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document @@ -42,7 +42,7 @@ Free Software Foundation, Inc. This is Edition 4.1 of `GAWK: Effective AWK Programming: A User's -Guide for GNU Awk', for the 4.1.1 (or later) version of the GNU +Guide for GNU Awk', for the 4.1.2 (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document @@ -170,10 +170,10 @@ entitled "GNU Free Documentation License". * Escape Sequences:: How to write nonprinting characters. * Regexp Operators:: Regular Expression Operators. * Bracket Expressions:: What can go between `[...]'. -* GNU Regexp Operators:: Operators specific to GNU software. -* Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* GNU Regexp Operators:: Operators specific to GNU software. +* Case-sensitivity:: How to do case-insensitive matching. * Regexp Summary:: Regular expressions summary. * Records:: Controlling how data is split into records. @@ -189,8 +189,8 @@ entitled "GNU Free Documentation License". * Regexp Field Splitting:: Using regexps as the field separator. * Single Character Fields:: Making each character a separate field. -* Command Line Field Separator:: Setting `FS' from the - command line. +* Command Line Field Separator:: Setting `FS' from the command + line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -234,17 +234,19 @@ entitled "GNU Free Documentation License". * Printf Examples:: Several examples. * Redirection:: How to redirect output to multiple files and pipes. +* Special FD:: Special files for I/O. * Special Files:: File name interpretation in `gawk'. `gawk' allows access to inherited file descriptors. -* Special FD:: Special files for I/O. +* Other Inherited Files:: Accessing other open files with + `gawk'. * Special Network:: Special files for network communications. * Special Caveats:: Things to watch out for. * Close Files And Pipes:: Closing Input and Output Files and Pipes. * Output Summary:: Output summary. -* Output exercises:: Exercises. +* Output Exercises:: Exercises. * Values:: Constants, Variables, and Regular Expressions. * Constants:: String, numeric and regexp constants. @@ -330,7 +332,7 @@ entitled "GNU Free Documentation License". record. * Nextfile Statement:: Stop processing the current file. * Exit Statement:: Stop execution of `awk'. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * User-modified:: Built-in variables that you change to control `awk'. * Auto-set:: Built-in variables where `awk' @@ -350,12 +352,12 @@ entitled "GNU Free Documentation License". elements. * Controlling Scanning:: Controlling the order in which arrays are scanned. -* Delete:: The `delete' statement removes an - element from an array. * Numeric Array Subscripts:: How to use numbers as subscripts in `awk'. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. +* Delete:: The `delete' statement removes an + element from an array. * Multidimensional:: Emulating multidimensional arrays in `awk'. * Multiscanning:: Scanning multidimensional arrays. @@ -414,6 +416,8 @@ entitled "GNU Free Documentation License". * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the + shell. * Data File Management:: Functions for managing command-line data files. * Filetrans Function:: A function for handling data file @@ -431,7 +435,7 @@ entitled "GNU Free Documentation License". information. * Walking Arrays:: A function to walk arrays of arrays. * Library Functions Summary:: Summary of library functions. -* Library exercises:: Exercises. +* Library Exercises:: Exercises. * Running Examples:: How to run these examples. * Clones:: Clones of common utilities. * Cut Program:: The `cut' utility. @@ -528,7 +532,6 @@ entitled "GNU Free Documentation License". * Extension API Description:: A full description of the API. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @@ -541,6 +544,7 @@ entitled "GNU Free Documentation License". * Two-way processors:: Registering a two-way processor. * Printing Messages:: Functions for printing messages. * Updating `ERRNO':: Functions for updating `ERRNO'. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -579,9 +583,9 @@ entitled "GNU Free Documentation License". processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to `gettimeofday()' and `sleep()'. +* Extension Sample API Tests:: Tests for the API. * gawkextlib:: The `gawkextlib' project. * Extension summary:: Extension summary. * Extension Exercises:: Exercises. @@ -693,7 +697,7 @@ 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 few lines of code. I was excited to try my hand at programming in +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 @@ -775,14 +779,14 @@ 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 (*note Options::), 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'. Thus, we usually 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' allows you to: + Using `awk' you can: * Manage small, personal databases @@ -803,9 +807,9 @@ and other `awk' implementations. * Perform simple network communications - * Profile and debug `awk' programs. + * Profile and debug `awk' programs - * Extend the language with functions written in C or C++. + * Extend the language with functions written in C or C++ This Info file teaches you about the `awk' language and how you can use it effectively. You should already be familiar with basic system @@ -818,9 +822,8 @@ different computing environments. This Info file, while describing the of `awk' called `gawk' (which stands for "GNU `awk'"). `gawk' runs on a broad range of Unix systems, ranging from Intel-architecture PC-based computers up through large-scale systems. `gawk' has also been ported -to Mac OS X, Microsoft Windows (all versions) and OS/2 PCs, and OpenVMS. -(Some other, obsolete systems to which `gawk' was once ported are no -longer supported and the code for those systems has been removed.) +to Mac OS X, Microsoft Windows (all versions) and OS/2 PCs, and +OpenVMS.(3) * Menu: @@ -840,11 +843,14 @@ longer supported and the code for those systems has been removed.) (1) The 2008 POSIX standard is accessible online at `http://www.opengroup.org/onlinepubs/9699919799/'. - (2) These commands are available on POSIX-compliant systems, as well -as on traditional Unix-based systems. If you are using some other + (2) These utilities are available on POSIX-compliant systems, as +well as on traditional Unix-based systems. If you are using some other operating system, you still need to be familiar with the ideas of I/O redirection and pipes. + (3) Some other, obsolete systems to which `gawk' was once ported are +no longer supported and the code for those systems has been removed. + File: gawk.info, Node: History, Next: Names, Up: Preface @@ -872,16 +878,16 @@ V Release 3.1 (1987). The version in System V Release 4 (1989) added some new features and cleaned up the behavior in some of the "dark corners" of the language. The specification for `awk' in the POSIX Command Language and Utilities standard further clarified the language. -Both the `gawk' designers and the original Bell Laboratories `awk' -designers provided feedback for the POSIX specification. +Both the `gawk' designers and the original `awk' designers at Bell +Laboratories provided feedback for the POSIX specification. - Paul Rubin wrote the GNU implementation, `gawk', in 1986. Jay -Fenlason completed it, with advice from Richard Stallman. John Woods -contributed parts of the code as well. In 1988 and 1989, David -Trueman, with help from me, thoroughly reworked `gawk' for compatibility -with the newer `awk'. Circa 1994, I became the primary maintainer. -Current development focuses on bug fixes, performance improvements, -standards compliance and, occasionally, new features. + Paul Rubin wrote `gawk' in 1986. Jay Fenlason completed it, with +advice from Richard Stallman. John Woods contributed parts of the code +as well. In 1988 and 1989, David Trueman, with help from me, +thoroughly reworked `gawk' for compatibility with the newer `awk'. +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 `awk', and with a little help from me, set about adding features to do @@ -894,8 +900,8 @@ the `gawk' distribution). His code finally became part of the main `awk'-level debugger. This version became available as `gawk' version 4.0, in 2011. - *Note Contributors::, for a complete list of those who made -important contributions to `gawk'. + *Note Contributors::, for a full list of those who made important +contributions to `gawk'. File: gawk.info, Node: Names, Next: This Manual, Prev: History, Up: Preface @@ -905,23 +911,19 @@ 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'" (`nawk'). +Info file is often referred to as "new `awk'". By analogy, the +original version of `awk' is referred to as "old `awk'." - For some time after new `awk' was introduced, there were systems -with multiple versions of `awk'. Some systems had an `awk' utility -that implemented the original version of the `awk' language and a -`nawk' utility for the new version. Others had an `oawk' version for -the "old `awk'" language and plain `awk' for the new one. Still others -only had one version, which is usually the new one. + Today, on most systems, when you run the `awk' utility, you get some +version of new `awk'.(1) If your system's standard `awk' is the old +one, you will see something like this if you try the test program: - Today, only Solaris systems still use an old `awk' for the default -`awk' utility. (A more modern `awk' lives in `/usr/xpg6/bin' on these -systems.) All other modern systems use some version of new `awk'.(1) + $ awk 1 /dev/null + error--> awk: syntax error near line 1 + error--> awk: bailing out near line 1 - It is likely that you already have some version of new `awk' on your -system, which is what you should use when running your programs. (Of -course, if you're reading this Info file, chances are good that you -have `gawk'!) +In this case, you should find a version of new `awk', or just install +`gawk'! Throughout this Info file, whenever we refer to a language feature that should be available in any complete implementation of POSIX `awk', @@ -930,7 +932,9 @@ specific to the GNU implementation, we use the term `gawk'. ---------- Footnotes ---------- - (1) Many of these systems use `gawk' for their `awk' implementation! + (1) Only Solaris systems still use an old `awk' for the default +`awk' utility. A more modern `awk' lives in `/usr/xpg6/bin' on these +systems. File: gawk.info, Node: This Manual, Next: Conventions, Prev: Names, Up: Preface @@ -950,8 +954,8 @@ programming language. in the POSIX standard. It does so in the context of the `gawk' implementation. While doing so, it also attempts to describe important differences between `gawk' and other `awk' implementations.(1) Finally, -any `gawk' features that are not in the POSIX standard for `awk' are -noted. +it notes any `gawk' features that are not in the POSIX standard for +`awk'. There are sidebars scattered throughout the Info file. They add a more complete explanation of points that are relevant, but not likely @@ -960,7 +964,7 @@ heading "sidebar." Most of the time, the examples use complete `awk' programs. Some of the more advanced sections show only the part of the `awk' program that -illustrates the concept currently being described. +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' @@ -996,7 +1000,7 @@ 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 built-in variables `awk' and `gawk' use. +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 @@ -1004,7 +1008,8 @@ 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. +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 @@ -1021,18 +1026,18 @@ problems. Part III focuses on features specific to `gawk'. It contains the following chapters: - *note Advanced Features::, describes a number of `gawk'-specific -advanced features. Of particular note are the abilities to 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 in `gawk' -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 `awk' debugger. + *note Debugger::, describes the `gawk' debugger. *note Arbitrary Precision Arithmetic::, describes advanced -arithmetic facilities provided by `gawk'. +arithmetic facilities. *note Dynamic Extensions::, describes how to add new variables and functions to `gawk' by writing extensions in C or C++. @@ -1119,8 +1124,8 @@ at all. Descriptions of such features (often called "dark corners") are noted in this Info file with "(d.c.)". They also appear in the index under the heading "dark corner." - As noted by the opening quote, though, any coverage of dark corners -is, by definition, incomplete. + But, as noted by the opening quote, any coverage of dark corners is +by definition incomplete. Extensions to the standard `awk' language that are supported by more than one `awk' implementation are marked "(c.e.)," and listed in the @@ -1160,7 +1165,7 @@ system for Intel, Power Architecture, Sun SPARC, IBM S/390, and other systems.(2) Many GNU/Linux distributions are available for download from the Internet. - The Info file itself has gone through a number of previous editions. + 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 @@ -1173,17 +1178,16 @@ published the first two editions under the title `The GNU Awk User's Guide'. This edition maintains the basic structure of the previous editions. -For FSF edition 4.0, the content has been thoroughly reviewed and -updated. All references to `gawk' versions prior to 4.0 have been -removed. Of significant note for this edition was *note Debugger::. +For FSF edition 4.0, the content was thoroughly reviewed and updated. +All references to `gawk' versions prior to 4.0 were removed. Of +significant note for that edition was *note Debugger::. For FSF edition 4.1, the content has been reorganized into parts, and the major new additions are *note Arbitrary Precision Arithmetic::, and *note Dynamic Extensions::. - This Info file will undoubtedly continue to evolve. An electronic -version comes with the `gawk' distribution from the FSF. If you find -an error in this Info file, please report it! *Note Bugs::, for + This Info file will undoubtedly continue to evolve. If you find an +error in this Info file, please report it! *Note Bugs::, for information on submitting problem reports electronically. ---------- Footnotes ---------- @@ -1288,12 +1292,14 @@ Michal Jaegermann, Ju"rgen Kahrs, Stepan Kasal, John Malmberg, Dave Pitts, Chet Ramey, Pat Rankin, Andrew Schorr, Corinna Vinschen, and Eli Zaretskii (in alphabetical order) make up the current `gawk' "crack portability team." Without their hard work and help, `gawk' would not -be nearly the fine program it is today. It has been and continues to -be a pleasure working with this team of fine people. +be nearly the robust, 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. *Note Contributors::, for the full list. + Thanks to Michael Brennan for the Foreword. + Thanks to Patrice Dumas for the new `makeinfo' program. Thanks to Karl Berry who continues to work to keep the Texinfo markup language sane. @@ -1457,21 +1463,23 @@ end-of-file character may be different. For example, on OS/2, it is As an example, the following program prints a friendly piece of advice (from Douglas Adams's `The Hitchhiker's Guide to the Galaxy'), to keep you from worrying about the complexities of computer -programming (`BEGIN' is a feature we haven't discussed yet): +programming: - $ awk "BEGIN { print \"Don't Panic!\" }" + $ awk 'BEGIN { print "Don\47t Panic!" }' -| Don't Panic! - This program does not read any input. The `\' before each of the -inner double quotes is necessary because of the shell's quoting -rules--in particular because it mixes both single quotes and double -quotes.(1) + `awk' executes statements associated with `BEGIN' before reading any +input. If there are no other statements in your program, as is the +case here, `awk' just stops, instead of trying to read input it doesn't +know how to process. The `\47' is a magic way (explained later) of +getting a single quote into the program, without having to engage in +ugly shell quoting tricks. - NOTE: As a side note, if you use Bash as your shell, you should - execute the command `set +H' before running this program - interactively, to disable the C shell-style command history, which - treats `!' as a special character. We recommend putting this - command into your personal startup file. + NOTE: If you use Bash as your shell, you should execute the + command `set +H' before running this program interactively, to + disable the C shell-style command history, which treats `!' as a + special character. We recommend putting this command into your + personal startup file. This next simple `awk' program emulates the `cat' utility; it copies whatever you type on the keyboard to its standard output (why this @@ -1488,21 +1496,15 @@ works is explained shortly). -| What, me worry? Ctrl-d - ---------- Footnotes ---------- - - (1) Although we generally recommend the use of single quotes around -the program text, double quotes are needed here in order to put the -single quote into the message. - File: gawk.info, Node: Long, Next: Executable Scripts, Prev: Read Terminal, Up: Running gawk 1.1.3 Running Long Programs --------------------------- -Sometimes your `awk' programs can be very long. In this case, it is -more convenient to put the program into a separate file. In order to -tell `awk' to use that file for its program, you type: +Sometimes `awk' programs are very long. In these cases, it is more +convenient to put the program into a separate file. In order to tell +`awk' to use that file for its program, you type: awk -f SOURCE-FILE INPUT-FILE1 INPUT-FILE2 ... @@ -1518,14 +1520,16 @@ into the file `advice'. Then this command: does the same thing as this one: - awk "BEGIN { print \"Don't Panic!\" }" + awk 'BEGIN { print "Don\47t Panic!" }' This was explained earlier (*note Read Terminal::). Note that you don't usually need single quotes around the file name that you specify with `-f', because most file names don't contain any of the shell's special characters. Notice that in `advice', the `awk' program did not have single quotes around it. The quotes are only needed for programs -that are provided on the `awk' command line. +that are provided on the `awk' command line. (Also, placing the +program in a file allows us to use a literal single quote in the program +text, instead of the magic `\47'.) If you want to clearly identify your `awk' program files as such, you can add the extension `.awk' to the file name. This doesn't affect @@ -1548,8 +1552,8 @@ like this: BEGIN { print "Don't Panic!" } After making this file executable (with the `chmod' utility), simply -type `advice' at the shell and the system arranges to run `awk'(2) as -if you had typed `awk -f advice': +type `advice' at the shell and the system arranges to run `awk' as if +you had typed `awk -f advice': $ chmod +x advice $ advice @@ -1563,7 +1567,24 @@ at the shell.) program that users can invoke without their having to know that the program is written in `awk'. - Portability Issues with `#!' + Understanding `#!' + + `awk' is an "interpreted" language. This means that the `awk' +utility reads your program and then processes your data according to +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. + + The line beginning with `#!' lists the full file name of an +interpreter to run and a single optional initial command-line argument +to pass to that interpreter. The operating system then runs the +interpreter with the given argument and the full argument list of the +executed program. The first argument in the list is the full file name +of the `awk' program. The rest of the argument list contains either +options to `awk', or data files, or both. (Note that on many systems +`awk' may be found in `/usr/bin' instead of in `/bin'.) Some systems limit the length of the interpreter name to 32 characters. Often, this can be dealt with by using a symbolic link. @@ -1585,15 +1606,6 @@ the name of your script (`advice'). (d.c.) Don't rely on the value of (1) The `#!' mechanism works on GNU/Linux systems, BSD-based systems and commercial Unix systems. - (2) The line beginning with `#!' lists the full file name of an -interpreter to run and a single optional initial command-line argument -to pass to that interpreter. The operating system then runs the -interpreter with the given argument and the full argument list of the -executed program. The first argument in the list is the full file name -of the `awk' program. The rest of the argument list contains either -options to `awk', or data files, or both. Note that on many systems -`awk' may be found in `/usr/bin' instead of in `/bin'. Caveat Emptor. - File: gawk.info, Node: Comments, Next: Quoting, Prev: Executable Scripts, Up: Running gawk @@ -1712,8 +1724,11 @@ the quoting rules. the characters `$', ``', `\', and `"', all of which must be preceded by a backslash within double-quoted text if they are to be passed on literally to the program. (The leading backslash is - stripped first.) Thus, the example seen in *note Read Terminal::, - is applicable: + stripped first.) Thus, the example seen in *note Read Terminal::: + + awk 'BEGIN { print "Don\47t Panic!" }' + + could instead be written this way: $ awk "BEGIN { print \"Don't Panic!\" }" -| Don't Panic! @@ -1731,10 +1746,10 @@ the quoting rules. awk -F"" 'PROGRAM' FILES # wrong! - In the second case, `awk' will attempt to use the text of the - program as the value of `FS', and the first file name as the text - of the program! This results in syntax errors at best, and - confusing behavior at worst. + In the second case, `awk' attempts to use the text of the program + as the value of `FS', and the first file name as the text of the + program! This results in syntax errors at best, and confusing + behavior at worst. Mixing single and double quotes is difficult. You have to resort to shell quoting tricks, like this: @@ -1779,6 +1794,9 @@ this: $ awk -v sq="'" 'BEGIN { print "Here is a single quote <" sq ">" }' -| Here is a single quote <'> + (Here, the two string constants and the value of `sq' are +concatenated into a single string which is printed by `print'.) + If you really need both single and double quotes in your `awk' program, it is probably best to move it into a separate file, where the shell won't be part of the picture, and you can say what you mean. @@ -1814,12 +1832,12 @@ The second data file, called `inventory-shipped', contains information about monthly shipments. In both files, each line is considered to be one "record". - In the data 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 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 that the person is a relative: + 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 +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 +that the person is a relative: Amelia 555-5553 amelia.zodiacusque@gmail.com F Anthony 555-3412 anthony.asserturo@hotmail.com A @@ -1838,7 +1856,8 @@ shipments during the year. Each record contains the month, the number of green crates shipped, the number of red boxes shipped, the number of orange bags shipped, and the number of blue packages shipped, respectively. There are 16 entries, covering the 12 months of last year -and the first four months of the current year. +and the first four months of the current year. An empty line separates +the data for the two years. Jan 13 25 15 115 Feb 15 32 24 226 @@ -1918,11 +1937,6 @@ 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 the length of the longest input line: - - awk '{ if (length($0) > max) max = length($0) } - END { print max }' data - * Print every line that is longer than 80 characters: awk 'length($0) > 80' data @@ -1930,15 +1944,23 @@ different ways to do the same things shown here: The sole rule has a relational expression as its pattern and it has no action--so it uses the default action, printing the record. + * Print the length of the longest input line: + + awk '{ if (length($0) > max) max = length($0) } + END { print max }' data + + The code associated with `END' executes after all input has been + read; it's the other side of the coin to `BEGIN'. + * Print the length of the longest line in `data': expand data | awk '{ if (x < length($0)) x = length($0) } - END { print "maximum line length is " x }' + END { print "maximum line length is " x }' - This example differs slightly from the first example in this list: - 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. + 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. * Print every line that has at least one field: @@ -1956,7 +1978,7 @@ different ways to do the same things shown here: * Print the total number of bytes used by FILES: ls -l FILES | awk '{ x += $5 } - END { print "total bytes: " x }' + END { print "total bytes: " x }' * Print the total number of kilobytes used by FILES: @@ -1985,13 +2007,13 @@ File: gawk.info, Node: Two Rules, Next: More Complex, Prev: Very Simple, Up: ============================= The `awk' utility reads the input files one line at a time. For each -line, `awk' tries the patterns of each of the rules. If several -patterns match, then several actions execute in the order in which they -appear in the `awk' program. If no patterns match, then no actions run. +line, `awk' tries the patterns of each rule. If several patterns +match, then several actions execute in the order in which they appear +in the `awk' program. If no patterns match, then no actions run. After processing all the rules that match the line (and perhaps there are none), `awk' reads the next line. (However, *note Next -Statement::, and also *note Nextfile Statement::). This continues +Statement::, and also *note Nextfile Statement::.) This continues until the program reaches the end of the file. For example, the following `awk' program contains two rules: @@ -2035,8 +2057,8 @@ summarize, select, and rearrange the output of another utility. It uses features that haven't been covered yet, so don't worry if you don't understand all the details: - LC_ALL=C ls -l | awk '$6 == "Nov" { sum += $5 } - END { print sum }' + ls -l | awk '$6 == "Nov" { sum += $5 } + END { print sum }' This command prints the total number of bytes in all the files in the current directory that were last modified in November (of any year). @@ -2055,11 +2077,11 @@ date the file was last modified. Its output looks like this: The first field contains read-write permissions, the second field contains the number of links to the file, and the third field -identifies the owner of the file. The fourth field identifies the group -of the file. The fifth field contains the size of the file in bytes. -The sixth, seventh, and eighth fields contain the month, day, and time, +identifies the file's owner. The fourth field identifies the file's +group. The fifth field contains the file's size in bytes. The sixth, +seventh, and eighth fields contain the month, day, and time, respectively, that the file was last modified. Finally, the ninth field -contains the file name.(1) +contains the file name. The `$6 == "Nov"' in our `awk' program is an expression that tests whether the sixth field of the output from `ls -l' matches the string @@ -2081,11 +2103,6 @@ displays your output. By manipulating fields and using `print' statements, you can produce some very useful and impressive-looking reports. - ---------- Footnotes ---------- - - (1) The `LC_ALL=C' is needed to produce this traditional-style -output from `ls'. - File: gawk.info, Node: Statements/Lines, Next: Other Features, Prev: More Complex, Up: Getting Started @@ -2216,7 +2233,7 @@ determining the type of a variable, and array sorting. As we develop our presentation of the `awk' language, we introduce most of the variables and many of the functions. They are described -systematically in *note Built-in Variables::, and *note Built-in::. +systematically in *note Built-in Variables::, and in *note Built-in::. File: gawk.info, Node: When, Next: Intro Summary, Prev: Other Features, Up: Getting Started @@ -2243,9 +2260,7 @@ edit-compile-test-debug cycle of software development. 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. Even -BWK `awk' has fewer predefined limits, and those that it has are much -larger than they used to be. +by tasks of such complexity, 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 @@ -2266,6 +2281,9 @@ File: gawk.info, Node: Intro Summary, Prev: When, Up: Getting Started * Programs in `awk' consist of PATTERN-ACTION pairs. + * An ACTION without a PATTERN always runs. The default ACTION for a + pattern without one is `{ print $0 }'. + * Use either `awk 'PROGRAM' FILES' or `awk -f PROGRAM-FILE FILES' to run `awk'. @@ -2381,7 +2399,7 @@ The following list describes options mandated by the POSIX standard: CAUTION: Using `-v' to set the values of the built-in variables may lead to surprising results. `awk' will reset the values of those variables as it needs to, possibly - ignoring any predefined value you may have given. + ignoring any initial value you may have given. `-W GAWK-OPT' Provide an implementation-specific option. This is the POSIX @@ -2432,9 +2450,9 @@ The following list describes options mandated by the POSIX standard: `-d'[FILE] `--dump-variables'[`='FILE] Print a sorted list of global variables, their types, and final - values to FILE. If no FILE is provided, print this list to the - file named `awkvars.out' in the current directory. No space is - allowed between the `-d' and FILE, if FILE is supplied. + values to FILE. If no FILE is provided, print this list to a file + named `awkvars.out' in the current directory. No space is allowed + between the `-d' and FILE, if FILE is supplied. Having a list of all global variables is a good way to look for typographical errors in your programs. You would also use this @@ -2497,7 +2515,7 @@ The following list describes options mandated by the POSIX standard: `-i' SOURCE-FILE `--include' SOURCE-FILE - Read `awk' source library from SOURCE-FILE. This option is + Read an `awk' source library from SOURCE-FILE. This option is completely equivalent to using the `@include' directive inside your program. This option is very similar to the `-f' option, but there are two important differences. First, when `-i' is used, @@ -2518,8 +2536,8 @@ The following list describes options mandated by the POSIX standard: not be specified in the extension name. The extension initialization routine should be named `dl_load()'. An alternative is to use the `@load' keyword inside the program to - load a shared library. This feature is described in detail in - *note Dynamic Extensions::. + load a shared library. This advanced feature is described in + detail in *note Dynamic Extensions::. `-L'[VALUE] `--lint'[`='VALUE] @@ -2555,6 +2573,8 @@ The following list describes options mandated by the POSIX standard: CAUTION: This option can severely break old programs. Use with care. + This option may disappear in a future version of `gawk'. + `-N' `--use-lc-numeric' Force the use of the locale's decimal point character when parsing @@ -2654,8 +2674,9 @@ 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. (As mentioned in -*note Definition Syntax::, function names must be unique.) +having to be included into each individual program. The `-i' option is +similar in this regard. (As mentioned in *note Definition Syntax::, +function names must be unique.) With standard `awk', library functions can still be used, even if the program is entered at the keyboard, by specifying `-f /dev/tty'. @@ -2712,14 +2733,21 @@ Any additional arguments on the command line are normally treated as input files to be processed in the order specified. However, an argument that has the form `VAR=VALUE', assigns the value VALUE to the variable VAR--it does not specify a file at all. (See *note Assignment -Options::.) +Options::.) In the following example, COUNT=1 is a variable assignment, +not a file name: + + awk -f program.awk file1 count=1 file2 - All these arguments are made available to your `awk' 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. + All the command-line arguments are made available to your `awk' +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. + + Changing `ARGC' and `ARGV' in your `awk' program lets you control +how `awk' processes the input files; this is described in more detail +in *note ARGC and ARGV::. The distinction between file name arguments and variable-assignment arguments is made when `awk' is about to open the next input file. At @@ -2824,8 +2852,8 @@ variable. If that variable does not exist, `gawk' uses a default path, The search path feature is particularly helpful for building libraries of useful `awk' functions. The library files can be placed in a standard directory in the default path and then specified on the -command line with a short file name. Otherwise, the full file name -would have to be typed for each file. +command line with a short file name. Otherwise, you would have to type +the full file name for each file. By using the `-i' option, or the `-e' and `-f' options, your command-line `awk' programs can use facilities in `awk' library files @@ -2833,21 +2861,20 @@ command-line `awk' programs can use facilities in `awk' library files in compatibility mode. This is true for both `--traditional' and `--posix'. *Note Options::. - If the source code is not found after the initial search, the path -is searched again after adding the default `.awk' suffix to the file -name. + If the source code file is not found after the initial search, the +path is searched again after adding the default `.awk' suffix to the +file name. - NOTE: To include the current directory in the path, either place - `.' explicitly in the path or write a null entry in the path. (A - null entry is indicated by starting or ending the path with a - colon or by placing two colons next to each other [`::'].) This - path search mechanism is similar to the shell's. (See `The - Bourne-Again SHell manual'. - (http://www.gnu.org/software/bash/manual/)) + `gawk''s path search mechanism is similar to the shell's. (See `The +Bourne-Again SHell manual' (http://www.gnu.org/software/bash/manual/).) +It treats a null entry in the path as indicating the current directory. +(A null entry is indicated by starting or ending the path with a colon +or by placing two colons next to each other [`::'].) - However, `gawk' always looks in the current directory _before_ - searching `AWKPATH', so there is no real reason to include the - current directory in the search path. + NOTE: `gawk' always looks in the current directory _before_ + searching `AWKPATH'. Thus, while you can include the current + directory in the search path, either explicitly or with a null + entry, there is no real reason to do so. If `AWKPATH' is not defined in the environment, `gawk' places its default search path into `ENVIRON["AWKPATH"]'. This makes it easy to @@ -2894,15 +2921,6 @@ 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. -`POSIXLY_CORRECT' - Causes `gawk' to switch to POSIX compatibility mode, disabling all - traditional and GNU extensions. *Note Options::. - -`GAWK_SOCK_RETRIES' - Controls the number of times `gawk' attempts to retry a two-way - TCP/IP (socket) connection before giving up. *Note TCP/IP - Networking::. - `GAWK_MSEC_SLEEP' Specifies the interval between connection retries, in milliseconds. On systems that do not support the `usleep()' system @@ -2912,6 +2930,15 @@ used by regular users. Specifies the time, in milliseconds, for `gawk' to wait for input before returning with an error. *Note Read Timeout::. +`GAWK_SOCK_RETRIES' + Controls the number of times `gawk' attempts to retry a two-way + TCP/IP (socket) connection before giving up. *Note TCP/IP + Networking::. + +`POSIXLY_CORRECT' + 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 the `gawk' developers for testing and tuning. They are subject to change. The variables are: @@ -2923,7 +2950,7 @@ change. The variables are: the value should be a number, and `gawk' uses that number as the size of the buffer to allocate. (When this variable is not set, `gawk' uses the smaller of the file's size and the "default" - blocksize, which is usually the filesystems I/O blocksize.) + blocksize, which is usually the filesystem's I/O blocksize.) `AWK_HASH' If this variable exists with a value of `gst', `gawk' switches to @@ -2937,11 +2964,11 @@ change. The variables are: where I/O is performed in records, not in blocks. `GAWK_MSG_SRC' - If this variable exists, `gawk' includes the source file name and - line number from which warning and/or fatal messages are - generated. Its purpose is to help isolate the source of a - message, since there can be multiple places which produce the same - warning or error message. + 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. `GAWK_NO_DFA' If this variable exists, `gawk' does not use the DFA regexp matcher @@ -2956,12 +2983,12 @@ change. The variables are: evaluation stack, when needed. `INT_CHAIN_MAX' - The average number of items `gawk' will maintain on a hash chain - for managing arrays indexed by integers. + The intended maximum number of items `gawk' will maintain on a + hash chain for managing arrays indexed by integers. `STR_CHAIN_MAX' - The average number of items `gawk' will maintain on a hash chain - for managing arrays indexed by strings. + The intended maximum number of items `gawk' will maintain on a + hash chain for managing arrays indexed by strings. `TIDYMEM' If this variable exists, `gawk' uses the `mtrace()' library calls @@ -3020,8 +3047,8 @@ and here is `test2': Running `gawk' with `test2' produces the following result: $ gawk -f test2 - -| This is file test1. - -| This is file 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 @@ -3043,9 +3070,9 @@ namely `test3': Running `gawk' with the `test3' script produces the following results: $ gawk -f test3 - -| This is file test1. - -| This is file test2. - -| This is file test3. + -| This is script test1. + -| This is script test2. + -| This is script test3. The file name can, of course, be a pathname. For example: @@ -3115,7 +3142,8 @@ is useful for embedding inside an `awk' source file that requires access to an extension. *note Dynamic Extensions::, describes how to write extensions (in C -or C++) that can be loaded with either `@load' or the `-l' option. +or C++) that can be loaded with either `@load' or the `-l' option. It +also describes the `ordchr' extension. File: gawk.info, Node: Obsolete, Next: Undocumented, Prev: Loading Shared Libraries, Up: Invoking Gawk @@ -3166,7 +3194,8 @@ File: gawk.info, Node: Invoking Summary, Prev: Undocumented, Up: Invoking Gaw affects how `awk' processes input. * You can use a single minus sign (`-') to refer to standard input - on the command line. + on the command line. `gawk' also lets you use the special file + name `/dev/stdin'. * `gawk' pays attention to a number of environment variables. `AWKPATH', `AWKLIBPATH', and `POSIXLY_CORRECT' are the most @@ -3200,7 +3229,7 @@ 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 -pattern `/foo/' matches any input record containing the three +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. @@ -3210,10 +3239,10 @@ you specify more complicated classes of strings. * Escape Sequences:: How to write nonprinting characters. * Regexp Operators:: Regular Expression Operators. * Bracket Expressions:: What can go between `[...]'. -* GNU Regexp Operators:: Operators specific to GNU software. -* Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* GNU Regexp Operators:: Operators specific to GNU software. +* Case-sensitivity:: How to do case-insensitive matching. * Regexp Summary:: Regular expressions summary. @@ -3304,9 +3333,9 @@ or newline. While there is nothing to stop you from entering most unprintable characters directly in a string constant or regexp constant, they may look ugly. - The following table lists all the escape sequences used in `awk' and -what they represent. Unless noted otherwise, all these escape sequences -apply to both string constants and regexp constants: + The following list presents all the escape sequences used in `awk' +and what they represent. Unless noted otherwise, all these escape +sequences apply to both string constants and regexp constants: `\\' A literal backslash, `\'. @@ -3355,17 +3384,19 @@ 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. Because the regexp is delimited by slashes, you - need to escape the slash that is part of the pattern, in order to + contains a slash (such as `/.*:\/home\/[[:alnum:]]+:.*/'; the + `[[:alnum:]]' notation is discussed shortly, 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. `\"' A literal double quote (necessary for string constants only). This sequence is used when you want to write a string constant - that contains a double quote. Because the string is delimited by - double quotes, you need to escape the quote that is part of the - string, in order to tell `awk' to keep processing the rest of the - string. + that contains a double quote (such as `"He said \"hi!\" to her."'). + Because the string is delimited by double quotes, you need to + escape any quote that is part of the string, in order to tell + `awk' to keep processing the rest of the string. In `gawk', a number of additional two-character sequences that begin with a backslash have special meaning in regexps. *Note GNU Regexp @@ -3378,11 +3409,11 @@ normally be a regexp operator. For example, `/a\+b/' matches the three characters `a+b'. For complete portability, do not use a backslash before any -character not shown in the previous list. +character not shown in the previous list and that is not an operator. To summarize: - * The escape sequences in the table above are always processed first, + * 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. @@ -3440,7 +3471,7 @@ and converted into corresponding real characters as the very first step in processing regexps. Here is a list of metacharacters. All characters that are not escape -sequences and that are not listed in the table stand for themselves: +sequences and that are not listed in the following stand for themselves: `\' This is used to suppress the special meaning of a character when @@ -3497,9 +3528,10 @@ sequences and that are not listed in the table stand for themselves: `|' This is the "alternation operator" and it is used to specify alternatives. The `|' has the lowest precedence of all the regular - expression operators. For example, `^P|[[:digit:]]' matches any - string that matches either `^P' or `[[:digit:]]'. This means it - matches any string that starts with `P' or contains a digit. + expression operators. For example, `^P|[aeiouy]' matches any + string that matches either `^P' or `[aeiouy]'. This means it + matches any string that starts with `P' or contains (anywhere + within it) a lowercase English vowel. The alternation applies to the largest possible regexps on either side. @@ -3519,22 +3551,20 @@ sequences and that are not listed in the table stand for themselves: matches of one `p' followed by any number of `h's. This also matches just `p' if no `h's are present. - The `*' repeats the _smallest_ possible preceding expression. - (Use parentheses if you want to repeat a larger expression.) It - finds as many repetitions as possible. For example, `awk - '/\(c[ad][ad]*r x\)/ { print }' sample' prints every record in - `sample' containing a string of the form `(car x)', `(cdr x)', - `(cadr x)', and so on. Notice the escaping of the parentheses by - preceding them with backslashes. + There are two subtle points to understand about how `*' works. + 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. + + Second, `*' finds as many repetitions as possible. If the text to + be matched is `phhhhhhhhhhhhhhooey', `ph*' matches all of the `h's. `+' This symbol is similar to `*', except that the preceding expression must be matched at least once. This means that `wh+y' would match `why' and `whhy', but not `wy', whereas `wh*y' would - match all three. The following is a simpler way of writing the - last `*' example: - - awk '/\(c[ad]+r x\)/ { print }' sample + match all three. `?' This symbol is similar to `*', except that the preceding @@ -3604,7 +3634,7 @@ list". regexp operator or function. -File: gawk.info, Node: Bracket Expressions, Next: GNU Regexp Operators, Prev: Regexp Operators, Up: Regexp +File: gawk.info, Node: Bracket Expressions, Next: Leftmost Longest, Prev: Regexp Operators, Up: Regexp 3.4 Using Bracket Expressions ============================= @@ -3625,10 +3655,12 @@ expression, put a `\' in front of it. For example: [d\]] -matches either `d' or `]'. +matches either `d' or `]'. Additionally, if you place `]' right after +the opening `[', the closing bracket is treated as one of the +characters to be matched. - This treatment of `\' in bracket expressions is compatible with -other `awk' implementations and is also mandated by POSIX. The regular + The treatment of `\' in bracket expressions is compatible with other +`awk' implementations and is also mandated by POSIX. The regular expressions in `awk' are a superset of the POSIX specification for Extended Regular Expressions (EREs). POSIX EREs are based on the regular expressions accepted by the traditional `egrep' utility. @@ -3707,9 +3739,119 @@ Equivalence classes classes. -File: gawk.info, Node: GNU Regexp Operators, Next: Case-sensitivity, Prev: Bracket Expressions, Up: Regexp +File: gawk.info, Node: Leftmost Longest, Next: Computed Regexps, Prev: Bracket Expressions, Up: Regexp + +3.5 How Much Text Matches? +========================== + +Consider the following: + + echo aaaabcd | awk '{ sub(/a+/, "<A>"); print }' + + This example uses the `sub()' function to make a change to the input +record. (`sub()' replaces the first instance of any text matched by +the first argument with the string provided as the second argument; +*note String Functions::). Here, the regexp `/a+/' indicates "one or +more `a' characters," and the replacement text is `<A>'. + + The input contains four `a' characters. `awk' (and POSIX) regular +expressions always match the leftmost, _longest_ sequence of input +characters that can match. Thus, all four `a' characters are replaced +with `<A>' in this example: + + $ echo aaaabcd | awk '{ sub(/a+/, "<A>"); print }' + -| <A>bcd + + For simple match/no-match tests, this is not so important. But when +doing text matching and substitutions with the `match()', `sub()', +`gsub()', and `gensub()' functions, it is very important. *Note String +Functions::, for more information on these functions. Understanding +this principle is also important for regexp-based record and field +splitting (*note Records::, and also *note Field Separators::). + + +File: gawk.info, Node: Computed Regexps, Next: GNU Regexp Operators, Prev: Leftmost Longest, Up: Regexp + +3.6 Using Dynamic Regexps +========================= + +The righthand side of a `~' or `!~' operator need not be a regexp +constant (i.e., a string of characters between slashes). It may be any +expression. The expression is evaluated and converted to a string if +necessary; the contents of the string are then used as the regexp. A +regexp computed in this way is called a "dynamic regexp" or a "computed +regexp": + + BEGIN { digits_regexp = "[[:digit:]]+" } + $0 ~ digits_regexp { print } + +This sets `digits_regexp' to a regexp that describes one or more digits, +and tests whether the input record matches this regexp. + + NOTE: When using the `~' and `!~' operators, there is a difference + between a regexp constant enclosed in slashes and a string + constant enclosed in double quotes. If you are going to use a + string constant, you have to understand that the string is, in + essence, scanned _twice_: the first time when `awk' reads your + program, and the second time when it goes to match the string on + the lefthand side of the operator with the pattern on the right. + This is true of any string-valued expression (such as + `digits_regexp', shown previously), not just string constants. + + What difference does it make if the string is scanned twice? The +answer has to do with escape sequences, and particularly with +backslashes. To get a backslash into a regular expression inside a +string, you have to type two backslashes. + + For example, `/\*/' is a regexp constant for a literal `*'. Only +one backslash is needed. To do the same thing with a string, you have +to type `"\\*"'. The first backslash escapes the second one so that +the string actually contains the two characters `\' and `*'. + + Given that you can use both regexp and string constants to describe +regular expressions, which should you use? The answer is "regexp +constants," for several reasons: + + * String constants are more complicated to write and more difficult + to read. Using regexp constants makes your programs less + error-prone. Not understanding the difference between the two + kinds of constants is a common source of errors. + + * It is more efficient to use regexp constants. `awk' can note that + you have supplied a regexp and store it internally in a form that + makes pattern matching more efficient. When using a string + constant, `awk' must first convert the string into this internal + form and then perform the pattern matching. + + * Using regexp constants is better form; it shows clearly that you + intend a regexp match. + + Using `\n' in Bracket Expressions of Dynamic Regexps + + Some older versions of `awk' do not allow the newline character to +be used inside a bracket expression for a dynamic regexp: + + $ awk '$0 ~ "[ \t\n]"' + error--> awk: newline in character class [ + error--> ]... + error--> source line number 1 + error--> context is + error--> $0 ~ "[ >>> \t\n]" <<< + + But a newline in a regexp constant works with no problem: + + $ awk '$0 ~ /[ \t\n]/' + here is a sample line + -| here is a sample line + Ctrl-d + + `gawk' does not have this problem, and it isn't likely to occur +often in practice, but it's worth noting for future reference. + + +File: gawk.info, Node: GNU Regexp Operators, Next: Case-sensitivity, Prev: Computed Regexps, Up: Regexp -3.5 `gawk'-Specific Regexp Operators +3.7 `gawk'-Specific Regexp Operators ==================================== GNU software that deals with regular expressions provides a number of @@ -3793,7 +3935,7 @@ No options 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' does support them. Characters described by octal and + BWK `awk' supports them. Characters described by octal and hexadecimal escape sequences are treated literally, even if they represent regexp metacharacters. @@ -3803,9 +3945,9 @@ No options default. -File: gawk.info, Node: Case-sensitivity, Next: Leftmost Longest, Prev: GNU Regexp Operators, Up: Regexp +File: gawk.info, Node: Case-sensitivity, Next: Regexp Summary, Prev: GNU Regexp Operators, Up: Regexp -3.6 Case Sensitivity in Matching +3.8 Case Sensitivity in Matching ================================ Case is normally significant in regular expressions, both when matching @@ -3878,116 +4020,7 @@ obscure and we don't recommend it. means that `gawk' does the right thing. -File: gawk.info, Node: Leftmost Longest, Next: Computed Regexps, Prev: Case-sensitivity, Up: Regexp - -3.7 How Much Text Matches? -========================== - -Consider the following: - - echo aaaabcd | awk '{ sub(/a+/, "<A>"); print }' - - This example uses the `sub()' function (which we haven't discussed -yet; *note String Functions::) to make a change to the input record. -Here, the regexp `/a+/' indicates "one or more `a' characters," and the -replacement text is `<A>'. - - The input contains four `a' characters. `awk' (and POSIX) regular -expressions always match the leftmost, _longest_ sequence of input -characters that can match. Thus, all four `a' characters are replaced -with `<A>' in this example: - - $ echo aaaabcd | awk '{ sub(/a+/, "<A>"); print }' - -| <A>bcd - - For simple match/no-match tests, this is not so important. But when -doing text matching and substitutions with the `match()', `sub()', -`gsub()', and `gensub()' functions, it is very important. *Note String -Functions::, for more information on these functions. Understanding -this principle is also important for regexp-based record and field -splitting (*note Records::, and also *note Field Separators::). - - -File: gawk.info, Node: Computed Regexps, Next: Regexp Summary, Prev: Leftmost Longest, Up: Regexp - -3.8 Using Dynamic Regexps -========================= - -The righthand side of a `~' or `!~' operator need not be a regexp -constant (i.e., a string of characters between slashes). It may be any -expression. The expression is evaluated and converted to a string if -necessary; the contents of the string are then used as the regexp. A -regexp computed in this way is called a "dynamic regexp" or a "computed -regexp": - - BEGIN { digits_regexp = "[[:digit:]]+" } - $0 ~ digits_regexp { print } - -This sets `digits_regexp' to a regexp that describes one or more digits, -and tests whether the input record matches this regexp. - - NOTE: When using the `~' and `!~' operators, there is a difference - between a regexp constant enclosed in slashes and a string - constant enclosed in double quotes. If you are going to use a - string constant, you have to understand that the string is, in - essence, scanned _twice_: the first time when `awk' reads your - program, and the second time when it goes to match the string on - the lefthand side of the operator with the pattern on the right. - This is true of any string-valued expression (such as - `digits_regexp', shown previously), not just string constants. - - What difference does it make if the string is scanned twice? The -answer has to do with escape sequences, and particularly with -backslashes. To get a backslash into a regular expression inside a -string, you have to type two backslashes. - - For example, `/\*/' is a regexp constant for a literal `*'. Only -one backslash is needed. To do the same thing with a string, you have -to type `"\\*"'. The first backslash escapes the second one so that -the string actually contains the two characters `\' and `*'. - - Given that you can use both regexp and string constants to describe -regular expressions, which should you use? The answer is "regexp -constants," for several reasons: - - * String constants are more complicated to write and more difficult - to read. Using regexp constants makes your programs less - error-prone. Not understanding the difference between the two - kinds of constants is a common source of errors. - - * It is more efficient to use regexp constants. `awk' can note that - you have supplied a regexp and store it internally in a form that - makes pattern matching more efficient. When using a string - constant, `awk' must first convert the string into this internal - form and then perform the pattern matching. - - * Using regexp constants is better form; it shows clearly that you - intend a regexp match. - - Using `\n' in Bracket Expressions of Dynamic Regexps - - Some versions of `awk' do not allow the newline character to be used -inside a bracket expression for a dynamic regexp: - - $ awk '$0 ~ "[ \t\n]"' - error--> awk: newline in character class [ - error--> ]... - error--> source line number 1 - error--> context is - error--> >>> <<< - - But a newline in a regexp constant works with no problem: - - $ awk '$0 ~ /[ \t\n]/' - here is a sample line - -| here is a sample line - Ctrl-d - - `gawk' does not have this problem, and it isn't likely to occur -often in practice, but it's worth noting for future reference. - - -File: gawk.info, Node: Regexp Summary, Prev: Computed Regexps, Up: Regexp +File: gawk.info, Node: Regexp Summary, Prev: Case-sensitivity, Up: Regexp 3.9 Summary =========== @@ -4011,18 +4044,18 @@ File: gawk.info, Node: Regexp Summary, Prev: Computed Regexps, Up: Regexp Within bracket expressions, POSIX character classes let you specify certain groups of characters in a locale-independent fashion. - * `gawk''s `IGNORECASE' variable lets you control the case - sensitivity of regexp matching. In other `awk' versions, use - `tolower()' or `toupper()'. - * Regular expressions match the leftmost longest text in the string being matched. This matters for cases where you need to know the 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 + * Matching expressions may use dynamic regexps, that is, string values treated as regular expressions. + * `gawk''s `IGNORECASE' variable lets you control the case + sensitivity of regexp matching. In other `awk' versions, use + `tolower()' or `toupper()'. + File: gawk.info, Node: Reading Files, Next: Printing, Prev: Regexp, Up: Top @@ -4035,8 +4068,8 @@ standard input (by default, this is the keyboard, but often it is a pipe from another command) or from files whose names you specify on the `awk' command line. If you specify input files, `awk' reads them in order, processing all the data from one before going on to the next. -The name of the current input file can be found in the built-in variable -`FILENAME' (*note Built-in Variables::). +The name of the current input file can be found in the predefined +variable `FILENAME' (*note Built-in Variables::). The input is read in units called "records", and is processed by the rules of your program one record at a time. By default, each record is @@ -4073,13 +4106,13 @@ File: gawk.info, Node: Records, Next: Fields, Up: Reading Files 4.1 How Input Is Split into Records =================================== -The `awk' utility divides the input for your `awk' program into records -and fields. `awk' keeps track of the number of records that have been -read so far from the current input file. This value is stored in a -built-in variable called `FNR'. It is reset to zero when a new file is -started. Another built-in 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. +`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. +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. * Menu: @@ -4096,7 +4129,7 @@ Records are separated by a character called the "record separator". By default, the record separator is the newline character. This is why records are, by default, single lines. A different character can be used for the record separator by assigning the character to the -built-in variable `RS'. +predefined variable `RS'. Like any other variable, the value of `RS' can be changed in the `awk' program with the assignment operator, `=' (*note Assignment @@ -4184,9 +4217,10 @@ character such as `/' is more likely to produce correct behavior in the majority of cases, but there are no guarantees. The moral is: Know Your Data. - There is one unusual case, that occurs when `gawk' is being fully -POSIX-compliant (*note Options::). Then, the following (extreme) -pipeline prints a surprising `1': + When using regular characters as the record separator, there is one +unusual case that occurs when `gawk' is being fully POSIX-compliant +(*note Options::). Then, the following (extreme) pipeline prints a +surprising `1': $ echo | gawk --posix 'BEGIN { RS = "a" } ; { print NF }' -| 1 @@ -4251,9 +4285,9 @@ trailing whitespace: -| ] The square brackets delineate the contents of `RT', letting you see the -leading and trailing whitespace. The final value of `RT' `RT' is a -newline. *Note Simple Sed::, for a more useful example of `RS' as a -regexp and `RT'. +leading and trailing whitespace. The final value of `RT' is a newline. +*Note Simple Sed::, for a more useful example of `RS' as a regexp and +`RT'. If you set `RS' to a regular expression that allows optional trailing text, such as `RS = "abc(XYZ)?"' it is possible, due to @@ -4268,13 +4302,13 @@ that this will never happen. the beginning and end of a _line_. As a result, something like `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 in it. It is thus best - to avoid anchor characters in the value of `RS'. + that happens to contain newline characters. It is thus best to + avoid anchor characters 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 Options::). In compatibility mode, only the first character of the -value of `RS' is used to determine the end of the record. +value of `RS' determines the end of the record. `RS = "\0"' Is Not Portable @@ -4303,11 +4337,12 @@ terminator. In effect, this means that `RS = "\0"' is the same as `RS It happens that recent versions of `mawk' can use the NUL character as a record separator. However, this is a special case: `mawk' does not -allow embedded NUL characters in strings. +allow embedded NUL characters in strings. (This may change in a future +version of `mawk'.) - *Note Readfile Function::, for an interesting, portable way to read -whole files. If you are using `gawk', see *note Extension Sample -Readfile::, for another option. + *Note Readfile Function::, for an interesting way to read whole +files. If you are using `gawk', see *note Extension Sample Readfile::, +for another option. ---------- Footnotes ---------- @@ -4346,7 +4381,7 @@ Here the first field, or `$1', is `This', the second field, or `$2', is Because there is no space between the `e' and the `.', the period is considered part of the seventh field. - `NF' is a built-in variable whose value is the number of fields in + `NF' is a predefined variable whose value is the number of fields in the current record. `awk' automatically updates the value of `NF' each time it reads a record. No matter how many fields there are, the last field in a record can be represented by `$NF'. So, `$NF' is the same @@ -4364,13 +4399,11 @@ examples: -| Julie 555-6699 julie.perscrutabor@skeeve.com F This example prints each record in the file `mail-list' whose first -field contains the string `li'. The operator `~' is called a "matching -operator" (*note Regexp Usage::); it tests whether a string (here, the -field `$1') matches a given regular expression. +field contains the string `li'. By contrast, the following example looks for `li' in _the entire -record_ and prints the first field and the last field for each matching -input record: +record_ and prints the first and last fields for each matching input +record: $ awk '/li/ { print $1, $NF }' mail-list -| Amelia F @@ -4425,9 +4458,9 @@ program. Other `awk' implementations may behave differently.) As mentioned in *note Fields::, `awk' stores the current record's number of fields in the built-in variable `NF' (also *note Built-in -Variables::). The expression `$NF' is not a special feature--it is the -direct consequence of evaluating `NF' and using its value as a field -number. +Variables::). Thus, the expression `$NF' is not a special feature--it +is the direct consequence of evaluating `NF' and using its value as a +field number. ---------- Footnotes ---------- @@ -4546,12 +4579,12 @@ value six. value of `NF' and recomputes `$0'. (d.c.) Here is an example: $ echo a b c d e f | awk '{ print "NF =", NF; - > NF = 3; print $0 }' + > NF = 3; print $0 }' -| NF = 6 -| a b c CAUTION: Some versions of `awk' don't rebuild `$0' when `NF' is - decremented. Caveat emptor. + decremented. Finally, there are times when it is convenient to force `awk' to rebuild the entire record, using the current value of the fields and @@ -4576,8 +4609,8 @@ as it was read from the input. This includes any leading or trailing whitespace, and the exact whitespace (or other characters) that separate the fields. - It is a not-uncommon error to try to change the field separators in -a record simply by setting `FS' and `OFS', and then expecting a plain + It is a common error to try to change the field separators in a +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 @@ -4614,7 +4647,7 @@ the following line: is split into three fields: `m', `*g', and `*gai*pan'. Note the leading spaces in the values of the second and third fields. - The field separator is represented by the built-in variable `FS'. + The field separator is represented by the predefined variable `FS'. Shell programmers take note: `awk' does _not_ use the name `IFS' that is used by the POSIX-compliant shells (such as the Unix Bourne shell, `sh', or Bash). @@ -4727,9 +4760,9 @@ play whenever `$0' is recomputed. For instance, study this pipeline: The first `print' statement prints the record as it was read, with leading whitespace intact. The assignment to `$2' rebuilds `$0' by concatenating `$1' through `$NF' together, separated by the value of -`OFS'. Because the leading whitespace was ignored when finding `$1', -it is not part of the new `$0'. Finally, the last `print' statement -prints the new `$0'. +`OFS' (which is a space by default). Because the leading whitespace +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 @@ -4744,7 +4777,7 @@ beginning of the record. `gawk' also works this way. For example: $ echo 'xxAA xxBxx C' | > gawk -F '(^x+)|( +)' '{ for (i = 1; i <= NF; i++) - > printf "-->%s<--\n", $i }' + > printf "-->%s<--\n", $i }' -| --><-- -| -->AA<-- -| -->xxBxx<-- @@ -4789,13 +4822,10 @@ For example: sets `FS' to the `,' character. Notice that the option uses an uppercase `F' instead of a lowercase `f'. The latter option (`-f') -specifies a file containing an `awk' program. Case is significant in -command-line options: the `-F' and `-f' options have nothing to do with -each other. You can use both options at the same time to set the `FS' -variable _and_ get an `awk' program from a file. +specifies a file containing an `awk' program. The value used for the argument to `-F' is processed in exactly the -same way as assignments to the built-in variable `FS'. Any special +same way as assignments to the predefined variable `FS'. Any special characters in the field separator must be escaped appropriately. For example, to use a `\' as the field separator on the command line, you would have to type: @@ -4890,7 +4920,7 @@ occurrences of any two characters." If instead you want fields to be separated by a literal period followed by any single character, use `FS = "\\.."'. - The following table summarizes how fields are split, based on the + The following list summarizes how fields are split, based on the value of `FS' (`==' means "is equal to"): `FS == " "' @@ -4910,7 +4940,7 @@ value of `FS' (`==' means "is equal to"): `FS == ""' Each individual character in the record becomes a separate field. - (This is a `gawk' extension; it is not specified by the POSIX + (This is a common extension; it is not specified by the POSIX standard.) Changing `FS' Does Not Affect the Fields @@ -5281,7 +5311,7 @@ A simple program to process this file is as follows: ... *Note Labels Program::, for a more realistic program that deals with -address lists. The following table summarizes how records are split, +address lists. The following list summarizes how records are split, based on the value of `RS'. (`==' means "is equal to.") `RS == "\n"' @@ -5305,9 +5335,10 @@ based on the value of `RS'. (`==' means "is equal to.") records. (This is a `gawk' extension; it is not specified by the POSIX standard.) - In all cases, `gawk' sets `RT' to the input text that matched the -value specified by `RS'. But if the input file ended without any text -that matches `RS', then `gawk' sets `RT' to the null string. + If not in compatibility mode (*note Options::), `gawk' sets `RT' to +the input text that matched the value specified by `RS'. But if the +input file ended without any text that matches `RS', then `gawk' sets +`RT' to the null string. ---------- Footnotes ---------- @@ -5334,8 +5365,8 @@ yet. Therefore, come back and study the `getline' command _after_ you have reviewed the rest of this Info file and have a good knowledge of how `awk' works. - The `getline' command returns one if it finds a record and zero if -it encounters the end of the file. If there is some error in getting a + The `getline' command returns 1 if it finds a record and 0 if it +encounters the end of the file. If there is some error in getting a record, such as a file that cannot be opened, then `getline' returns -1. In this case, `gawk' sets the variable `ERRNO' to a string describing the error that occurred. @@ -5374,35 +5405,45 @@ input record and split it up into fields. This is useful if you've finished processing the current record, but want to do some special processing on the next record _right now_. For example: + # Remove text between /* and */, inclusive { - if ((t = index($0, "/*")) != 0) { - # value of `tmp' will be "" if t is 1 - tmp = substr($0, 1, t - 1) - u = index(substr($0, t + 2), "*/") - offset = t + 2 - while (u == 0) { - if (getline <= 0) { - m = "unexpected EOF or error" - m = (m ": " ERRNO) - print m > "/dev/stderr" + if ((i = index($0, "/*")) != 0) { + out = substr($0, 1, i - 1) # leading part of the string + rest = substr($0, i + 2) # ... */ ... + j = index(rest, "*/") # is */ in trailing part? + if (j > 0) { + rest = substr(rest, j + 2) # remove comment + } else { + while (j == 0) { + # get more text + if (getline <= 0) { + print("unexpected EOF or error:", ERRNO) > "/dev/stderr" exit - } - u = index($0, "*/") - offset = 0 - } - # substr() expression will be "" if */ - # occurred at end of line - $0 = tmp substr($0, offset + u + 2) - } - print $0 + } + # build up the line using string concatenation + rest = rest $0 + j = index(rest, "*/") # is */ in trailing part? + if (j != 0) { + rest = substr(rest, j + 2) + break + } + } + } + # build up the output line using string concatenation + $0 = out rest + } + print $0 } This `awk' program deletes C-style comments (`/* ... */') from the -input. By replacing the `print $0' with other statements, you could -perform more complicated processing on the decommented input, such as -searching for matches of a regular expression. (This program has a -subtle problem--it does not work if one comment ends and another begins -on the same line.) +input. It uses a number of features we haven't covered yet, including +string concatenation (*note Concatenation::) and the `index()' and +`substr()' built-in functions (*note String Functions::). By replacing +the `print $0' with other statements, you could perform more +complicated processing on the decommented input, such as searching for +matches of a regular expression. (This program has a subtle +problem--it does not work if one comment ends and another begins on the +same line.) This form of the `getline' command sets `NF', `NR', `FNR', `RT', and the value of `$0'. @@ -5498,7 +5539,7 @@ 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 this version of `getline', none of the built-in variables are + In this version of `getline', none of the predefined variables are changed and the record is not split into fields. The only variable changed is VAR.(1) For example, the following program copies all the input files to the output, except for records that say @@ -5579,9 +5620,9 @@ the program might produce: bill ttyp1 Jul 13 14:23 (murphy:0) bletch -Notice that this program ran the command `who' and printed the previous -result. (If you try this program yourself, you will of course get -different results, depending upon who is logged in on your system.) +Notice that this program ran the command `who' and printed the result. +(If you try this program yourself, you will of course get different +results, depending upon who is logged in on your system.) This variation of `getline' splits the record into fields, sets the value of `NF', and recomputes the value of `$0'. The values of `NR' @@ -5597,10 +5638,10 @@ all `awk' implementations. NOTE: Unfortunately, `gawk' has not been consistent in its treatment of a construct like `"echo " "date" | getline'. Most versions, including the current version, treat it at as `("echo " - "date") | getline'. (This how BWK `awk' behaves.) Some versions - changed and treated it as `"echo " ("date" | getline)'. (This is - how `mawk' behaves.) In short, _always_ use explicit parentheses, - and then you won't have to worry. + "date") | getline'. (This is also how BWK `awk' behaves.) Some + versions changed and treated it as `"echo " ("date" | getline)'. + (This is how `mawk' behaves.) In short, _always_ use explicit + parentheses, and then you won't have to worry. File: gawk.info, Node: Getline/Variable/Pipe, Next: Getline/Coprocess, Prev: Getline/Pipe, Up: Getline @@ -5619,8 +5660,8 @@ following program reads the current date and time into the variable print "Report printed on " current_time } - In this version of `getline', none of the built-in variables are -changed and the record is not split into fields. + In this version of `getline', none of the predefined variables are +changed and the record is not split into fields. However, `RT' is set. According to POSIX, `EXPRESSION | getline VAR' is ambiguous if EXPRESSION contains unparenthesized operators other than `$'; for @@ -5669,7 +5710,7 @@ When you use `COMMAND |& getline VAR', the output from the coprocess COMMAND is sent through a two-way pipe to `getline' and into the variable VAR. - In this version of `getline', none of the built-in variables are + In this version of `getline', none of the predefined variables are changed and the record is not split into fields. The only variable changed is VAR. However, `RT' is set. @@ -5702,7 +5743,7 @@ in mind: `getline' command causes `awk' to set the value of `FILENAME'. Normally, `FILENAME' does not have a value inside `BEGIN' rules, because you have not yet started to process the command-line data - files. (d.c.) (*Note BEGIN/END::, also *note Auto-set::.) + files. (d.c.) (See *note BEGIN/END::; also *note Auto-set::.) * Using `FILENAME' with `getline' (`getline < FILENAME') is likely to be a source for confusion. `awk' opens a separate input stream @@ -5735,7 +5776,7 @@ in mind: `gawk' treats `getline' like a function call, and evaluates the expression `a[++c]' before attempting to read from `f'. However, some versions of `awk' only evaluate the expression once they know - that there is a string value to be assigned. Caveat Emptor. + that there is a string value to be assigned. File: gawk.info, Node: Getline Summary, Prev: Getline Notes, Up: Getline @@ -5744,23 +5785,22 @@ File: gawk.info, Node: Getline Summary, Prev: Getline Notes, Up: Getline ------------------------------------ *note table-getline-variants:: summarizes the eight variants of -`getline', listing which built-in variables are set by each one, and +`getline', listing which predefined variables are set by each one, and whether the variant is standard or a `gawk' extension. Note: for each -variant, `gawk' sets the `RT' built-in variable. +variant, `gawk' sets the `RT' predefined variable. -Variant Effect Standard / - Extension +Variant Effect `awk' / `gawk' ------------------------------------------------------------------------- -`getline' Sets `$0', `NF', `FNR', Standard +`getline' Sets `$0', `NF', `FNR', `awk' `NR', and `RT' -`getline' VAR Sets VAR, `FNR', `NR', and Standard +`getline' VAR Sets VAR, `FNR', `NR', and `awk' `RT' -`getline <' FILE Sets `$0', `NF', and `RT' Standard -`getline VAR < FILE' Sets VAR and `RT' Standard -COMMAND `| getline' Sets `$0', `NF', and `RT' Standard -COMMAND `| getline' VAR Sets VAR and `RT' Standard -COMMAND `|& getline' Sets `$0', `NF', and `RT' Extension -COMMAND `|& getline' Sets VAR and `RT' Extension +`getline <' FILE Sets `$0', `NF', and `RT' `awk' +`getline VAR < FILE' Sets VAR and `RT' `awk' +COMMAND `| getline' Sets `$0', `NF', and `RT' `awk' +COMMAND `| getline' VAR Sets VAR and `RT' `awk' +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 @@ -5776,7 +5816,7 @@ 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 -setting a special element in the `PROCINFO' (*note Auto-set::) array: +setting a special element in the `PROCINFO' array (*note Auto-set::): PROCINFO["input_name", "READ_TIMEOUT"] = TIMEOUT IN MILLISECONDS @@ -5800,9 +5840,9 @@ for more than five seconds: print $0 `gawk' terminates the read operation if input does not arrive after -waiting for the timeout period, returns failure and sets the `ERRNO' -variable to an appropriate string value. A negative or zero value for -the timeout is the same as specifying no timeout at all. +waiting for the timeout period, returns failure and sets `ERRNO' to an +appropriate string value. A negative or zero value for the timeout is +the same as specifying no timeout at all. A timeout can also be set for reading from the keyboard in the implicit loop that reads input records and matches them against @@ -5900,6 +5940,10 @@ File: gawk.info, Node: Input Summary, Next: Input Exercises, Prev: Command-li A regexp Text that matches the `gawk' regexp + * `FNR' indicates how many records have been read from the current + input file; `NR' indicates how many records have been read in + total. + * `gawk' sets `RT' to the text matched by `RS'. * After splitting the input into records, `awk' further splits the @@ -5917,32 +5961,31 @@ File: gawk.info, Node: Input Summary, Next: Input Exercises, Prev: Command-li * Field splitting is more complicated than record splitting. - Field separator value Fields are split ... `awk' / - `gawk' + Field separator value Fields are split ... `awk' / + `gawk' ---------------------------------------------------------------------- - `FS == " "' On runs of whitespace `awk' - `FS == ANY SINGLE On that character `awk' - CHARACTER' - `FS == REGEXP' On text matching the `awk' - regexp - `FS == ""' Each individual character `gawk' - is a separate field - `FIELDWIDTHS == LIST OF Based on character `gawk' - COLUMNS' position - `FPAT == REGEXP' On text around text `gawk' - matching the regexp - - Using `FS = "\n"' causes the entire record to be a single field + `FS == " "' On runs of whitespace `awk' + `FS == ANY SINGLE On that character `awk' + CHARACTER' + `FS == REGEXP' On text matching the regexp `awk' + `FS == ""' Each individual character is `gawk' + a separate field + `FIELDWIDTHS == LIST OF Based on character position `gawk' + COLUMNS' + `FPAT == REGEXP' On the text surrounding text `gawk' + matching the regexp + + * Using `FS = "\n"' causes the entire record to be a single field (assuming that newlines separate records). * `FS' may be set from the command line using the `-F' option. This can also be done using command-line variable assignment. - * `PROCINFO["FS"]' can be used to see how fields are being split. + * Use `PROCINFO["FS"]' to see how fields are being split. * Use `getline' in its various forms to read additional records, from the default input stream, from a file, or from a pipe or - co-process. + coprocess. * Use `PROCINFO[FILE, "READ_TIMEOUT"]' to cause reads to timeout for FILE. @@ -5966,8 +6009,8 @@ File: gawk.info, Node: Input Exercises, Prev: Input Summary, Up: Reading File 2. *note Plain Getline::, presented a program to remove C-style comments (`/* ... */') from the input. That program does not work if one comment ends on one line and another one starts later on - the same line. Write a program that does handle multiple comments - on the line. + the same line. That can be fixed by making one simple change. + What is it? @@ -6000,12 +6043,13 @@ function. * Printf:: The `printf' statement. * Redirection:: How to redirect output to multiple files and pipes. +* Special FD:: Special files for I/O. * Special Files:: File name interpretation in `gawk'. `gawk' allows access to inherited file descriptors. * Close Files And Pipes:: Closing Input and Output Files and Pipes. * Output Summary:: Output summary. -* Output exercises:: Exercises. +* Output Exercises:: Exercises. File: gawk.info, Node: Print, Next: Print Examples, Up: Printing @@ -6013,10 +6057,10 @@ File: gawk.info, Node: Print, Next: Print Examples, Up: Printing 5.1 The `print' Statement ========================= -The `print' statement is used for producing output with simple, -standardized formatting. You specify only the strings or numbers to -print, in a list separated by commas. They are output, separated by -single spaces, followed by a newline. The statement looks like this: +Use the `print' statement to produce output with simple, standardized +formatting. You specify only the strings or numbers to print, in a +list separated by commas. They are output, separated by single spaces, +followed by a newline. The statement looks like this: print ITEM1, ITEM2, ... @@ -6031,14 +6075,14 @@ Numeric values are converted to strings and then printed. The simple statement `print' with no items is equivalent to `print $0': it prints the entire current record. To print a blank line, use -`print ""', where `""' is the empty string. To print a fixed piece of -text, use a string constant, such as `"Don't Panic"', as one item. If -you forget to use the double-quote characters, your text is taken as an -`awk' expression, and you will probably get an error. Keep in mind -that a space is printed between any two items. +`print ""'. To print a fixed piece of text, use a string constant, +such as `"Don't Panic"', as one item. If you forget to use the +double-quote characters, your text is taken as an `awk' expression, and +you will probably get an error. Keep in mind that a space is printed +between any two items. Note that the `print' statement is a statement and not an -expression--you can't use it the pattern part of a pattern-action +expression--you can't use it in the pattern part of a PATTERN-ACTION statement, for example. @@ -6131,7 +6175,7 @@ As mentioned previously, a `print' statement contains a list of items 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 built-in variable `OFS'. +the "output field separator" by setting the predefined variable `OFS'. The initial value of this variable is the string `" "'--that is, a single space. @@ -6193,12 +6237,12 @@ to format numbers (or strings), and that there are a number of different ways in which numbers can be formatted. The different format specifications are discussed more fully in *note Control Letters::. - The built-in variable `OFMT' contains the default format -specification that `print' uses with `sprintf()' when it wants to -convert a number to a string for printing. The default value of `OFMT' -is `"%.6g"'. The way `print' prints numbers can be changed by -supplying different format specifications as the value of `OFMT', as -shown in the following example: + The predefined variable `OFMT' contains the format specification +that `print' uses with `sprintf()' when it wants to convert a number to +a string for printing. The default value of `OFMT' is `"%.6g"'. The +way `print' prints numbers can be changed by supplying a different +format specification for the value of `OFMT', as shown in the following +example: $ awk 'BEGIN { > OFMT = "%.0f" # print numbers as integers (rounds) @@ -6220,8 +6264,6 @@ by `print', use `printf'. With `printf' you can specify the width to use for each item, as well as various formatting choices for numbers (such as what output base to use, whether to print an exponent, whether to print a sign, and how many digits to print after the decimal point). -You do this by supplying a string, called the "format string", that -controls how and where to print the other arguments. * Menu: @@ -6240,10 +6282,10 @@ A simple `printf' statement looks like this: printf FORMAT, ITEM1, ITEM2, ... -The entire list of arguments may optionally be enclosed in parentheses. -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 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::). The difference between `printf' and `print' is the FORMAT argument. This is an expression whose value is taken as a string; it specifies @@ -6264,10 +6306,10 @@ statements. For example: $ awk 'BEGIN { > ORS = "\nOUCH!\n"; OFS = "+" - > msg = "Dont Panic!" + > msg = "Don\47t Panic!" > printf "%s\n", msg > }' - -| Dont Panic! + -| Don't Panic! Here, neither the `+' nor the `OUCH' appear in the output message. @@ -6285,9 +6327,9 @@ print. The rest of the format specifier is made up of optional width. Here is a list of the format-control letters: `%c' - Print a number as an ASCII character; thus, `printf "%c", 65' - outputs the letter `A'. The output for a string value is the first - character of the string. + Print a number as a character; thus, `printf "%c", 65' outputs the + letter `A'. The output for a string value is the first character + of the string. NOTE: The POSIX standard says the first character of a string is printed. In locales with multibyte characters, `gawk' @@ -6380,7 +6422,7 @@ File: gawk.info, Node: Format Modifiers, Next: Printf Examples, Prev: Control A format specification can also include "modifiers" that can control how much of the item's value is printed, as well as how much space it gets. The modifiers come between the `%' and the format-control letter. -We will use the bullet symbol "*" in the following examples to represent +We use the bullet symbol "*" in the following examples to represent spaces in the output. Here are the possible modifiers, in the order in which they may appear: @@ -6400,8 +6442,7 @@ which they may appear: At first glance, this feature doesn't seem to be of much use. It is in fact a `gawk' extension, intended for use in translating messages at runtime. *Note Printf Ordering::, which describes how - and why to use positional specifiers. For now, we will not use - them. + and why to use positional specifiers. For now, we ignore them. `-' The minus sign, used before the width modifier (see later on in @@ -6431,10 +6472,10 @@ which they may appear: trailing zeros are not removed from the result. `0' - A leading `0' (zero) acts as a flag that indicates that output - should be padded with zeros instead of spaces. This applies only - to the numeric output formats. This flag only has an effect when - the field width is wider than the value to print. + A leading `0' (zero) acts as a flag indicating that output should + be padded with zeros instead of spaces. This applies only to the + numeric output formats. This flag only has an effect when the + field width is wider than the value to print. `'' A single quote or apostrophe character is a POSIX extension to ISO @@ -6582,14 +6623,14 @@ beginning of the `awk' program: awk 'BEGIN { print "Name Number" print "---- ------" } - { printf "%-10s %s\n", $1, $2 }' mail-list + { 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: awk 'BEGIN { printf "%-10s %s\n", "Name", "Number" printf "%-10s %s\n", "----", "------" } - { printf "%-10s %s\n", $1, $2 }' mail-list + { printf "%-10s %s\n", $1, $2 }' mail-list Printing each column heading with the same format specification used for the column elements ensures that the headings are aligned just like @@ -6601,10 +6642,10 @@ be emphasized by storing it in a variable, like this: awk 'BEGIN { format = "%-10s %s\n" printf format, "Name", "Number" printf format, "----", "------" } - { printf format, $1, $2 }' mail-list + { printf format, $1, $2 }' mail-list -File: gawk.info, Node: Redirection, Next: Special Files, Prev: Printf, Up: Printing +File: gawk.info, Node: Redirection, Next: Special FD, Prev: Printf, Up: Printing 5.6 Redirecting Output of `print' and `printf' ============================================== @@ -6614,7 +6655,7 @@ output, usually the screen. Both `print' and `printf' can also send their output to other places. This is called "redirection". NOTE: When `--sandbox' is specified (*note Options::), redirecting - output to files and pipes is disabled. + output to files, pipes and coprocesses is disabled. A redirection appears after the `print' or `printf' statement. Redirections in `awk' are written just like redirections in shell @@ -6685,16 +6726,10 @@ work identically for `printf': maintenance: report = "mail bug-system" - print "Awk script failed:", $0 | report - m = ("at record number " FNR " of " FILENAME) - print m | report + print("Awk script failed:", $0) | report + print("at record number", FNR, "of", FILENAME) | report close(report) - The message is built using string concatenation and saved in the - variable `m'. It's then sent down the pipeline to the `mail' - program. (The parentheses group the items to concatenate--see - *note Concatenation::.) - The `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. *Note Close Files And Pipes::, for more information. @@ -6760,40 +6795,30 @@ uppercase characters converted to lowercase (*note String Functions::). The program builds up a list of command lines, using the `mv' utility to rename the files. It then sends the list to the shell for execution. - -File: gawk.info, Node: Special Files, Next: Close Files And Pipes, Prev: Redirection, Up: Printing - -5.7 Special File Names in `gawk' -================================ - -`gawk' provides a number of special file names that it interprets -internally. These file names provide access to standard file -descriptors and TCP/IP networking. - -* Menu: - -* Special FD:: Special files for I/O. -* Special Network:: Special files for network communications. -* Special Caveats:: Things to watch out for. + *Note Shell Quoting::, for a function that can help in generating +command lines to be fed to the shell. -File: gawk.info, Node: Special FD, Next: Special Network, Up: Special Files +File: gawk.info, Node: Special FD, Next: Special Files, Prev: Redirection, Up: Printing -5.7.1 Special Files for Standard Descriptors --------------------------------------------- +5.7 Special Files for Standard Pre-Opened Data Streams +====================================================== Running programs conventionally have three input and output streams already available to them for reading and writing. These are known as the "standard input", "standard output", and "standard error output". -These streams are, by default, connected to your keyboard and screen, -but they are often redirected with the shell, via the `<', `<<', `>', -`>>', `>&', and `|' operators. Standard error is typically used for -writing error messages; the reason there are two separate streams, +These open streams (and any other open file or pipe) are often referred +to by the technical term "file descriptors". + + These streams are, by default, connected to your keyboard and +screen, but they are often redirected with the shell, via the `<', `<<', +`>', `>>', `>&', and `|' operators. Standard error is typically used +for writing error messages; the reason there are two separate streams, standard output and standard error, is so that they can be redirected separately. - In other implementations of `awk', the only way to write an error -message to standard error in an `awk' program is as follows: + In traditional implementations of `awk', the only way to write an +error message to standard error in an `awk' program is as follows: print "Serious error detected!" | "cat 1>&2" @@ -6808,19 +6833,18 @@ error messages to the screen, like this: (`/dev/tty' is a special file supplied by the operating system that is connected to your keyboard and screen. It represents the "terminal,"(1) which on modern systems is a keyboard and screen, not a serial console.) -This usually has the same effect but not always: although the standard -error stream is usually the screen, it can be redirected; when 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 +This generally has the same effect but not always: although the +standard error stream is usually the screen, it can be redirected; when +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' provides special file names for accessing the three standard -streams. (c.e.) It also provides syntax for accessing any other -inherited open files. If the file name matches one of these special -names when `gawk' redirects input or output, then it directly uses the -stream that the file name stands for. These special file names work -for all operating systems that `gawk' has been ported to, not just -those that are POSIX-compliant: + `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 +stands for. These special file names work for all operating systems +that `gawk' has been ported to, not just those that are POSIX-compliant: `/dev/stdin' The standard input (file descriptor 0). @@ -6831,16 +6855,8 @@ those that are POSIX-compliant: `/dev/stderr' The standard error output (file descriptor 2). -`/dev/fd/N' - The file associated with file descriptor N. Such a file must be - opened by the program initiating the `awk' execution (typically - the shell). Unless special pains are taken in the shell from which - `gawk' is invoked, only descriptors 0, 1, and 2 are available. - - The file names `/dev/stdin', `/dev/stdout', and `/dev/stderr' are -aliases for `/dev/fd/0', `/dev/fd/1', and `/dev/fd/2', respectively. -However, they are more self-explanatory. The proper way to write an -error message in a `gawk' program is to use `/dev/stderr', like this: + With these facilities, the proper way to write an error message then +becomes: print "Serious error detected!" > "/dev/stderr" @@ -6848,21 +6864,60 @@ error message in a `gawk' program is to use `/dev/stderr', like this: redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results. - Finally, using the `close()' function on a file name of the form -`"/dev/fd/N"', for file descriptor numbers above two, does actually -close the given file descriptor. - - The `/dev/stdin', `/dev/stdout', and `/dev/stderr' special files are -also recognized internally by several other versions of `awk'. + `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::). ---------- Footnotes ---------- (1) The "tty" in `/dev/tty' stands for "Teletype," a serial terminal. -File: gawk.info, Node: Special Network, Next: Special Caveats, Prev: Special FD, Up: Special Files +File: gawk.info, Node: Special Files, Next: Close Files And Pipes, Prev: Special FD, Up: Printing + +5.8 Special File Names in `gawk' +================================ + +Besides access to standard input, stanard output, and standard error, +`gawk' provides access to any open file descriptor. Additionally, +there are special file names reserved for TCP/IP networking. + +* Menu: + +* Other Inherited Files:: Accessing other open files with + `gawk'. +* Special Network:: Special files for network communications. +* Special Caveats:: Things to watch out for. + + +File: gawk.info, Node: Other Inherited Files, Next: Special Network, Up: Special Files + +5.8.1 Accessing Other Open Files With `gawk' +-------------------------------------------- + +Besides the `/dev/stdin', `/dev/stdout', and `/dev/stderr' special file +names mentioned earlier, `gawk' provides syntax for accessing any other +inherited open file: + +`/dev/fd/N' + The file associated with file descriptor N. Such a file must be + opened by the program initiating the `awk' execution (typically + the shell). Unless special pains are taken in the shell from which + `gawk' is invoked, only descriptors 0, 1, and 2 are available. -5.7.2 Special Files for Network Communications + The file names `/dev/stdin', `/dev/stdout', and `/dev/stderr' are +essentially aliases for `/dev/fd/0', `/dev/fd/1', and `/dev/fd/2', +respectively. However, those names are more self-explanatory. + + Note that using `close()' on a file name of the form `"/dev/fd/N"', +for file descriptor numbers above two, does actually close the given +file descriptor. + + +File: gawk.info, Node: Special Network, Next: Special Caveats, Prev: Other Inherited Files, Up: Special Files + +5.8.2 Special Files for Network Communications ---------------------------------------------- `gawk' programs can open a two-way TCP/IP connection, acting as either @@ -6882,14 +6937,18 @@ mentioned here only for completeness. Full discussion is delayed until File: gawk.info, Node: Special Caveats, Prev: Special Network, Up: Special Files -5.7.3 Special File Name Caveats +5.8.3 Special File Name Caveats ------------------------------- -Here is a list of things to bear in mind when using the special file -names that `gawk' provides: +Here are some things to bear in mind when using the special file names +that `gawk' provides: - * Recognition of these special file names is disabled if `gawk' is in - compatibility mode (*note Options::). + * Recognition of the file names for the three standard pre-opened + files is disabled only in POSIX mode. + + * Recognition of the other special file names is disabled if `gawk' + is in compatibility mode (either `--traditional' or `--posix'; + *note Options::). * `gawk' _always_ interprets these special file names. For example, using `/dev/fd/4' for output actually writes on file descriptor 4, @@ -6902,7 +6961,7 @@ names that `gawk' provides: File: gawk.info, Node: Close Files And Pipes, Next: Output Summary, Prev: Special Files, Up: Printing -5.8 Closing Input and Output Redirections +5.9 Closing Input and Output Redirections ========================================= If the same file name or the same shell command is used with `getline' @@ -7016,7 +7075,8 @@ 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. It is, more likely, a close of a file that was never opened with a -redirection, so `awk' silently does nothing. +redirection, so `awk' silently does nothing, except return a negative +value. When using the `|&' operator to communicate with a coprocess, it is occasionally useful to be able to close one end of the two-way pipe @@ -7025,8 +7085,8 @@ to `close()'. As in any other call to `close()', the first argument is the name of the command or special file used to start the coprocess. The second argument should be a string, with either of the values `"to"' or `"from"'. Case does not matter. As this is an advanced -feature, a more complete discussion is delayed until *note Two-way -I/O::, which discusses it in more detail and gives an example. +feature, discussion is delayed until *note Two-way I/O::, which +describes it in more detail and gives an example. Using `close()''s Return Value @@ -7041,8 +7101,8 @@ value from `close()': (d.c.) `gawk' treats `close()' as a function. The return value is -1 if the argument names something that was never opened with a redirection, or if there is a system problem closing the file or process. In these -cases, `gawk' sets the built-in variable `ERRNO' to a string describing -the problem. +cases, `gawk' sets the predefined variable `ERRNO' to a string +describing the problem. In `gawk', when closing a pipe or coprocess (input or output), the return value is the exit status of the command.(2) Otherwise, it is the @@ -7067,10 +7127,10 @@ call. See the system manual pages for information on how to decode this value. -File: gawk.info, Node: Output Summary, Next: Output exercises, Prev: Close Files And Pipes, Up: Printing +File: gawk.info, Node: Output Summary, Next: Output Exercises, Prev: Close Files And Pipes, Up: Printing -5.9 Summary -=========== +5.10 Summary +============ * The `print' statement prints comma-separated expressions. Each expression is separated by the value of `OFS' and terminated by @@ -7082,20 +7142,20 @@ File: gawk.info, Node: Output Summary, Next: Output exercises, Prev: Close Fi flags that modify the behavior of the format control letters. * Output from both `print' and `printf' may be redirected to files, - pipes, and co-processes. + pipes, and coprocesses. * `gawk' provides special file names for access to standard input, output and error, and for network communications. - * Use `close()' to close open file, pipe and co-process redirections. - For co-processes, it is possible to close only one direction of the + * Use `close()' to close open file, pipe and coprocess redirections. + For coprocesses, it is possible to close only one direction of the communications. -File: gawk.info, Node: Output exercises, Prev: Output Summary, Up: Printing +File: gawk.info, Node: Output Exercises, Prev: Output Summary, Up: Printing -5.10 Exercises +5.11 Exercises ============== 1. Rewrite the program: @@ -7298,8 +7358,9 @@ File: gawk.info, Node: Regexp Constants, Prev: Nondecimal-numbers, Up: Consta A regexp constant is a regular expression description enclosed in slashes, such as `/^beginning and end$/'. Most regexps used in `awk' programs are constant, but the `~' and `!~' matching operators can also -match computed or dynamic regexps (which are just ordinary strings or -variables that contain a regexp). +match computed or dynamic regexps (which are typically just ordinary +strings or variables that contain a regexp, but could be a more complex +expression). File: gawk.info, Node: Using Constant Regexps, Next: Variables, Prev: Constants, Up: Values @@ -7324,7 +7385,7 @@ and: are exactly equivalent. One rather bizarre consequence of this rule is that the following Boolean expression is valid, but does not do what -the user probably intended: +its author probably intended: # Note that /foo/ is on the left of the ~ if (/foo/ ~ $1) print "found foo" @@ -7350,9 +7411,10 @@ of the `match()' function, and as the third argument of the `split()' and `patsplit()' functions (*note String Functions::). Modern implementations of `awk', including `gawk', allow the third argument of `split()' to be a regexp constant, but some older implementations do -not. (d.c.) This can lead to confusion when attempting to use regexp -constants as arguments to user-defined functions (*note User-defined::). -For example: +not. (d.c.) Because some built-in functions accept regexp constants +as arguments, it can be confusing when attempting to use regexp +constants as arguments to user-defined functions (*note +User-defined::). For example: function mysub(pat, repl, str, global) { @@ -7405,31 +7467,34 @@ File: gawk.info, Node: Using Variables, Next: Assignment Options, Up: Variabl Variables let you give names to values and refer to them later. Variables have already been used in many of the examples. The name of a variable must be a sequence of letters, digits, or underscores, and -it may not begin with a digit. Case is significant in variable names; -`a' and `A' are distinct variables. +it may not begin with a digit. Here, a "letter" is any one of the 52 +upper- and lowercase English letters. Other characters that may be +defined as letters in non-English locales are not valid in variable +names. Case is significant in variable names; `a' and `A' are distinct +variables. A variable name is a valid expression by itself; it represents the 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()', -`patsplit()' and `split()' 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 field separator), and `NF' (the number of fields in the current input -record). *Note Built-in Variables::, for a list of the built-in -variables. These built-in variables can be used and assigned just like -all other variables, but their values are also used or changed -automatically by `awk'. All built-in variables' names are entirely +record). *Note 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 `awk'. All predefined variables' names are entirely uppercase. Variables in `awk' can be assigned either numeric or string values. The kind of value a variable holds can change over the life of a program. By default, variables are initialized to the empty string, which is zero if converted to a number. There is no need to explicitly -"initialize" a variable in `awk', which is what you would do in C and -in most other traditional languages. +initialize a variable in `awk', which is what you would do in C and in +most other traditional languages. File: gawk.info, Node: Assignment Options, Prev: Using Variables, Up: Variables @@ -7525,7 +7590,7 @@ the string as numerals: `"2.5"' converts to 2.5, `"1e3"' converts to interpreted as valid numbers convert to zero. The exact manner in which numbers are converted into strings is -controlled by the `awk' built-in variable `CONVFMT' (*note Built-in +controlled by the `awk' predefined variable `CONVFMT' (*note Built-in Variables::). Numbers are converted using the `sprintf()' function with `CONVFMT' as the format specifier (*note String Functions::). @@ -7604,8 +7669,8 @@ difference in behavior, on a GNU/Linux system: The `en_DK.utf-8' locale is for English in Denmark, where the comma acts as the decimal point separator. In the normal `"C"' locale, `gawk' -treats `4,321' as `4', while in the Danish locale, it's treated as the -full number, 4.321. +treats `4,321' as 4, while in the Danish locale, it's treated as the +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 @@ -7987,8 +8052,7 @@ A workaround is: awk '/[=]=/' /dev/null - `gawk' does not have this problem; BWK `awk' and `mawk' also do not -(*note Other Versions::). + `gawk' does not have this problem; BWK `awk' and `mawk' also do not. File: gawk.info, Node: Increment Ops, Prev: Assignment Ops, Up: All Operators @@ -8165,9 +8229,9 @@ determine how they are compared. Variable typing follows these rules: STRING attribute. * Fields, `getline' input, `FILENAME', `ARGV' elements, `ENVIRON' - elements, and the elements of an array created by `patsplit()', - `split()' and `match()' that are numeric strings have the STRNUM - attribute. Otherwise, they have the STRING attribute. + elements, and the elements of an array created by `match()', + `split()' and `patsplit()' that are numeric strings have the + STRNUM attribute. Otherwise, they have the STRING attribute. Uninitialized variables also have the STRNUM attribute. * Attributes propagate across assignments but are not changed by any @@ -8217,21 +8281,21 @@ In contrast, the eight characters `" +3.14"' appearing in program text comprise a string constant. The following examples print `1' when the comparison between the two different constants is true, `0' otherwise: - $ echo ' +3.14' | gawk '{ print $0 == " +3.14" }' True + $ echo ' +3.14' | awk '{ print($0 == " +3.14") }' True -| 1 - $ echo ' +3.14' | gawk '{ print $0 == "+3.14" }' False + $ echo ' +3.14' | awk '{ print($0 == "+3.14") }' False -| 0 - $ echo ' +3.14' | gawk '{ print $0 == "3.14" }' False + $ echo ' +3.14' | awk '{ print($0 == "3.14") }' False -| 0 - $ echo ' +3.14' | gawk '{ print $0 == 3.14 }' True + $ echo ' +3.14' | awk '{ print($0 == 3.14) }' True -| 1 - $ echo ' +3.14' | gawk '{ print $1 == " +3.14" }' False + $ echo ' +3.14' | awk '{ print($1 == " +3.14") }' False -| 0 - $ echo ' +3.14' | gawk '{ print $1 == "+3.14" }' True + $ echo ' +3.14' | awk '{ print($1 == "+3.14") }' True -| 1 - $ echo ' +3.14' | gawk '{ print $1 == "3.14" }' False + $ echo ' +3.14' | awk '{ print($1 == "3.14") }' False -| 0 - $ echo ' +3.14' | gawk '{ print $1 == 3.14 }' True + $ echo ' +3.14' | awk '{ print($1 == 3.14) }' True -| 1 @@ -8284,8 +8348,9 @@ Unless `b' happens to be zero or the null string, the `if' part of the test always succeeds. Because the operators are so similar, this kind of error is very difficult to spot when scanning the source code. - The following table of expressions illustrates the kind of comparison -`gawk' performs, as well as what the result of the comparison is: + The following list of expressions illustrates the kinds of +comparisons `awk' performs, as well as what the result of each +comparison is: `1.5 <= 2.0' numeric comparison (true) @@ -8336,9 +8401,9 @@ regexp constant (`/'...`/') or an ordinary expression. In the latter case, the value of the expression as a string is used as a dynamic regexp (*note Regexp Usage::; also *note Computed Regexps::). - In modern implementations of `awk', a constant regular expression in -slashes by itself is also an expression. The regexp `/REGEXP/' is an -abbreviation for the following comparison expression: + A constant regular expression in slashes by itself is also an +expression. The regexp `/REGEXP/' is an abbreviation for the following +comparison expression: $0 ~ /REGEXP/ @@ -8354,9 +8419,9 @@ File: gawk.info, Node: POSIX String Comparison, Prev: Comparison Operators, U The POSIX standard says that string comparison is performed based on the locale's "collating order". This is the order in which characters -sort, as defined by the locale (for more discussion, *note Ranges and -Locales::). This order is usually very different from the results -obtained when doing straight character-by-character comparison.(1) +sort, as defined by the locale (for more discussion, *note Locales::). +This order is usually very different from the results obtained when +doing straight character-by-character comparison.(1) Because this behavior differs considerably from existing practice, `gawk' only implements it when in POSIX mode (*note Options::). Here @@ -8413,13 +8478,15 @@ Boolean operators are: `BOOLEAN1 || BOOLEAN2' True if at least one of BOOLEAN1 or BOOLEAN2 is true. For example, the following statement prints all records in the input - that contain _either_ `edu' or `li' or both: + that contain _either_ `edu' or `li': if ($0 ~ /edu/ || $0 ~ /li/) print The subexpression BOOLEAN2 is evaluated only if BOOLEAN1 is false. This can make a difference when BOOLEAN2 contains expressions that - have side effects. + have side effects. (Thus, this test never really distinguishes + records that contain both `edu' and `li'--as soon as `edu' is + matched, the full test succeeds.) `! BOOLEAN' True if BOOLEAN is false. For example, the following program @@ -8427,7 +8494,7 @@ Boolean operators are: variable is not defined: BEGIN { if (! ("HOME" in ENVIRON)) - print "no home!" } + print "no home!" } (The `in' operator is described in *note Reference to Elements::.) @@ -8436,9 +8503,9 @@ because of the way they work. Evaluation of the full expression is "short-circuited" if the result can be determined part way through its evaluation. - Statements that use `&&' or `||' can be continued simply by putting -a newline after them. But you cannot put a newline in front of either -of these operators without using backslash continuation (*note + Statements that end with `&&' or `||' can be continued simply by +putting a newline after them. But you cannot put a newline in front of +either of these operators without using backslash continuation (*note Statements/Lines::). The actual value of an expression using the `!' operator is either @@ -8449,7 +8516,7 @@ following program is one way to print lines in between special bracketing lines: $1 == "START" { interested = ! interested; next } - interested == 1 { print } + interested { print } $1 == "END" { interested = ! interested; next } The variable `interested', as with all `awk' variables, starts out @@ -8459,6 +8526,14 @@ using `!'. The next rule prints lines as long as `interested' is true. When a line is seen whose first field is `END', `interested' is toggled back to false.(1) + Most commonly, the `!' operator is used in the conditions of `if' +and `while' statements, where it often makes more sense to phrase the +logic in the negative: + + if (! SOME CONDITION || SOME OTHER CONDITION) { + ... DO WHATEVER PROCESSING ... + } + NOTE: The `next' statement is discussed in *note Next Statement::. `next' tells `awk' to skip the rest of the rules, get the next record, and start processing the rules over again at the top. The @@ -8642,7 +8717,7 @@ violates the precedence rules; for example, `$$0++--' is not a valid expression because the first `$' has higher precedence than the `++'; to avoid the problem the expression can be rewritten as `$($0++)--'. - This table presents `awk''s operators, in order of highest to lowest + This list presents `awk''s operators, in order of highest to lowest precedence: `('...`)' @@ -8717,8 +8792,8 @@ system about the local character set and language. The ISO C standard defines a default `"C"' locale, which is an environment that is typical of what many C programmers are used to. - Once upon a time, the locale setting used to affect regexp matching -(*note Ranges and Locales::), but this is no longer true. + Once upon a time, the locale setting used to affect regexp matching, +but this is no longer true (*note Ranges and Locales::). Locales can affect record splitting. For the normal case of `RS = "\n"', the locale is largely irrelevant. For other single-character @@ -8770,10 +8845,11 @@ File: gawk.info, Node: Expressions Summary, Prev: Locales, Up: Expressions * `awk' provides the usual arithmetic operators (addition, subtraction, multiplication, division, modulus), and unary plus and minus. It also provides comparison operators, boolean - operators, and regexp matching operators. String concatenation is - accomplished by placing two expressions next to each other; there - is no explicit operator. The three-operand `?:' operator provides - an "if-else" test within expressions. + operators, array membership testing, and regexp matching + operators. String concatenation is accomplished by placing two + expressions next to each other; there is no explicit operator. + The three-operand `?:' operator provides an "if-else" test within + expressions. * Assignment operators provide convenient shorthands for common arithmetic operations. @@ -8781,8 +8857,8 @@ File: gawk.info, Node: Expressions Summary, Prev: Locales, Up: Expressions * In `awk', a value is considered to be true if it is non-zero _or_ non-null. Otherwise, the value is false. - * A value's type is set upon each assignment and may change over its - lifetime. The type determines how it behaves in comparisons + * A variable's type is set upon each assignment and may change over + its lifetime. The type determines how it behaves in comparisons (string or numeric). * Function calls return a value which may be used as part of a larger @@ -8808,7 +8884,7 @@ File: gawk.info, Node: Patterns and Actions, Next: Arrays, Prev: Expressions, As you have already seen, each `awk' statement consists of a pattern with an associated action. This major node describes how you build patterns and actions, what kinds of things you can do within actions, -and `awk''s built-in variables. +and `awk''s predefined variables. The pattern-action rules and the statements available for use within actions form the core of `awk' programming. In a sense, everything @@ -8822,7 +8898,7 @@ top of. Now it's time to start building something useful. * Action Overview:: What goes into an action. * Statements:: Describes the various control statements in detail. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * Pattern Action Summary:: Patterns and Actions summary. @@ -8853,7 +8929,7 @@ summary of the types of `awk' patterns: number) or non-null (if a string). (*Note Expression Patterns::.) `BEGPAT, ENDPAT' - A pair of patterns separated by a comma, specifying a range of + A pair of patterns separated by a comma, specifying a "range" of records. The range includes both the initial record that matches BEGPAT and the final record that matches ENDPAT. (*Note Ranges::.) @@ -8914,7 +8990,7 @@ precisely `li': `li'.) Contrast this with the following regular expression match, which accepts any record with a first field that contains `li': - $ awk '$1 ~ /foo/ { print $2 }' mail-list + $ awk '$1 ~ /li/ { print $2 }' mail-list -| 555-5553 -| 555-6699 @@ -9064,7 +9140,7 @@ input is read. For example: $ awk ' > BEGIN { print "Analysis of \"li\"" } - > /li/ { ++n } + > /li/ { ++n } > END { print "\"li\" appears in", n, "records." }' mail-list -| Analysis of "li" -| "li" appears in 4 records. @@ -9133,9 +9209,10 @@ and `NF' were _undefined_ inside an `END' rule. The POSIX standard specifies that `NF' is available in an `END' rule. It contains the number of fields from the last input record. Most probably due to an oversight, the standard does not say that `$0' is also preserved, -although logically one would think that it should be. In fact, `gawk' -does preserve the value of `$0' for use in `END' rules. Be aware, -however, that BWK `awk', and possibly other implementations, do not. +although logically one would think that it should be. In fact, all of +BWK `awk', `mawk', and `gawk' preserve the value of `$0' for use in +`END' rules. Be aware, however, that some other implementations and +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 @@ -9204,9 +9281,9 @@ makes it possible to catch and process I/O errors at the level of the `awk' program. The `next' statement (*note Next Statement::) is not allowed inside -either a `BEGINFILE' or and `ENDFILE' rule. The `nextfile' statement -(*note Nextfile Statement::) is allowed only inside a `BEGINFILE' rule, -but not inside an `ENDFILE' rule. +either a `BEGINFILE' or an `ENDFILE' rule. The `nextfile' statement is +allowed only inside a `BEGINFILE' rule, but not inside an `ENDFILE' +rule. The `getline' statement (*note Getline::) is restricted inside both `BEGINFILE' and `ENDFILE': only redirected forms of `getline' are @@ -9241,9 +9318,9 @@ hold a pattern that the `awk' program searches for. There are two ways to get the value of the shell variable into the body of the `awk' program. - The most common method is to use shell quoting to substitute the -variable's value into the program inside the script. For example, -consider the following program: + A common method is to use shell quoting to substitute the variable's +value into the program inside the script. For example, consider the +following program: printf "Enter search pattern: " read pattern @@ -9434,18 +9511,18 @@ thing the `while' statement does is test the CONDITION. If the CONDITION is true, it executes the statement BODY. (The CONDITION is true when the value is not zero and not a null string.) After BODY has been executed, CONDITION is tested again, and if it is still true, BODY -is executed again. This process repeats until the CONDITION is no -longer true. If the CONDITION is initially false, the body of the loop -is never executed and `awk' continues with the statement following the -loop. This example prints the first three fields of each record, one -per line: - - awk '{ - i = 1 - while (i <= 3) { - print $i - i++ - } +executes again. This process repeats until the CONDITION is no longer +true. If the CONDITION is initially false, the body of the loop never +executes and `awk' continues with the statement following the loop. +This example prints the first three fields of each record, one per line: + + awk ' + { + i = 1 + while (i <= 3) { + print $i + i++ + } }' inventory-shipped The body of this loop is a compound statement enclosed in braces, @@ -9476,22 +9553,22 @@ the CONDITION is true. It looks like this: BODY while (CONDITION) - Even if the CONDITION is false at the start, the BODY is executed at + Even if the CONDITION is false at the start, the BODY executes at least once (and only once, unless executing BODY makes CONDITION true). Contrast this with the corresponding `while' statement: while (CONDITION) - BODY + BODY This statement does not execute BODY even once if the CONDITION is false to begin with. The following is an example of a `do' statement: { - i = 1 - do { - print $0 - i++ - } while (i <= 10) + i = 1 + do { + print $0 + i++ + } while (i <= 10) } This program prints each input record 10 times. However, it isn't a @@ -9520,9 +9597,10 @@ INCREMENT. Typically, INITIALIZATION sets a variable to either zero or one, INCREMENT adds one to it, and CONDITION compares it against the desired number of iterations. For example: - awk '{ - for (i = 1; i <= 3; i++) - print $i + awk ' + { + for (i = 1; i <= 3; i++) + print $i }' inventory-shipped This prints the first three fields of each input record, with one field @@ -9546,7 +9624,7 @@ whatsoever. For example, the following statement prints all the powers of two between 1 and 100: for (i = 1; i <= 100; i *= 2) - print i + print i If there is nothing to be done, any of the three expressions in the parentheses following the `for' keyword may be omitted. Thus, @@ -9787,9 +9865,8 @@ complicating the rest of the program, write a "weed out" rule near the beginning, in the following manner: NF != 4 { - err = sprintf("%s:%d: skipped: NF != 4\n", FILENAME, FNR) - print err > "/dev/stderr" - next + printf("%s:%d: skipped: NF != 4\n", FILENAME, FNR) > "/dev/stderr" + next } Because of the `next' statement, the program's subsequent rules won't @@ -9805,11 +9882,11 @@ rules. *Note BEGINFILE/ENDFILE::. According to the POSIX standard, the behavior is undefined if the `next' statement is used in a `BEGIN' or `END' rule. `gawk' treats it -as a syntax error. Although POSIX permits it, most other `awk' -implementations don't allow the `next' statement inside function bodies -(*note User-defined::). Just as with any other `next' statement, a -`next' statement inside a function body reads the next record and -starts processing it with the first rule in the program. +as a syntax error. Although POSIX does not disallow it, most other +`awk' implementations don't allow the `next' statement inside function +bodies (*note User-defined::). Just as with any other `next' +statement, a `next' statement inside a function body reads the next +record and starts processing it with the first rule in the program. File: gawk.info, Node: Nextfile Statement, Next: Exit Statement, Prev: Next Statement, Up: Statements @@ -9827,7 +9904,7 @@ reset to one, and processing starts over with the first rule in the program. If the `nextfile' statement causes the end of the input to be reached, then the code in any `END' rules is executed. An exception to this is when `nextfile' is invoked during execution of any statement in -an `END' rule; In this case, it causes the program to stop immediately. +an `END' rule; in this case, it causes the program to stop immediately. *Note BEGIN/END::. The `nextfile' statement is useful when there are many data files to @@ -9837,10 +9914,10 @@ would have to continue scanning the unwanted records. The `nextfile' statement accomplishes this much more efficiently. In `gawk', execution of `nextfile' causes additional things to -happen: any `ENDFILE' rules are executed except in the case as -mentioned below, `ARGIND' is incremented, and any `BEGINFILE' rules are -executed. (`ARGIND' hasn't been introduced yet. *Note Built-in -Variables::.) +happen: any `ENDFILE' rules are executed if `gawk' is not currently in +an `END' or `BEGINFILE' rule, `ARGIND' is incremented, and any +`BEGINFILE' rules are executed. (`ARGIND' hasn't been introduced yet. +*Note Built-in Variables::.) With `gawk', `nextfile' is useful inside a `BEGINFILE' rule to skip over a file that would otherwise cause `gawk' to exit with a fatal @@ -9853,17 +9930,17 @@ 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 `gawk' extension. As of + NOTE: For many years, `nextfile' was a 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=607). - The current version of BWK `awk', and `mawk' (*note Other -Versions::) also support `nextfile'. However, they don't allow the -`nextfile' statement inside function bodies (*note User-defined::). -`gawk' does; a `nextfile' inside a function body reads the next record -and starts processing it with the first rule in the program, just as -any other `nextfile' statement. + The current version of BWK `awk', and `mawk' also support +`nextfile'. However, they don't allow the `nextfile' statement inside +function bodies (*note User-defined::). `gawk' does; a `nextfile' +inside a function body reads the next record and starts processing it +with the first rule in the program, just as any other `nextfile' +statement. File: gawk.info, Node: Exit Statement, Prev: Nextfile Statement, Up: Statements @@ -9887,8 +9964,8 @@ stop immediately. An `exit' statement that is not part of a `BEGIN' or `END' rule stops the execution of any further automatic rules for the current record, skips reading any remaining input records, and executes the -`END' rule if there is one. Any `ENDFILE' rules are also skipped; they -are not executed. +`END' rule if there is one. `gawk' also skips any `ENDFILE' rules; +they do not execute. In such a case, if you don't want the `END' rule to do its job, set a variable to nonzero before the `exit' statement and check that @@ -9925,8 +10002,8 @@ statement with a nonzero argument, as shown in the following example: File: gawk.info, Node: Built-in Variables, Next: Pattern Action Summary, Prev: Statements, Up: Patterns and Actions -7.5 Built-in Variables -====================== +7.5 Predefined Variables +======================== Most `awk' variables are available to use for your own purposes; they never change unless your program assigns values to them, and they never @@ -9936,7 +10013,7 @@ of these automatically, so that they enable you to tell `awk' how to do certain things. Others are set automatically by `awk', so that they carry information from the internal workings of `awk' to your program. - This minor node documents all of `gawk''s built-in variables, most + This minor node documents all of `gawk''s predefined variables, most of which are also documented in the major nodes describing their areas of activity. @@ -9975,7 +10052,7 @@ description of each variable.) use binary I/O. Any other string value is treated the same as `"rw"', but causes `gawk' to generate a warning message. `BINMODE' is described in more detail in *note PC Using::. `mawk' - *note Other Versions::), also supports this variable, but only + (*note Other Versions::), also supports this variable, but only using numeric values. ``CONVFMT'' @@ -10058,9 +10135,8 @@ description of each variable.) printing with the `print' statement. It works by being passed as the first argument to the `sprintf()' function (*note String Functions::). Its default value is `"%.6g"'. Earlier versions of - `awk' also used `OFMT' to specify the format for converting - numbers to strings in general expressions; this is now done by - `CONVFMT'. + `awk' used `OFMT' to specify the format for converting numbers to + strings in general expressions; this is now done by `CONVFMT'. `OFS' This is the output field separator (*note Output Separators::). @@ -10169,8 +10245,8 @@ Options::), they are not special. the command line. While you can change the value of `ARGIND' within your `awk' - program, `gawk' automatically sets it to a new value when the next - file is opened. + program, `gawk' automatically sets it to a new value when it opens + the next file. `ENVIRON' An associative array containing the values of the environment. @@ -10220,9 +10296,9 @@ Options::), they are not special. Getline::) inside a `BEGIN' rule can give `FILENAME' a value. `FNR' - The current record number in the current file. `FNR' is - incremented each time a new record is read (*note Records::). It - is reinitialized to zero each time a new input file is started. + The current record number in the current file. `awk' increments + `FNR' each time it reads a new record (*note Records::). `awk' + resets `FNR' to zero each time it starts a new input file. `NF' The number of fields in the current input record. `NF' is set @@ -10237,7 +10313,8 @@ Options::), they are not special. `FUNCTAB #' An array whose indices and corresponding values are the names of - all the user-defined or extension functions in the program. + all the built-in, user-defined and extension functions in the + program. NOTE: Attempting to use the `delete' statement with the `FUNCTAB' array causes a fatal error. Any attempt to assign @@ -10245,8 +10322,8 @@ Options::), they are not special. `NR' The number of input records `awk' has processed since the - beginning of the program's execution (*note Records::). `NR' is - incremented each time a new record is read. + beginning of the program's execution (*note Records::). `awk' + increments `NR' each time it reads a new record. `PROCINFO #' The elements of this array provide access to information about the @@ -10267,15 +10344,21 @@ Options::), they are not special. `PROCINFO["identifiers"]' A subarray, indexed by the names of all identifiers used in - the text of the AWK program. For each identifier, the value - of the element is one of the following: + the text of the AWK program. An "identifier" is simply the + name of a variable (be it scalar or array), built-in + function, user-defined function, or extension function. For + each identifier, the value of the element is one of the + following: `"array"' The identifier is an array. + `"builtin"' + The identifier is a built-in function. + `"extension"' The identifier is an extension function loaded via - `@load'. + `@load' or `-l'. `"scalar"' The identifier is a scalar. @@ -10305,7 +10388,7 @@ 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 (INDEX + 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 Array::. @@ -10323,7 +10406,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 numbers (*note + version of `gawk' supports arbitrary precision arithmetic (*note Arbitrary Precision Arithmetic::): `PROCINFO["mpfr_version"]' @@ -10356,14 +10439,14 @@ Options::), they are not special. The `PROCINFO' array has the following additional uses: - * It may be used to cause coprocesses to communicate over - pseudo-ttys instead of through two-way pipes; this is - discussed further in *note Two-way I/O::. - * It may be used to provide a timeout when reading from any open input file, pipe, or coprocess. *Note Read Timeout::, for more information. + * It may be used to cause coprocesses to communicate over + pseudo-ttys instead of through two-way pipes; this is + discussed further in *note Two-way I/O::. + `RLENGTH' The length of the substring matched by the `match()' function (*note String Functions::). `RLENGTH' is set by invoking the @@ -10382,9 +10465,14 @@ Options::), they are not special. separator. It is set every time a record is read. `SYMTAB #' - An array whose indices are the names of all currently defined - global variables and arrays in the program. The array may be used - for indirect access to read or write the value of a variable: + An array whose indices are the names of all defined global + variables and arrays in the program. `SYMTAB' makes `gawk''s + symbol table visible to the `awk' programmer. It is built as + `gawk' parses the program and is complete before the program + starts to run. + + The array may be used for indirect access to read or write the + value of a variable: foo = 5 SYMTAB["foo"] = 4 @@ -10552,6 +10640,12 @@ Because `-q' is not a valid `gawk' option, it and the following `-v' 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 +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::). + File: gawk.info, Node: Pattern Action Summary, Prev: Built-in Variables, Up: Patterns and Actions @@ -10581,8 +10675,8 @@ File: gawk.info, Node: Pattern Action Summary, Prev: Built-in Variables, Up: * The control statements in `awk' are `if'-`else', `while', `for', and `do'-`while'. `gawk' adds the `switch' statement. There are - two flavors of `for' statement: one for for performing general - looping, and the other iterating through an array. + two flavors of `for' statement: one for performing general + looping, and the other for iterating through an array. * `break' and `continue' let you exit early or start the next iteration of a loop (or get out of a `switch'). @@ -10594,11 +10688,16 @@ File: gawk.info, Node: Pattern Action Summary, Prev: Built-in Variables, Up: * The `exit' statement terminates your program. When executed from an action (or function body) it transfers control to the `END' statements. From an `END' statement body, it exits immediately. - You may pass an optional numeric value to be used at `awk''s exit + You may pass an optional numeric value to be used as `awk''s exit status. - * Some built-in variables provide control over `awk', mainly for I/O. - Other variables convey information from `awk' to your program. + * Some predefined variables provide control over `awk', mainly for + I/O. Other variables convey information from `awk' to your + program. + + * `ARGC' and `ARGV' make the command-line arguments available to + your program. Manipulating them from a `BEGIN' rule lets you + control how `awk' will process the provided data files. @@ -10619,26 +10718,21 @@ about array usage. The major node moves on to discuss `gawk''s facility for sorting arrays, and ends with a brief description of `gawk''s ability to support true arrays of arrays. - `awk' maintains a single set of names that may be used for naming -variables, arrays, and functions (*note User-defined::). Thus, you -cannot have a variable and an array with the same name in the same -`awk' program. - * Menu: * Array Basics:: The basics of arrays. -* Delete:: The `delete' statement removes an element - from an array. * Numeric Array Subscripts:: How to use numbers as subscripts in `awk'. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. +* Delete:: The `delete' statement removes an element + from an array. * Multidimensional:: Emulating multidimensional arrays in `awk'. * Arrays of Arrays:: True multidimensional arrays. * Arrays Summary:: Summary of arrays. -File: gawk.info, Node: Array Basics, Next: Delete, Up: Arrays +File: gawk.info, Node: Array Basics, Next: Numeric Array Subscripts, Up: Arrays 8.1 The Basics of Arrays ======================== @@ -10677,8 +10771,8 @@ program. Arrays in `awk' superficially resemble arrays in other programming languages, but there are fundamental differences. In `awk', it isn't necessary to specify the size of an array before starting to use it. -Additionally, any number or string in `awk', not just consecutive -integers, may be used as an array index. +Additionally, any number or string, not just consecutive integers, may +be used as an array index. In most other languages, arrays must be "declared" before use, including a specification of how many elements or components they @@ -10717,7 +10811,8 @@ array element value: Index 0 Value 8 Index 2 Value "" -The pairs are shown in jumbled order because their order is irrelevant. +The pairs are shown in jumbled order because their order is +irrelevant.(1) One advantage of associative arrays is that new pairs can be added at any time. For example, suppose a tenth element is added to the array @@ -10746,9 +10841,10 @@ from English to French: Here we decided to translate the number one in both spelled-out and numeric form--thus illustrating that a single array can have both numbers and strings as indices. (In fact, array subscripts are always -strings; this is discussed in more detail in *note Numeric Array -Subscripts::.) Here, the number `1' isn't double-quoted, since `awk' -automatically converts it to a string. +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 +`awk' automatically converts it to a string. The value of `IGNORECASE' has no effect upon array subscripting. The identical string value used to store an array element must be used @@ -10759,6 +10855,11 @@ starting at one. (*Note String Functions::.) `awk''s arrays are efficient--the time to access an element is independent of the number of elements in the array. + ---------- Footnotes ---------- + + (1) The ordering will vary among `awk' implementations, which +typically use hash tables to store array elements and values. + File: gawk.info, Node: Reference to Elements, Next: Assigning Elements, Prev: Array Intro, Up: Array Basics @@ -10805,7 +10906,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. For example, this statement tests +(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 whether the array `frequencies' contains the index `2': if (2 in frequencies) @@ -10849,14 +10951,14 @@ encountering repeated numbers, gaps, or lines that don't begin with a number: { - if ($1 > max) - max = $1 - arr[$1] = $0 + if ($1 > max) + max = $1 + arr[$1] = $0 } END { - for (x = 1; x <= max; x++) - print arr[x] + for (x = 1; x <= max; x++) + print arr[x] } The first rule keeps track of the largest line number seen so far; @@ -10884,9 +10986,9 @@ overrides the others. Gaps in the line numbers can be handled with an easy improvement to the program's `END' rule, as follows: END { - for (x = 1; x <= max; x++) - if (x in arr) - print arr[x] + for (x = 1; x <= max; x++) + if (x in arr) + print arr[x] } @@ -10904,7 +11006,7 @@ lowest index up to the highest. This technique won't do the job in has a special kind of `for' statement for scanning an array: for (VAR in ARRAY) - BODY + BODY This loop executes BODY once for each index in ARRAY that the program has previously used, with the variable VAR set to that index. @@ -10961,7 +11063,7 @@ all `awk' versions do so. Consider this program, named `loopcheck.awk': } } - Here is what happens when run with `gawk': + Here is what happens when run with `gawk' (and `mawk'): $ gawk -f loopcheck.awk -| here @@ -11064,7 +11166,8 @@ available: to run. Changing `PROCINFO["sorted_in"]' in the loop body does not affect the loop. For example: - $ gawk 'BEGIN { + $ gawk ' + > BEGIN { > a[4] = 4 > a[3] = 3 > for (i in a) @@ -11072,7 +11175,8 @@ affect the loop. For example: > }' -| 4 4 -| 3 3 - $ gawk 'BEGIN { + $ gawk ' + > BEGIN { > PROCINFO["sorted_in"] = "@ind_str_asc" > a[4] = 4 > a[3] = 3 @@ -11124,93 +11228,15 @@ ordering when the numeric values are equal ensures that `gawk' behaves consistently across different environments. -File: gawk.info, Node: Delete, Next: Numeric Array Subscripts, Prev: Array Basics, Up: Arrays - -8.2 The `delete' Statement -========================== - -To remove an individual element of an array, use the `delete' statement: - - delete ARRAY[INDEX-EXPRESSION] - - Once an array element has been deleted, any value the element once -had is no longer available. It is as if the element had never been -referred to or been given a value. The following is an example of -deleting elements in an array: - - for (i in frequencies) - delete frequencies[i] - -This example removes all the elements from the array `frequencies'. -Once an element is deleted, a subsequent `for' statement to scan the -array does not report that element and the `in' operator to check for -the presence of that element returns zero (i.e., false): - - delete foo[4] - if (4 in foo) - print "This will never be printed" - - It is important to note that deleting an element is _not_ the same -as assigning it a null value (the empty string, `""'). For example: - - foo[4] = "" - if (4 in foo) - print "This is printed, even though foo[4] is empty" - - It is not an error to delete an element that does not exist. -However, if `--lint' is provided on the command line (*note Options::), -`gawk' issues a warning message when an element that is not in the -array is deleted. - - All the elements of an array may be deleted with a single statement -by leaving off the subscript in the `delete' statement, as follows: - - delete ARRAY - - Using this version of the `delete' statement is about three times -more efficient than the equivalent loop that deletes each element one -at a time. - - NOTE: For many years, using `delete' without a subscript was a - `gawk' extension. As of September, 2012, it was accepted for - inclusion into the POSIX standard. See the Austin Group website - (http://austingroupbugs.net/view.php?id=544). This form of the - `delete' statement is also supported by BWK `awk' and `mawk', as - well as by a number of other implementations (*note Other - Versions::). - - The following statement provides a portable but nonobvious way to -clear out an array:(1) - - split("", array) - - The `split()' function (*note String Functions::) clears out the -target array first. This call asks it to split apart the null string. -Because there is no data to split out, the function simply clears the -array and then returns. - - CAUTION: Deleting an array does not change its type; you cannot - delete an array and then use the array's name as a scalar (i.e., a - regular variable). For example, the following does not work: - - a[1] = 3 - delete a - a = 3 - - ---------- Footnotes ---------- - - (1) Thanks to Michael Brennan for pointing this out. - - -File: gawk.info, Node: Numeric Array Subscripts, Next: Uninitialized Subscripts, Prev: Delete, Up: Arrays +File: gawk.info, Node: Numeric Array Subscripts, Next: Uninitialized Subscripts, Prev: Array Basics, Up: Arrays -8.3 Using Numbers to Subscript Arrays +8.2 Using Numbers to Subscript Arrays ===================================== An important aspect to remember about arrays is that _array subscripts are always strings_. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting -(*note Conversion::). This means that the value of the built-in +(*note Conversion::). This means that the value of the predefined variable `CONVFMT' can affect how your program accesses elements of an array. For example: @@ -11233,9 +11259,9 @@ two significant digits. This test fails, since `"12.15"' is different from `"12.153"'. According to the rules for conversions (*note Conversion::), integer -values are always converted to strings as integers, no matter what the -value of `CONVFMT' may happen to be. So the usual case of the -following works: +values always convert to strings as integers, no matter what the value +of `CONVFMT' may happen to be. So the usual case of the following +works: for (i = 1; i <= maxsub; i++) do something with array[i] @@ -11248,14 +11274,14 @@ example, that `array[17]', `array[021]', and `array[0x11]' all refer to the same element! As with many things in `awk', the majority of the time things work -as one would expect them to. But it is useful to have a precise +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 effect on your programs. -File: gawk.info, Node: Uninitialized Subscripts, Next: Multidimensional, Prev: Numeric Array Subscripts, Up: Arrays +File: gawk.info, Node: Uninitialized Subscripts, Next: Delete, Prev: Numeric Array Subscripts, Up: Arrays -8.4 Using Uninitialized Variables as Subscripts +8.3 Using Uninitialized Variables as Subscripts =============================================== Suppose it's necessary to write a program to print the input data in @@ -11266,7 +11292,7 @@ might look like this: > line 2 > line 3' | awk '{ l[lines] = $0; ++lines } > END { - > for (i = lines-1; i >= 0; --i) + > for (i = lines - 1; i >= 0; i--) > print l[i] > }' -| line 3 @@ -11287,7 +11313,7 @@ following version of the program works correctly: { l[lines++] = $0 } END { - for (i = lines - 1; i >= 0; --i) + for (i = lines - 1; i >= 0; i--) print l[i] } @@ -11301,7 +11327,86 @@ string as a subscript if `--lint' is provided on the command line (*note Options::). -File: gawk.info, Node: Multidimensional, Next: Arrays of Arrays, Prev: Uninitialized Subscripts, Up: Arrays +File: gawk.info, Node: Delete, Next: Multidimensional, Prev: Uninitialized Subscripts, Up: Arrays + +8.4 The `delete' Statement +========================== + +To remove an individual element of an array, use the `delete' statement: + + delete ARRAY[INDEX-EXPRESSION] + + Once an array element has been deleted, any value the element once +had is no longer available. It is as if the element had never been +referred to or been given a value. The following is an example of +deleting elements in an array: + + for (i in frequencies) + delete frequencies[i] + +This example removes all the elements from the array `frequencies'. +Once an element is deleted, a subsequent `for' statement to scan the +array does not report that element and the `in' operator to check for +the presence of that element returns zero (i.e., false): + + delete foo[4] + if (4 in foo) + print "This will never be printed" + + It is important to note that deleting an element is _not_ the same +as assigning it a null value (the empty string, `""'). For example: + + foo[4] = "" + if (4 in foo) + print "This is printed, even though foo[4] is empty" + + It is not an error to delete an element that does not exist. +However, if `--lint' is provided on the command line (*note Options::), +`gawk' issues a warning message when an element that is not in the +array is deleted. + + All the elements of an array may be deleted with a single statement +by leaving off the subscript in the `delete' statement, as follows: + + delete ARRAY + + Using this version of the `delete' statement is about three times +more efficient than the equivalent loop that deletes each element one +at a time. + + This form of the `delete' statement is also supported by BWK `awk' +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 + inclusion into the POSIX standard. See the Austin Group website + (http://austingroupbugs.net/view.php?id=544). + + The following statement provides a portable but nonobvious way to +clear out an array:(1) + + split("", array) + + The `split()' function (*note String Functions::) clears out the +target array first. This call asks it to split apart the null string. +Because there is no data to split out, the function simply clears the +array and then returns. + + CAUTION: Deleting all the elements from an array does not change + its type; you cannot clear an array and then use the array's name + as a scalar (i.e., a regular variable). For example, the following + does not work: + + a[1] = 3 + delete a + a = 3 + + ---------- Footnotes ---------- + + (1) Thanks to Michael Brennan for pointing this out. + + +File: gawk.info, Node: Multidimensional, Next: Arrays of Arrays, Prev: Delete, Up: Arrays 8.5 Multidimensional Arrays =========================== @@ -11313,7 +11418,7 @@ File: gawk.info, Node: Multidimensional, Next: Arrays of Arrays, Prev: Uninit 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 most languages, including `awk') to refer to an element of a +(in many languages, including `awk') to refer to an element of a two-dimensional array named `grid' is with `grid[X,Y]'. Multidimensional arrays are supported in `awk' through concatenation @@ -11454,8 +11559,9 @@ multidimensional subscript). So the following is valid in `gawk': Each subarray and the main array can be of different length. In fact, the elements of an array or its subarray do not all have to have the same type. This means that the main array and any of its subarrays -can be non-rectangular, or jagged in structure. One can assign a scalar -value to the index `4' of the main array `a': +can be non-rectangular, or jagged in structure. You can assign a scalar +value to the index `4' of the main array `a', even though `a[1]' is +itself an array and not a scalar: a[4] = "An element in a jagged array" @@ -11516,6 +11622,8 @@ an array element is itself an array: print array[i][j] } } + else + print array[i] } If the structure of a jagged array of arrays is known in advance, @@ -11746,8 +11854,9 @@ brackets ([ ]): user-defined function that can be used to obtain a random non-negative integer less than N: - function randint(n) { - return int(n * rand()) + function randint(n) + { + return int(n * rand()) } The multiplication produces a random number greater than zero and @@ -11764,8 +11873,7 @@ brackets ([ ]): # Roll 3 six-sided dice and # print total number of points. { - printf("%d points\n", - roll(6)+roll(6)+roll(6)) + printf("%d points\n", roll(6) + roll(6) + roll(6)) } CAUTION: In most `awk' implementations, including `gawk', @@ -11852,8 +11960,7 @@ 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 in alphabetic -order. +which comes towards the end since 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 @@ -11886,7 +11993,8 @@ Options::): When comparing strings, `IGNORECASE' affects the sorting (*note Array Sorting Functions::). If the SOURCE array contains subarrays as values (*note Arrays of Arrays::), they will come - last, after all scalar values. + last, after all scalar values. Subarrays are _not_ recursively + sorted. For example, if the contents of `a' are as follows: @@ -11989,7 +12097,10 @@ Options::): If FIND is not found, `index()' returns zero. - It is a fatal error to use a regexp constant for FIND. + With BWK `awk' and `gawk', it is a fatal error to use a regexp + constant for FIND. Other implementations allow it, simply + treating the regexp constant as an expression meaning `$0 ~ + /regexp/'. (d.c.). `length('[STRING]`)' Return the number of characters in STRING. If STRING is a number, @@ -12049,21 +12160,20 @@ Options::): `match()', the order is the same as for the `~' operator: `STRING ~ REGEXP'. - The `match()' function sets the built-in variable `RSTART' to the - index. It also sets the built-in variable `RLENGTH' to the length - in characters of the matched substring. If no match is found, - `RSTART' is set to zero, and `RLENGTH' to -1. + The `match()' function sets the predefined variable `RSTART' to + the index. It also sets the predefined variable `RLENGTH' to the + length in characters of the matched substring. If no match is + found, `RSTART' is set to zero, and `RLENGTH' to -1. For example: { - if ($1 == "FIND") - regex = $2 - else { - where = match($0, regex) - if (where != 0) - print "Match of", regex, "found at", - where, "in", $0 + if ($1 == "FIND") + regex = $2 + else { + where = match($0, regex) + if (where != 0) + print "Match of", regex, "found at", where, "in", $0 } } @@ -12132,7 +12242,7 @@ Options::): The `patsplit()' function splits strings into pieces in a manner similar to the way input lines are split into fields using `FPAT' - (*note Splitting By Content::. + (*note Splitting By Content::). Before splitting the string, `patsplit()' deletes any previously existing elements in the arrays ARRAY and SEPS. @@ -12143,15 +12253,14 @@ Options::): first piece is stored in `ARRAY[1]', the second piece in `ARRAY[2]', and so forth. The string value of the third argument, FIELDSEP, is a regexp describing where to split STRING (much as - `FS' can be a regexp describing where to split input records; - *note Regexp Field Splitting::). If FIELDSEP is omitted, the - value of `FS' is used. `split()' returns the number of elements - created. SEPS is a `gawk' extension with `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). + `FS' can be a regexp describing where to split input records). If + FIELDSEP is omitted, the value of `FS' is used. `split()' returns + the number of elements created. SEPS is a `gawk' extension with + `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). The `split()' function splits strings into pieces in a manner similar to the way input lines are split into fields. For example: @@ -12357,6 +12466,17 @@ Options::): Nonalphabetic characters are left unchanged. For example, `toupper("MiXeD cAsE 123")' returns `"MIXED CASE 123"'. + Matching the Null String + + In `awk', the `*' operator can match the null string. This is +particularly important for the `sub()', `gsub()', and `gensub()' +functions. For example: + + $ echo abc | awk '{ gsub(/m*/, "X"); print }' + -| XaXbXcX + +Although this makes a certain amount of sense, it can be surprising. + ---------- Footnotes ---------- (1) Unless you use the `--non-decimal-data' option, which isn't @@ -12376,8 +12496,8 @@ File: gawk.info, Node: Gory Details, Up: String Functions 9.1.3.1 More About `\' and `&' with `sub()', `gsub()', and `gensub()' ..................................................................... - CAUTION: This section has been known to cause headaches. You - might want to skip it upon first reading. + CAUTION: This subsubsection has been reported to cause headaches. + You might want to skip it upon first reading. When using `sub()', `gsub()', or `gensub()', and trying to get literal backslashes and ampersands into the replacement text, you need @@ -12511,17 +12631,6 @@ Table 9.4: Escape Sequence Processing For `gensub()' and the special cases for `sub()' and `gsub()', we recommend the use of `gawk' and `gensub()' when you have to do substitutions. - Matching the Null String - - In `awk', the `*' operator can match the null string. This is -particularly important for the `sub()', `gsub()', and `gensub()' -functions. For example: - - $ echo abc | awk '{ gsub(/m*/, "X"); print }' - -| XaXbXcX - -Although this makes a certain amount of sense, it can be surprising. - ---------- Footnotes ---------- (1) This was rather naive of him, despite there being a note in this @@ -12571,11 +12680,10 @@ parameters are enclosed in square brackets ([ ]): function--`gawk' also buffers its output and the `fflush()' function forces `gawk' to flush its buffers. - `fflush()' was added to BWK `awk' in April of 1992. For two - decades, it was not part of the POSIX standard. As of 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 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). POSIX standardizes `fflush()' as follows: If there is no argument, or if the argument is the null string (`""'), then `awk' flushes @@ -12762,7 +12870,7 @@ enclosed in square brackets ([ ]): If DATESPEC does not contain enough elements or if the resulting time is out of range, `mktime()' returns -1. -`strftime(' [FORMAT [`,' TIMESTAMP [`,' UTC-FLAG] ] ]`)' +`strftime('[FORMAT [`,' TIMESTAMP [`,' UTC-FLAG] ] ]`)' Format the time specified by TIMESTAMP based on the contents of the FORMAT string and return the result. It is similar to the function of the same name in ISO C. If UTC-FLAG is present and is @@ -12977,7 +13085,7 @@ to the standard output and interprets the current time according to the format specifiers in the string. For example: $ date '+Today is %A, %B %d, %Y.' - -| Today is Monday, May 05, 2014. + -| Today is Monday, September 22, 2014. Here is the `gawk' version of the `date' utility. It has a shell "wrapper" to handle the `-u' option, which requires that `date' run as @@ -13066,12 +13174,13 @@ a given value. Finally, two other common operations are to shift the bits left or right. For example, if you have a bit string `10111001' and you shift -it right by three bits, you end up with `00010111'.(1) If you start over -again with `10111001' and shift it left by three bits, you end up with -`11001000'. `gawk' provides built-in functions that implement the -bitwise operations just described. They are: +it right by three bits, you end up with `00010111'.(1) If you start +over again with `10111001' and shift it left by three bits, you end up +with `11001000'. The following list describes `gawk''s built-in +functions that implement the bitwise operations. Optional parameters +are enclosed in square brackets ([ ]): -``and(V1, V2' [`,' ...]`)'' +``and('V1`,' V2 [`,' ...]`)'' Return the bitwise AND of the arguments. There must be at least two. @@ -13081,13 +13190,13 @@ bitwise operations just described. They are: ``lshift(VAL, COUNT)'' Return the value of VAL, shifted left by COUNT bits. -``or(V1, V2' [`,' ...]`)'' +``or('V1`,' V2 [`,' ...]`)'' Return the bitwise OR of the arguments. There must be at least two. ``rshift(VAL, COUNT)'' Return the value of VAL, shifted right by COUNT bits. -``xor(V1, V2' [`,' ...]`)'' +``xor('V1`,' V2 [`,' ...]`)'' Return the bitwise XOR of the arguments. There must be at least two. @@ -13162,7 +13271,7 @@ Nondecimal-numbers::), and then demonstrates the results of the (1) This example shows that 0's come in on the left side. For `gawk', this is always true, but in some languages, it's possible to -have the left side fill with 1's. Caveat emptor. +have the left side fill with 1's. File: gawk.info, Node: Type Functions, Next: I18N Functions, Prev: Bitwise Functions, Up: Built-in @@ -13172,7 +13281,7 @@ File: gawk.info, Node: Type Functions, Next: I18N Functions, Prev: Bitwise Fu `gawk' provides a single function that lets you distinguish an array from a scalar variable. This is necessary for writing code that -traverses every element of an array of arrays. (*note Arrays of +traverses every element of an array of arrays (*note Arrays of Arrays::). `isarray(X)' @@ -13184,12 +13293,12 @@ itself an array or not. The second is inside the body of a user-defined function (not discussed yet; *note User-defined::), to test if a parameter is an array or not. - Note, however, that 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' will end up turning -it into a scalar. + 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. File: gawk.info, Node: I18N Functions, Prev: Type Functions, Up: Built-in @@ -13253,7 +13362,10 @@ File: gawk.info, Node: Definition Syntax, Next: Function Example, Up: User-de 9.2.1 Function Definition Syntax -------------------------------- -Definitions of functions can appear anywhere between the rules of an + It's entirely fair to say that the `awk' syntax for local variable + definitions is appallingly awful. -- Brian Kernighan + + Definitions of functions can appear anywhere between the rules of an `awk' program. Thus, the general form of an `awk' program is extended to include sequences of rules _and_ user-defined function definitions. There is no need to put the definition of a function before all uses of @@ -13269,9 +13381,10 @@ starting to execute any of it. Here, NAME is the name of the function to define. A valid function name is like a valid variable name: a sequence of letters, digits, and -underscores that doesn't start with a digit. Within a single `awk' -program, any particular name can only be used as a variable, array, or -function. +underscores that doesn't start with a digit. Here too, only the 52 +upper- and lowercase English letters may be used in a function name. +Within a single `awk' program, any particular name can only be used as +a variable, array, or function. PARAMETER-LIST is an optional list of the function's arguments and local variable names, separated by commas. When the function is called, @@ -13281,9 +13394,9 @@ call. A function cannot have two parameters with the same name, nor may it have a parameter with the same name as the function itself. In addition, according to the POSIX standard, function parameters cannot -have the same name as one of the special built-in variables (*note +have the same name as one of the special predefined variables (*note Built-in Variables::). Not all versions of `awk' enforce this -restriction.) +restriction. Local variables act like the empty string if referenced where a string value is required, and like zero if referenced where a numeric @@ -13396,7 +13509,7 @@ extra whitespace signifies the start of the local variable list): function delarray(a, i) { for (i in a) - delete a[i] + delete a[i] } When working with arrays, it is often necessary to delete all the @@ -13404,8 +13517,8 @@ elements in an array and start over with a new list of elements (*note Delete::). Instead of having to repeat this loop everywhere that you need to clear out an array, your program can just call `delarray'. (This guarantees portability. The use of `delete ARRAY' to delete the -contents of an entire array is a recent(1) addition to the POSIX -standard.) +contents of an entire array is a relatively recent(1) addition to the +POSIX standard.) The following is an example of a recursive function. It takes a string as an input parameter and returns the string in backwards order. @@ -13428,7 +13541,7 @@ way: > gawk -e '{ print rev($0) }' -f rev.awk -| !cinaP t'noD - The C `ctime()' function takes a timestamp and returns it in a + The C `ctime()' function takes a timestamp and returns it as a string, formatted in a well-known fashion. The following example uses the built-in `strftime()' function (*note Time Functions::) to create an `awk' version of `ctime()': @@ -13439,12 +13552,18 @@ an `awk' version of `ctime()': function ctime(ts, format) { - format = PROCINFO["strftime"] + format = "%a %b %e %H:%M:%S %Z %Y" + if (ts == 0) ts = systime() # use current time as default return strftime(format, ts) } + 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"]'. + ---------- Footnotes ---------- (1) Late in 2012. @@ -13825,7 +13944,7 @@ File: gawk.info, Node: Indirect Calls, Next: Functions Summary, Prev: User-de 9.3 Indirect Function Calls =========================== -This section describes a `gawk'-specific extension. +This section describes an advanced, `gawk'-specific extension. Often, you may wish to defer the choice of function to call until runtime. For example, you may have different kinds of records, each of @@ -13864,7 +13983,7 @@ your test scores: This style of programming works, but can be awkward. With "indirect" function calls, you tell `gawk' to use the _value_ of a variable as the -name of the function to call. +_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, @@ -13906,7 +14025,6 @@ using indirect function calls. Otherwise they perform the expected computations and are not unusual. # For each record, print the class name and the requested statistics - { class_name = $1 gsub(/_/, " ", class_name) # Replace _ with spaces @@ -13987,7 +14105,7 @@ mechanism allows you to sort arbitrary data in an arbitrary fashion. # quicksort_swap --- helper function for quicksort, should really be inline - function quicksort_swap(data, i, j, temp) + function quicksort_swap(data, i, j, temp) { temp = data[i] data[i] = data[j] @@ -14090,14 +14208,71 @@ names of the two comparison functions: -| sort: <87.1 93.4 95.6 100.0> -| rsort: <100.0 95.6 93.4 87.1> + Another example where indirect functions calls are useful can be +found in processing arrays. *note Walking Arrays::, presented a simple +function for "walking" an array of arrays. That function simply +printed the name and value of each scalar array element. However, it is +easy to generalize that function, by passing in the name of a function +to call when walking an array. The modified function looks like this: + + function process_array(arr, name, process, do_arrays, i, new_name) + { + for (i in arr) { + new_name = (name "[" i "]") + if (isarray(arr[i])) { + if (do_arrays) + @process(new_name, arr[i]) + process_array(arr[i], new_name, process, do_arrays) + } else + @process(new_name, arr[i]) + } + } + + The arguments are as follows: + +`arr' + The array. + +`name' + The name of the array (a string). + +`process' + The name of the function to call. + +`do_arrays' + If this is true, the function can handle elements that are + subarrays. + + If subarrays are to be processed, that is done before walking them +further. + + When run with the following scaffolding, the function produces the +same results as does the earlier `walk_array()' function: + + BEGIN { + a[1] = 1 + a[2][1] = 21 + a[2][2] = 22 + a[3] = 3 + a[4][1][1] = 411 + a[4][2] = 42 + + process_array(a, "a", "do_print", 0) + } + + function do_print(name, element) + { + printf "%s = %s\n", name, element + } + Remember that you must supply a leading `@' in front of an indirect function call. - Unfortunately, indirect function calls cannot be used with the -built-in functions. However, you can generally write "wrapper" -functions which call the built-in ones, and those can be called -indirectly. (Other than, perhaps, the mathematical functions, there is -not a lot of reason to try to call the built-in functions indirectly.) + Starting with version 4.1.2 of `gawk', indirect function calls may +also be used with built-in functions and with extension functions +(*note Dynamic Extensions::). The only thing you cannot do is pass a +regular expression constant to a built-in function through an indirect +function call.(1) `gawk' does its best to make indirect function calls efficient. For example, in the following case: @@ -14105,7 +14280,12 @@ example, in the following case: for (i = 1; i <= n; i++) @the_func() -`gawk' will look up the actual function to call only once. +`gawk' looks up the actual function to call only once. + + ---------- Footnotes ---------- + + (1) This may change in a future version; recheck the documentation +that comes with your version of `gawk' to see if it has. File: gawk.info, Node: Functions Summary, Prev: Indirect Calls, Up: Functions @@ -14117,11 +14297,12 @@ File: gawk.info, Node: Functions Summary, Prev: Indirect Calls, Up: Functions functions. * POSIX `awk' provides three kinds of built-in functions: numeric, - string, and I/O. `gawk' provides functions that work with values - representing time, do bit manipulation, sort arrays, and - internationalize and localize programs. `gawk' also provides - several extensions to some of standard functions, typically in the - form of additional arguments. + 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 + localize programs. `gawk' also provides several extensions to + some of standard functions, typically in the form of additional + arguments. * Functions accept zero or more arguments and return a value. The expressions that provide the argument values are completely @@ -14142,7 +14323,9 @@ File: gawk.info, Node: Functions Summary, Prev: Indirect Calls, Up: Functions * User-defined functions may call other user-defined (and built-in) functions and may call themselves recursively. Function parameters - "hide" any global variables of the same names. + "hide" any global variables of the same names. You cannot use the + name of a reserved variable (such as `ARGC') as the name of a + parameter in user-defined functions. * Scalar values are passed to user-defined functions by value. Array parameters are passed by reference; any changes made by the @@ -14158,10 +14341,9 @@ File: gawk.info, Node: Functions Summary, Prev: Indirect Calls, Up: Functions either scalar or array. * `gawk' provides indirect function calls using a special syntax. - By setting a variable to the name of a user-defined function, you - can determine at runtime what function will be called at that - point in the program. This is equivalent to function pointers in C - and C++. + By setting a variable to the name of a function, you can determine + at runtime what function will be called at that point in the + program. This is equivalent to function pointers in C and C++. @@ -14241,7 +14423,7 @@ for different implementations of `awk' is pretty straightforward. * Group Functions:: Functions for getting group information. * Walking Arrays:: A function to walk arrays of arrays. * Library Functions Summary:: Summary of library functions. -* Library exercises:: Exercises. +* Library Exercises:: Exercises. ---------- Footnotes ---------- @@ -14295,7 +14477,7 @@ to start that variable's name with a capital letter--for example, `getopt()''s `Opterr' and `Optind' variables (*note Getopt Function::). The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the -variable is not one of `awk''s built-in variables, such as `FS'. +variable is not one of `awk''s predefined variables, such as `FS'. It is also important that _all_ variables in library functions that do not need to save state are, in fact, declared local.(2) If this is @@ -14305,8 +14487,9 @@ program, leading to bugs that are very difficult to track down: function lib_func(x, y, l1, l2) { ... - USE VARIABLE some_var # some_var should be local - ... # but is not by oversight + # some_var should be local but by oversight is not + USE VARIABLE some_var + ... } A different convention, common in the Tcl community, is to use a @@ -14355,6 +14538,7 @@ programming use. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the shell. File: gawk.info, Node: Strtonum Function, Next: Assert Function, Up: General Functions @@ -14376,8 +14560,9 @@ versions of `awk': ret = 0 for (i = 1; i <= n; i++) { c = substr(str, i, 1) - if ((k = index("01234567", c)) > 0) - k-- # adjust for 1-basing in awk + # index() returns 0 if c not in string, + # includes c == "0" + k = index("1234567", c) ret = ret * 8 + k } @@ -14389,6 +14574,8 @@ versions of `awk': for (i = 1; i <= n; i++) { c = substr(str, i, 1) c = tolower(c) + # index() returns 0 if c not in string, + # includes c == "0" k = index("123456789abcdef", c) ret = ret * 16 + k @@ -14411,7 +14598,7 @@ versions of `awk': # a[5] = "123.45" # a[6] = "1.e3" # a[7] = "1.32" - # a[7] = "1.32E2" + # a[8] = "1.32E2" # # for (i = 1; i in a; i++) # print a[i], strtonum(a[i]), mystrtonum(a[i]) @@ -14420,9 +14607,11 @@ versions of `awk': The function first looks for C-style octal numbers (base 8). If the input string matches a regular expression describing octal numbers, then `mystrtonum()' loops through each character in the string. It -sets `k' to the index in `"01234567"' of the current octal digit. -Since the return value is one-based, the `k--' adjusts `k' so it can be -used in computing the return value. +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. Similar logic applies to the code that checks for and converts a hexadecimal value, which starts with `0x' or `0X'. The use of @@ -14448,7 +14637,7 @@ condition or set of conditions is true. Before proceeding with a particular computation, you make a statement about what you believe to be the case. Such a statement is known as an "assertion". The C language provides an `<assert.h>' header file and corresponding -`assert()' macro that the programmer can use to make assertions. If an +`assert()' macro that a programmer can use to make assertions. If an assertion fails, the `assert()' macro arranges to print a diagnostic message describing the condition that should have been true but was not, and then it kills the program. In C, using `assert()' looks this: @@ -14669,8 +14858,7 @@ worrying about: } #### test code #### - # BEGIN \ - # { + # BEGIN { # for (;;) { # printf("enter a character: ") # if (getline var <= 0) @@ -14789,7 +14977,7 @@ current time formatted in the same way as the `date' utility: now = systime() # return date(1)-style output - ret = strftime(PROCINFO["strftime"], now) + ret = strftime("%a %b %e %H:%M:%S %Z %Y", now) # clear out target array delete time @@ -14826,7 +15014,7 @@ the `getlocaltime()' function would have allowed the user to supply an optional timestamp value to use instead of the current time. -File: gawk.info, Node: Readfile Function, Prev: Getlocaltime Function, Up: General Functions +File: gawk.info, Node: Readfile Function, Next: Shell Quoting, Prev: Getlocaltime Function, Up: General Functions 10.2.8 Reading A Whole File At Once ----------------------------------- @@ -14885,6 +15073,61 @@ string. Thus calling code may use something like: This tests the result to see if it is empty or not. An equivalent test would be `contents == ""'. + *Note Extension Sample Readfile::, for an extension function that +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 +------------------------------------------- + +Michael Brennan offers the following programming pattern, which he uses +frequently: + + #! /bin/sh + + awkp=' + ... + ' + + INPUT_PROGRAM | awk "$awkp" | /bin/sh + + For example, a program of his named `flac-edit' has this form: + + $ flac-edit -song="Whoope! That's Great" file.flac + + It generates the following output, which is to be piped to the shell +(`/bin/sh'): + + chmod +w file.flac + metaflac --remove-tag=TITLE file.flac + LANG=en_US.88591 metaflac --set-tag=TITLE='Whoope! That'"'"'s Great' file.flac + chmod -w file.flac + + 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 `"\"'\""'. + + # shell_quote --- quote an argument for passing to the shell + + function shell_quote(s, # parameter + SINGLE, QSINGLE, i, X, n, ret) # locals + { + if (s == "") + return "\"\"" + + SINGLE = "\x27" # single quote + QSINGLE = "\"\x27\"" + n = split(s, X, SINGLE) + + ret = SINGLE X[1] SINGLE + for (i = 2; i <= n; i++) + ret = ret QSINGLE SINGLE X[i] SINGLE + + return ret + } + File: gawk.info, Node: Data File Management, Next: Getopt Function, Prev: General Functions, Up: Library Functions @@ -14934,15 +15177,14 @@ does so _portably_; this works with any implementation of `awk': # that each take the name of the file being started or # finished, respectively. - FILENAME != _oldfilename \ - { + FILENAME != _oldfilename { if (_oldfilename != "") endfile(_oldfilename) _oldfilename = FILENAME beginfile(FILENAME) } - END { endfile(FILENAME) } + END { endfile(FILENAME) } This file must be loaded before the user's "main" program, so that the rule it supplies is executed first. @@ -14980,7 +15222,7 @@ solves the problem: beginfile(FILENAME) } - END { endfile(_filename_) } + END { endfile(_filename_) } *note Wc Program::, shows how this library function can be used and how it simplifies writing the main program. @@ -15033,15 +15275,12 @@ over with it from the top. For lack of a better name, we'll call it nextfile } - This code relies on the `ARGIND' variable (*note Auto-set::), which -is specific to `gawk'. If you are not using `gawk', you can use ideas -presented in *note Filetrans Function::, to either update `ARGIND' on -your own or modify this code as appropriate. - - The `rewind()' function 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!) + The `rewind()' function relies on the `ARGIND' variable (*note +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!) File: gawk.info, Node: File Checking, Next: Empty Files, Prev: Rewind Function, Up: Data File Management @@ -15058,7 +15297,7 @@ following program to your `awk' program: BEGIN { for (i = 1; i < ARGC; i++) { - if (ARGV[i] ~ /^[[:alpha:]_][[:alnum:]_]*=.*/ \ + if (ARGV[i] ~ /^[a-zA-Z_][a-zA-Z0-9_]*=.*/ \ || ARGV[i] == "-" || ARGV[i] == "/dev/stdin") continue # assignment or standard input else if ((getline junk < ARGV[i]) < 0) # unreadable @@ -15072,6 +15311,10 @@ following program to your `awk' program: element from `ARGV' with `delete' skips the file (since 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. + ---------- Footnotes ---------- (1) The `BEGINFILE' special pattern (*note BEGINFILE/ENDFILE::) @@ -15150,7 +15393,7 @@ programming with a library file does the trick: function disable_assigns(argc, argv, i) { for (i = 1; i < argc; i++) - if (argv[i] ~ /^[[:alpha:]_][[:alnum:]_]*=.*/) + if (argv[i] ~ /^[a-zA-Z_][a-zA-Z0-9_]*=.*/) argv[i] = ("./" argv[i]) } @@ -15338,8 +15581,7 @@ not an option, and it ends option processing. Continuing on: i = index(options, thisopt) if (i == 0) { if (Opterr) - printf("%c -- invalid option\n", - thisopt) > "/dev/stderr" + printf("%c -- invalid option\n", thisopt) > "/dev/stderr" if (_opti >= length(argv[Optind])) { Optind++ _opti = 0 @@ -15451,10 +15693,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, it is the responsibility of the - user level code to 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. + 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::). Several of the sample programs presented in *note Sample Programs::, use `getopt()' to process their arguments. @@ -15613,8 +15859,8 @@ corresponding to the C functions of the same names: routine, we have chosen to put it in `/usr/local/libexec/awk'; however, you might want it to be in a different directory on your system. - The function `_pw_init()' keeps three copies of the user information -in three associative arrays. The arrays are indexed by username + The function `_pw_init()' fills three copies of the user information +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. @@ -15624,13 +15870,10 @@ efficiency, since `_pw_init()' needs to be called only once. 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. - - The `using_fw' variable checks `PROCINFO["FS"]', which is -`"FIELDWIDTHS"' if field splitting is being done with `FIELDWIDTHS'. -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. +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. The code that checks for using `FPAT', using `using_fpat' and `PROCINFO["FS"]', is similar. @@ -15793,8 +16036,7 @@ the same names: # group.awk --- functions for dealing with the group file - BEGIN \ - { + BEGIN { # Change to suit your system _gr_awklib = "/usr/local/libexec/awk/" } @@ -15827,8 +16069,7 @@ the same names: n = split($4, a, "[ \t]*,[ \t]*") for (i = 1; i <= n; i++) if (a[i] in _gr_groupsbyuser) - _gr_groupsbyuser[a[i]] = \ - _gr_groupsbyuser[a[i]] " " $1 + _gr_groupsbyuser[a[i]] = gr_groupsbyuser[a[i]] " " $1 else _gr_groupsbyuser[a[i]] = $1 @@ -15990,22 +16231,22 @@ value. Here is a main program to demonstrate: When run, the program produces the following output: $ gawk -f walk_array.awk - -| a[4][1][1] = 411 - -| a[4][2] = 42 -| a[1] = 1 -| a[2][1] = 21 -| a[2][2] = 22 -| a[3] = 3 + -| a[4][1][1] = 411 + -| a[4][2] = 42 -File: gawk.info, Node: Library Functions Summary, Next: Library exercises, Prev: Walking Arrays, Up: Library Functions +File: gawk.info, Node: Library Functions Summary, Next: Library Exercises, Prev: Walking Arrays, Up: Library Functions 10.8 Summary ============ * Reading programs is an excellent way to learn Good Programming. - The functions provided in this major node and the next are intended - to serve that purpose. + The functions and programs provided in this major node and the next + are intended to serve that purpose. * When writing general-purpose library functions, put some thought into how to name any global variables so that they won't conflict @@ -16035,7 +16276,7 @@ File: gawk.info, Node: Library Functions Summary, Next: Library exercises, Pr -File: gawk.info, Node: Library exercises, Prev: Library Functions Summary, Up: Library Functions +File: gawk.info, Node: Library Exercises, Prev: Library Functions Summary, Up: Library Functions 10.9 Exercises ============== @@ -16196,18 +16437,13 @@ supplied: # # Requires getopt() and join() library functions - function usage( e1, e2) + function usage() { - e1 = "usage: cut [-f list] [-d c] [-s] [files...]" - e2 = "usage: cut [-c list] [files...]" - print e1 > "/dev/stderr" - print e2 > "/dev/stderr" + print("usage: cut [-f list] [-d c] [-s] [files...]") > "/dev/stderr" + print("usage: cut [-c list] [files...]") > "/dev/stderr" exit 1 } -The variables `e1' and `e2' are used so that the function fits nicely -on the screen. - Next comes a `BEGIN' rule that parses the command-line options. It sets `FS' to a single TAB character, because that is `cut''s default field separator. The rule then sets the output field separator to be the @@ -16217,8 +16453,7 @@ through the command-line options. Exactly one of the variables should be done by fields or by characters, respectively. When cutting by characters, the output field separator is set to the null string: - BEGIN \ - { + BEGIN { FS = "\t" # default OFS = FS while ((c = getopt(ARGC, ARGV, "sf:c:d:")) != -1) { @@ -16451,7 +16686,7 @@ Function::). The program begins with a descriptive comment and then a `BEGIN' rule that processes the command-line arguments with `getopt()'. The `-i' (ignore case) option is particularly easy with `gawk'; we just use the -`IGNORECASE' built-in variable (*note Built-in Variables::): +`IGNORECASE' predefined variable (*note Built-in Variables::): # egrep.awk --- simulate egrep in awk # @@ -16603,32 +16838,20 @@ line is printed, with a leading file name and colon if necessary: The `END' rule takes care of producing the correct exit status. If there are no matches, the exit status is one; otherwise it is zero: - END \ - { + END { exit (total == 0) } The `usage()' function prints a usage message in case of invalid options, and then exits: - function usage( e) + function usage() { - e = "Usage: egrep [-csvil] [-e pat] [files ...]" - e = e "\n\tegrep [-csvil] pat [files ...]" - print e > "/dev/stderr" + print("Usage: egrep [-csvil] [-e pat] [files ...]") > "/dev/stderr" + print("\n\tegrep [-csvil] pat [files ...]") > "/dev/stderr" exit 1 } - The variable `e' is used so that the function fits nicely on the -printed page. - - Just a note on programming style: you may have noticed that the `END' -rule uses backslash continuation, with the open brace on a line by -itself. This is so that it more closely resembles the way functions -are written. Many of the examples in this major node use this style. -You can decide for yourself if you like writing your `BEGIN' and `END' -rules this way or not. - ---------- Footnotes ---------- (1) It also introduces a subtle bug; if a match happens, we output @@ -16671,8 +16894,7 @@ and the group numbers: # uid=12(foo) euid=34(bar) gid=3(baz) \ # egid=5(blat) groups=9(nine),2(two),1(one) - BEGIN \ - { + BEGIN { uid = PROCINFO["uid"] euid = PROCINFO["euid"] gid = PROCINFO["gid"] @@ -16680,26 +16902,22 @@ and the group numbers: printf("uid=%d", uid) pw = getpwuid(uid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (euid != uid) { printf(" euid=%d", euid) pw = getpwuid(euid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) } printf(" gid=%d", gid) pw = getgrgid(gid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (egid != gid) { printf(" egid=%d", egid) pw = getgrgid(egid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) } for (i = 1; ("group" i) in PROCINFO; i++) { @@ -16708,8 +16926,7 @@ and the group numbers: group = PROCINFO["group" i] printf("%d", group) pw = getgrgid(group) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (("group" (i+1)) in PROCINFO) printf(",") } @@ -16719,8 +16936,10 @@ and the group numbers: function pr_first_field(str, a) { - split(str, a, ":") - printf("(%s)", a[1]) + if (str != "") { + split(str, a, ":") + printf("(%s)", a[1]) + } } The test in the `for' loop is worth noting. Any supplementary @@ -16738,8 +16957,9 @@ then the condition is false the first time it's tested, and the loop body never executes. The `pr_first_field()' function simply isolates out some code that -is used repeatedly, making the whole program slightly shorter and -cleaner. +is used repeatedly, making the whole program shorter and cleaner. In +particular, moving the check for the empty string into this function +saves several lines of code. File: gawk.info, Node: Split Program, Next: Tee Program, Prev: Id Program, Up: Clones @@ -16830,15 +17050,12 @@ moves to the next letter in the alphabet and `s2' starts over again at The `usage()' function simply prints an error message and exits: - function usage( e) + function usage() { - e = "usage: split [-num] [file] [outname]" - print e > "/dev/stderr" + print("usage: split [-num] [file] [outname]") > "/dev/stderr" exit 1 } -The variable `e' is used so that the function fits nicely on the screen. - This program is a bit sloppy; it relies on `awk' to automatically close the last file instead of doing it in an `END' rule. It also assumes that letters are contiguous in the character set, which isn't @@ -16880,8 +17097,7 @@ input by setting `ARGV[1]' to `"-"' and `ARGC' to two: # Copy standard input to all named output files. # Append content if -a option is supplied. # - BEGIN \ - { + BEGIN { for (i = 1; i < ARGC; i++) copy[i] = ARGV[i] @@ -16931,8 +17147,7 @@ N input records and M output files, the first method only executes N Finally, the `END' rule cleans up by closing all the output files: - END \ - { + END { for (i in copy) close(copy[i]) } @@ -16953,10 +17168,10 @@ usage is as follows: The options for `uniq' are: `-d' - Print only repeated lines. + Print only repeated (duplicated) lines. `-u' - Print only nonrepeated lines. + Print only nonrepeated (unique) lines. `-c' Count lines. This option overrides `-d' and `-u'. Both repeated @@ -17006,10 +17221,9 @@ standard output, `/dev/stdout': # # Requires getopt() and join() library functions - function usage( e) + function usage() { - e = "Usage: uniq [-udc [-n]] [+n] [ in [ out ]]" - print e > "/dev/stderr" + print("Usage: uniq [-udc [-n]] [+n] [ in [ out ]]") > "/dev/stderr" exit 1 } @@ -17019,8 +17233,7 @@ standard output, `/dev/stdout': # -n skip n fields # +n skip n characters, skip fields first - BEGIN \ - { + BEGIN { count = 1 outputfile = "/dev/stdout" opts = "udc0:1:2:3:4:5:6:7:8:9:" @@ -17032,7 +17245,7 @@ standard output, `/dev/stdout': else if (c == "c") do_count++ else if (index("0123456789", c) != 0) { - # getopt requires args to options + # getopt() requires args to options # this messes us up for things like -5 if (Optarg ~ /^[[:digit:]]+$/) fcount = (c Optarg) + 0 @@ -17064,16 +17277,18 @@ standard output, `/dev/stdout': The following function, `are_equal()', compares the current line, `$0', to the previous line, `last'. It handles skipping fields and characters. If no field count and no character count are specified, -`are_equal()' simply returns one or zero depending upon the result of a -simple string comparison of `last' and `$0'. Otherwise, things get more -complicated. If fields have to be skipped, each line is broken into an -array using `split()' (*note String Functions::); the desired fields -are then joined back into a line using `join()'. The joined lines are -stored in `clast' and `cline'. If no fields are skipped, `clast' and -`cline' are set to `last' and `$0', respectively. Finally, if -characters are skipped, `substr()' is used to strip off the leading -`charcount' characters in `clast' and `cline'. The two strings are -then compared and `are_equal()' returns the result: +`are_equal()' returns one or zero depending upon the result of a simple +string comparison of `last' and `$0'. + + Otherwise, things get more complicated. If fields have to be +skipped, each line is broken into an array using `split()' (*note +String Functions::); the desired fields are then joined back into a line +using `join()'. The joined lines are stored in `clast' and `cline'. +If no fields are skipped, `clast' and `cline' are set to `last' and +`$0', respectively. Finally, if characters are skipped, `substr()' is +used to strip off the leading `charcount' characters in `clast' and +`cline'. The two strings are then compared and `are_equal()' returns +the result: function are_equal( n, m, clast, cline, alast, aline) { @@ -17169,8 +17384,8 @@ one or more input files. Its usage is as follows: If no files are specified on the command line, `wc' reads its standard input. If there are multiple files, it also prints total -counts for all the files. The options and their meanings are shown in -the following list: +counts for all the files. The options and their meanings are as +follows: `-l' Count only lines. @@ -17408,8 +17623,7 @@ Statement::), but the processing could be done with a series of # Requires getlocaltime() library function # usage: alarm time [ "message" [ count [ delay ] ] ] - BEGIN \ - { + BEGIN { # Initial argument sanity checking usage1 = "usage: alarm time ['message' [count [delay]]]" usage2 = sprintf("\t(%s) time ::= hh:mm", ARGV[1]) @@ -17527,17 +17741,17 @@ there are more characters in the "from" list than in the "to" list, the last character of the "to" list is used for the remaining characters in the "from" list. - Once upon a time, a user proposed that a transliteration function -should be added to `gawk'. The following program was written to prove -that character transliteration could be done with a user-level -function. This program is not as complete as the system `tr' utility -but it does most of the job. + Once upon a time, a user proposed adding a transliteration function +to `gawk'. The following program was written to prove that character +transliteration could be done with a user-level function. This program +is not as complete as the system `tr' utility but it does most of the +job. - The `translate' program demonstrates one of the few weaknesses of -standard `awk': dealing with individual characters is very painful, -requiring repeated use of the `substr()', `index()', and `gsub()' -built-in functions (*note String Functions::).(2) There are two -functions. The first, `stranslate()', takes three arguments: + The `translate' program was written long before `gawk' acquired the +ability to split each character in a string into separate array +elements. Thus, it makes repeated use of the `substr()', `index()', +and `gsub()' built-in functions (*note String Functions::). There are +two functions. The first, `stranslate()', takes three arguments: `from' A list of characters from which to translate. @@ -17554,10 +17768,10 @@ simple loop goes through `from', one character at a time. For each character in `from', if the character appears in `target', it is replaced with the corresponding `to' character. - The `translate()' function simply calls `stranslate()' using `$0' as -the target. The main program sets two global variables, `FROM' and -`TO', from the command line, and then changes `ARGV' so that `awk' -reads from the standard input. + The `translate()' function calls `stranslate()' using `$0' as the +target. The main program sets two global variables, `FROM' and `TO', +from the command line, and then changes `ARGV' so that `awk' reads from +the standard input. Finally, the processing rule simply calls `translate()' for each record: @@ -17623,6 +17837,10 @@ array only once, in a `BEGIN' rule. However, this assumes that the "from" and "to" lists will never change throughout the lifetime of the program. + Another obvious improvement is to enable the use of ranges, such as +`a-z', as allowed by the `tr' utility. Look at the code for `cut.awk' +(*note Cut Program::) for inspiration. + ---------- Footnotes ---------- (1) On some older systems, including Solaris, the system version of @@ -17630,9 +17848,6 @@ program. enclosed in square brackets (`[a-z]') and quoted, to prevent the shell from attempting a file name expansion. This is not a feature. - (2) This program was written before `gawk' acquired the ability to -split each character in a string into separate array elements. - File: gawk.info, Node: Labels Program, Next: Word Sorting, Prev: Translate Program, Up: Miscellaneous Programs @@ -17658,12 +17873,12 @@ splits records at blank lines (*note Records::). It sets `MAXLINES' to Most of the work is done in the `printpage()' function. The label lines are stored sequentially in the `line' array. But they have to print horizontally; `line[1]' next to `line[6]', `line[2]' next to -`line[7]', and so on. Two loops are used to accomplish this. The -outer loop, controlled by `i', steps through every 10 lines of data; -this is each row of labels. The inner loop, controlled by `j', goes -through the lines within the row. As `j' goes from 0 to 4, `i+j' is -the `j'-th line in the row, and `i+j+5' is the entry next to it. The -output ends up looking something like this: +`line[7]', and so on. Two loops accomplish this. The outer loop, +controlled by `i', steps through every 10 lines of data; this is each +row of labels. The inner loop, controlled by `j', goes through the +lines within the row. As `j' goes from 0 to 4, `i+j' is the `j'-th +line in the row, and `i+j+5' is the entry next to it. The output ends +up looking something like this: line 1 line 6 line 2 line 7 @@ -17730,8 +17945,7 @@ not have been an even multiple of 20 labels in the data: Count++ } - END \ - { + END { printpage() } @@ -17755,7 +17969,7 @@ a useful format. At first glance, a program like this would seem to do the job: - # Print list of word frequencies + # wordfreq-first-try.awk --- print list of word frequencies { for (i = 1; i <= NF; i++) @@ -17909,9 +18123,9 @@ Texinfo input file into separate files. This Info file is written in Texinfo (http://www.gnu.org/software/texinfo/), the GNU project's document formatting language. A single Texinfo source file can be used to -produce both printed and online documentation. The Texinfo language is -described fully, starting with *note (Texinfo)Top:: -texinfo,Texinfo--The GNU Documentation Format. +produce both printed documentation, with TeX, and online documentation. +(The Texinfo language is described fully, starting with *note +(Texinfo)Top:: texinfo,Texinfo--The GNU Documentation Format.) For our purposes, it is enough to know three things about Texinfo input files: @@ -17973,13 +18187,11 @@ upper- and lowercase letters in the directives won't matter. given (`NF' is at least three) and also checking that the command exits with a zero exit status, signifying OK: - # extract.awk --- extract files and run programs - # from texinfo files + # extract.awk --- extract files and run programs from texinfo files BEGIN { IGNORECASE = 1 } - /^@c(omment)?[ \t]+system/ \ - { + /^@c(omment)?[ \t]+system/ { if (NF < 3) { e = ("extract: " FILENAME ":" FNR) e = (e ": badly formed `system' line") @@ -18027,8 +18239,7 @@ with the value of `SUBSEP' (*note Multidimensional::), to rejoin the pieces back into a single line. That line is then printed to the output file: - /^@c(omment)?[ \t]+file/ \ - { + /^@c(omment)?[ \t]+file/ { if (NF != 3) { e = ("extract: " FILENAME ":" FNR ": badly formed `file' line") print e > "/dev/stderr" @@ -18082,7 +18293,7 @@ closing the open file: function unexpected_eof() { printf("extract: %s:%d: unexpected EOF or error\n", - FILENAME, FNR) > "/dev/stderr" + FILENAME, FNR) > "/dev/stderr" exit 1 } @@ -18104,7 +18315,7 @@ 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: - command1 < orig.data | sed 's/old/new/g' | command2 > result + 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 @@ -18291,8 +18502,8 @@ arguments are supplied, then the first nonoption argument should be the `awk' program. If there are no command-line arguments left, `igawk' prints an error message and exits. Otherwise, the first argument is appended to `program'. In any case, after the arguments have been -processed, `program' contains the complete text of the original `awk' -program. +processed, the shell variable `program' contains the complete text of +the original `awk' program. The program is as follows: @@ -18538,7 +18749,7 @@ and it is frequently easier to do certain kinds of string and argument manipulation using the shell than it is in `awk'. Finally, `igawk' shows that it is not always necessary to add new -features to a program; they can often be layered on top. +features to a program; they can often be layered on top.(3) ---------- Footnotes ---------- @@ -18547,7 +18758,10 @@ book. We provide some minimal explanations, but see a good shell programming book if you wish to understand things in more depth. (2) On some very old versions of `awk', the test `getline junk < t' -can loop forever if the file exists but is empty. Caveat emptor. +can loop forever if the file exists but is empty. + + (3) `gawk' does `@include' processing itself in order to support the +use of `awk' programs as Web CGI scripts. File: gawk.info, Node: Anagram Program, Next: Signature Program, Prev: Igawk Program, Up: Miscellaneous Programs @@ -18560,12 +18774,11 @@ 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"). - An elegant algorithm is presented in Column 2, Problem C of Jon -Bentley's `Programming Pearls', second edition. 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. + 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 @@ -18674,9 +18887,9 @@ File: gawk.info, Node: Programs Summary, Next: Programs Exercises, Prev: Misc 11.4 Summary ============ - * The functions provided in this major node and the previous one - continue on the theme that reading programs is an excellent way to - learn Good Programming. + * The programs provided in this major node continue on the theme + that reading programs is an excellent way to learn Good + Programming. * Using `#!' to make `awk' programs directly runnable makes them easier to use. Otherwise, invoke the program using `awk -f ...'. @@ -18705,7 +18918,7 @@ File: gawk.info, Node: Programs Exercises, Prev: Programs Summary, Up: Sample ============== 1. Rewrite `cut.awk' (*note Cut Program::) using `split()' with `""' - as the seperator. + as the separator. 2. In *note Egrep Program::, we mentioned that `egrep -i' could be simulated in versions of `awk' without `IGNORECASE' by using @@ -18718,14 +18931,21 @@ File: gawk.info, Node: Programs Exercises, Prev: Programs Summary, Up: Sample Program::) to accept the same arguments and perform in the same way. - 4. The `split.awk' program (*note Split Program::) uses the `chr()' - and `ord()' functions to move through the letters of the alphabet. - Modify the program to instead use only the `awk' built-in - functions, such as `index()' and `substr()'. - - 5. The `split.awk' program (*note Split Program::) assumes that + 4. The `split.awk' program (*note Split Program::) assumes that letters are contiguous in the character set, which isn't true for - EBCDIC systems. Fix this problem. + EBCDIC systems. Fix this problem. (Hint: Consider a different + way to work through the alphabet, without relying on `ord()' and + `chr()'.) + + 5. In `uniq.awk' (*note Uniq Program::, the logic for choosing which + lines to print represents a "state machine", which is "a device + that can be in one of a set number of stable conditions depending + on its previous condition and on the present values of its + inputs."(1) 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 suggestion. 6. Why can't the `wc.awk' program (*note Wc Program::) just use the value of `FNR' in `endfile()'? Hint: Examine the code in *note @@ -18788,6 +19008,11 @@ File: gawk.info, Node: Programs Exercises, Prev: Programs Summary, Up: Sample of the external `sort' utility. + ---------- Footnotes ---------- + + (1) This is the definition returned from entering `define: state +machine' into Google. + File: gawk.info, Node: Advanced Features, Next: Internationalization, Prev: Sample Programs, Up: Top @@ -18841,11 +19066,10 @@ File: gawk.info, Node: Nondecimal Data, Next: Array Sorting, Up: Advanced Fea =================================== If you run `gawk' with the `--non-decimal-data' option, you can have -nondecimal constants in your input data: +nondecimal values in your input data: $ echo 0123 123 0x123 | - > gawk --non-decimal-data '{ printf "%d, %d, %d\n", - > $1, $2, $3 }' + > gawk --non-decimal-data '{ printf "%d, %d, %d\n", $1, $2, $3 }' -| 83, 123, 291 For this feature to work, write your program so that `gawk' treats @@ -18876,6 +19100,8 @@ request it. programs easier to write and easier to read, and leads to less surprising results. + This option may disappear in a future version of `gawk'. + File: gawk.info, Node: Array Sorting, Next: Two-way I/O, Prev: Nondecimal Data, Up: Advanced Features @@ -18914,7 +19140,7 @@ pre-defined 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 -name. This lets you traverse an array based on any custom criterion. +name.(1) This lets you traverse an array based on any custom criterion. The array elements are ordered according to the return value of this function. The comparison function should be defined with at least four arguments: @@ -19029,7 +19255,7 @@ of the previous functions: according to login name. The following program sorts records by a specific field position and can be used for this purpose: - # sort.awk --- simple program to sort by field position + # passwd-sort.awk --- simple program to sort by field position # field position is specified by the global variable POS function cmp_field(i1, v1, i2, v2) @@ -19081,13 +19307,14 @@ seemingly ordered data: 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 -may change during the next loop traversal, if other elements are added -or removed from the array. One way to resolve ties when comparing -elements with otherwise equal values is to include the indices in the -comparison rules. Note that doing this may make the loop traversal -less efficient, so consider it only if necessary. The following -comparison functions force a deterministic order, and are based on the -fact that the (string) indices of two elements are never equal: +may change the next time the array is traversed, if other elements are +added or removed from the array. One way to resolve ties when +comparing elements with otherwise equal values is to include the +indices in the comparison rules. Note that doing this may make the +loop traversal less efficient, so consider it only if necessary. The +following comparison functions force a deterministic order, and are +based on the fact that the (string) indices of two elements are never +equal: function cmp_numeric(i1, v1, i2, v2) { @@ -19126,6 +19353,11 @@ array has been reported to add 15% to 20% overhead to the execution time of `awk' programs. For this reason, sorted array traversal is not the default. + ---------- Footnotes ---------- + + (1) This is why the predefined sorting orders start with an `@' +character, which cannot be part of an identifier. + File: gawk.info, Node: Array Sorting Functions, Prev: Controlling Array Traversal, Up: Array Sorting @@ -19212,7 +19444,7 @@ fill in the result array. Because `IGNORECASE' affects string comparisons, the value of `IGNORECASE' also affects sorting for both `asort()' and `asorti()'. Note also that the locale's sorting order does _not_ come into play; -comparisons are based on character values only.(1) Caveat Emptor. +comparisons are based on character values only.(1) ---------- Footnotes ---------- @@ -19338,7 +19570,7 @@ using regular pipes. (1) Michael Brennan suggests the use of `rand()' to generate unique file names. This is a valid point; nevertheless, temporary files remain -more difficult than two-way pipes. +more difficult to use than two-way pipes. (2) This is very different from the same operator in the C shell and in Bash. @@ -19349,16 +19581,16 @@ File: gawk.info, Node: TCP/IP Networking, Next: Profiling, Prev: Two-way I/O, 12.4 Using `gawk' for Network Programming ========================================= - `EMISTERED': + `EMRED': A host is a host from coast to coast, - and no-one can talk to host that's close, + and nobody talks to a host that's close, unless the host that isn't close - is busy hung or dead. + is busy, hung, or dead. -- Mike O'Brien (aka Mr. Protocol) - In addition to being able to open a two-way pipeline to a coprocess -on the same system (*note Two-way I/O::), it is possible to make a -two-way connection to another process on another system across an IP -network connection. +In addition to being able to open a two-way pipeline to a coprocess on +the same system (*note Two-way I/O::), it is possible to make a two-way +connection to another process on another system across an IP network +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 @@ -19377,8 +19609,8 @@ NET-TYPE PROTOCOL The protocol to use over IP. This must be either `tcp', or `udp', - for a TCP or UDP IP connection, respectively. The use of TCP is - recommended for most applications. + for a TCP or UDP IP connection, respectively. TCP should be used + for most applications. LOCAL-PORT The local TCP or UDP port number to use. Use a port number of `0' @@ -19404,10 +19636,10 @@ REMOTE-PORT Consider the following very simple example: BEGIN { - Service = "/inet/tcp/0/localhost/daytime" - Service |& getline - print $0 - close(Service) + Service = "/inet/tcp/0/localhost/daytime" + Service |& getline + print $0 + close(Service) } This program reads the current date and time from the local system's @@ -19482,9 +19714,9 @@ First, the `awk' program: profiler on this program and data. (This example also illustrates that `awk' programmers sometimes get up very early in the morning to work.) - # gawk profile, created Thu Feb 27 05:16:21 2014 + # gawk profile, created Mon Sep 29 05:16:21 2014 - # BEGIN block(s) + # BEGIN rule(s) BEGIN { 1 print "First BEGIN rule" @@ -19511,7 +19743,7 @@ profiler on this program and data. (This example also illustrates that } } - # END block(s) + # END rule(s) END { 1 print "First END rule" @@ -19597,7 +19829,7 @@ come out as: print $0 } -which is correct, but possibly surprising. +which is correct, but possibly unexpected. Besides creating profiles when a program has completed, `gawk' can produce a profile while it is running. This is useful if your `awk' @@ -19614,7 +19846,7 @@ The shell prints a job number and process ID number; in this case, $ kill -USR1 13992 As usual, the profiled version of the program is written to -`awkprof.out', or to a different file if one specified with the +`awkprof.out', or to a different file if one was specified with the `--profile' option. Along with the regular profile, as shown earlier, the profile file @@ -19658,7 +19890,8 @@ File: gawk.info, Node: Advanced Features Summary, Prev: Profiling, Up: Advanc * The `--non-decimal-data' option causes `gawk' to treat octal- and hexadecimal-looking input data as octal and hexadecimal. This option should be used with caution or not at all; use of - `strtonum()' is preferable. + `strtonum()' is preferable. Note that this option may disappear + in a future version of `gawk'. * You can take over complete control of sorting in `for (INDX in ARRAY)' array traversal by setting `PROCINFO["sorted_in"]' to the @@ -19672,14 +19905,14 @@ File: gawk.info, Node: Advanced Features Summary, Prev: Profiling, Up: Advanc `PROCINFO["sorted_in"]'. * You can use the `|&' operator to create a two-way pipe to a - co-process. You read from the co-process with `getline' and write + coprocess. You read from the coprocess with `getline' and write to it with `print' or `printf'. Use `close()' to close off the - co-process completely, or optionally, close off one side of the + coprocess completely, or optionally, close off one side of the two-way communications. - * By using special "file names" with the `|&' operator, you can open - a TCP/IP (or UDP/IP) connection to remote hosts in the Internet. - `gawk' supports both IPv4 an IPv6. + * By using special file names with the `|&' operator, you can open a + TCP/IP (or UDP/IP) connection to remote hosts in the Internet. + `gawk' supports both IPv4 and IPv6. * You can generate statement count profiles of your program. This can help you determine which parts of your program may be taking @@ -19840,7 +20073,7 @@ are: Character-type information (alphabetic, digit, upper- or lowercase, and so on) as well as character encoding. This information is accessed via the POSIX character classes in regular - expressions, such as `/[[:alnum:]]/' (*note Regexp Operators::). + expressions, such as `/[[:alnum:]]/' (*note Bracket Expressions::). `LC_MONETARY' Monetary information, such as the currency symbol, and whether the @@ -19908,8 +20141,8 @@ internationalization: Return the plural form used for NUMBER of the translation of STRING1 and STRING2 in text domain DOMAIN for locale category CATEGORY. STRING1 is the English singular variant of a message, - and STRING2 the English plural variant of the same message. The - default value for DOMAIN is the current value of `TEXTDOMAIN'. + and STRING2 is the English plural variant of the same message. + The default value for DOMAIN is the current value of `TEXTDOMAIN'. The default value for CATEGORY is `"LC_MESSAGES"'. The same remarks about argument order as for the `dcgettext()' @@ -19962,9 +20195,11 @@ outlined in *note Explaining gettext::, like so: one. This example would be better done with `dcngettext()': if (groggy) - message = dcngettext("%d customer disturbing me\n", "%d customers disturbing me\n", "adminprog") + message = dcngettext("%d customer disturbing me\n", + "%d customers disturbing me\n", "adminprog") else - message = dcngettext("enjoying %d customer\n", "enjoying %d customers\n", "adminprog") + message = dcngettext("enjoying %d customer\n", + "enjoying %d customers\n", "adminprog") printf(message, ncustomers) 4. During development, you might want to put the `.gmo' file in a @@ -20022,7 +20257,7 @@ marked and you've set (and perhaps bound) the text domain, it is time to produce translations. First, use the `--gen-pot' command-line option to create the initial `.pot' file: - $ gawk --gen-pot -f guide.awk > guide.pot + gawk --gen-pot -f guide.awk > guide.pot When run with `--gen-pot', `gawk' does not execute your program. Instead, it parses it as usual and prints all marked strings to @@ -20074,11 +20309,11 @@ example, `string' is the first argument and `length(string)' is the second: $ gawk 'BEGIN { - > string = "Dont Panic" + > string = "Don\47t Panic" > printf "%2$d characters live in \"%1$s\"\n", > string, length(string) > }' - -| 10 characters live in "Dont Panic" + -| 11 characters live in "Don't Panic" If present, positional specifiers come first in the format specification, before the flags, the field width, and/or the precision. @@ -20239,7 +20474,8 @@ 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. The directory +our file is to be used in the `en_US.UTF-8' locale, since 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: @@ -20248,7 +20484,7 @@ Other versions of `gettext' may use a different layout: The `msgfmt' utility does the conversion from human-readable `.po' file to machine-readable `.mo' file. By default, `msgfmt' creates a file named `messages'. This file must be renamed and placed in the -proper directory so that `gawk' can find it: +proper directory (using the `-o' option) so that `gawk' can find it: $ msgfmt guide-mellow.po -o en_US.UTF-8/LC_MESSAGES/guide.mo @@ -20281,8 +20517,8 @@ File: gawk.info, Node: Gawk I18N, Next: I18N Summary, Prev: I18N Example, Up `gawk' itself has been internationalized using the GNU `gettext' package. (GNU `gettext' is described in complete detail in *note (GNU `gettext' utilities)Top:: gettext, GNU gettext tools.) As of this -writing, the latest version of GNU `gettext' is version 0.19.1 -(ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.1.tar.gz). +writing, the latest version of GNU `gettext' is version 0.19.2 +(ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.2.tar.gz). If a translation of `gawk''s messages exists, then `gawk' produces usage messages, warnings, and fatal errors in the local language. @@ -20367,7 +20603,7 @@ File: gawk.info, Node: Debugging Concepts, Next: Debugging Terms, Up: Debuggi --------------------------- (If you have used debuggers in other languages, you may want to skip -ahead to the next section on the specific features of the `awk' +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 @@ -20403,8 +20639,8 @@ functional program that you or someone else wrote). File: gawk.info, Node: Debugging Terms, Next: Awk Debugging, Prev: Debugging Concepts, Up: Debugging -14.1.2 Additional Debugging Concepts ------------------------------------- +14.1.2 Debugging Concepts +------------------------- Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. The following list @@ -20496,22 +20732,22 @@ File: gawk.info, Node: Debugger Invocation, Next: Finding The Bug, Up: Sample 14.2.1 How to Start the Debugger -------------------------------- -Starting the debugger is almost exactly like running `gawk', except you -have to pass an additional option `--debug' or the corresponding short -option `-D'. The file(s) containing the program and any supporting -code are given on the command line as arguments to one or more `-f' -options. (`gawk' is not designed to debug command-line programs, only -programs contained in files.) In our case, we invoke the debugger like -this: +Starting the debugger is almost exactly like running `gawk' normally, +except you have to pass an additional option `--debug', or the +corresponding short option `-D'. The file(s) containing the program +and any supporting code are given on the command line as arguments to +one or more `-f' options. (`gawk' is not designed to debug command-line +programs, only programs contained in files.) In our case, we invoke +the debugger like this: - $ gawk -D -f getopt.awk -f join.awk -f uniq.awk inputfile + $ gawk -D -f getopt.awk -f join.awk -f uniq.awk -1 inputfile where both `getopt.awk' and `uniq.awk' are in `$AWKPATH'. (Experienced users of GDB or similar debuggers should note that this syntax is slightly different from what they are used to. With the `gawk' debugger, you give the arguments for running the program in the command line to the debugger rather than as part of the `run' command at the -debugger prompt.) +debugger prompt.) The `-1' is an option to `uniq.awk'. Instead of immediately running the program on `inputfile', as `gawk' would ordinarily do, the debugger merely loads all the program source @@ -20556,7 +20792,7 @@ for a breakpoint in `uniq.awk' is at the beginning of the function To set the breakpoint, use the `b' (breakpoint) command: gawk> b are_equal - -| Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 64 + -| Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 63 The debugger tells us the file and line number where the breakpoint is. Now type `r' or `run' and the program runs until it hits the @@ -20566,8 +20802,8 @@ breakpoint for the first time: -| Starting program: -| Stopping in Rule ... -| Breakpoint 1, are_equal(n, m, clast, cline, alast, aline) - at `awklib/eg/prog/uniq.awk':64 - -| 64 if (fcount == 0 && charcount == 0) + at `awklib/eg/prog/uniq.awk':63 + -| 63 if (fcount == 0 && charcount == 0) gawk> Now we can look at what's going on inside our program. First of all, @@ -20577,11 +20813,11 @@ the current stack frames: gawk> bt -| #0 are_equal(n, m, clast, cline, alast, aline) - at `awklib/eg/prog/uniq.awk':69 - -| #1 in main() at `awklib/eg/prog/uniq.awk':89 + at `awklib/eg/prog/uniq.awk':68 + -| #1 in main() at `awklib/eg/prog/uniq.awk':88 This tells us that `are_equal()' was called by the main program at -line 89 of `uniq.awk'. (This is not a big surprise, since this is the +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 programs, knowing who called a function and with what parameters can be the key to finding the source of the problem.) @@ -20600,13 +20836,13 @@ function was called without arguments (*note Function Calls::). A more useful variable to display might be the current record: gawk> p $0 - -| $0 = string ("gawk is a wonderful program!") + -| $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': gawk> p NR - -| NR = number (2) + -| NR = 2 So we can see that `are_equal()' was only called for the second record of the file. Of course, this is because our program contains a rule for @@ -20620,7 +20856,7 @@ of the file. Of course, this is because our program contains a rule for OK, let's just check that that rule worked correctly: gawk> p last - -| last = string ("awk is a wonderful program!") + -| last = "awk is a wonderful program!" Everything we have done so far has verified that the program has worked as planned, up to and including the call to `are_equal()', so @@ -20629,38 +20865,39 @@ must begin "stepping through" the lines of `are_equal()'. We start by typing `n' (for "next"): gawk> n - -| 67 if (fcount > 0) { + -| 66 if (fcount > 0) { - This tells us that `gawk' is now ready to execute line 67, which + 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 `-f' command-line option. (Notice that we skipped -from where we were before at line 64 to here, since the condition in -line 64 `if (fcount == 0 && charcount == 0)' was false.) +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 +line 63 `if (fcount == 0 && charcount == 0)' was false.) Continuing to step, we now get to the splitting of the current and last records: gawk> n - -| 68 n = split(last, alast) + -| 67 n = split(last, alast) gawk> n - -| 69 m = split($0, aline) + -| 68 m = split($0, aline) At this point, we should be curious to see what our records were split into, so we try to look: gawk> p n m alast aline - -| n = number (5) - -| m = number (5) + -| n = 5 + -| m = untyped variable -| alast = array, 5 elements - -| aline = array, 5 elements + -| aline = untyped variable (The `p' command can take more than one argument, similar to `awk''s `print' statement.) This is kind of disappointing, though. All we found out is that -there are five elements in each of our arrays. Useful enough (we now -know that none of the words were accidentally left out), but what if we -want to see inside the array? +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? The first choice would be to use subscripts: @@ -20670,25 +20907,25 @@ want to see inside the array? Oops! gawk> p alast[1] - -| alast["1"] = string ("awk") + -| alast["1"] = "awk" This would be kind of slow for a 100-member array, though, so `gawk' provides a shortcut (reminiscent of another language not to be mentioned): gawk> p @alast - -| alast["1"] = string ("awk") - -| alast["2"] = string ("is") - -| alast["3"] = string ("a") - -| alast["4"] = string ("wonderful") - -| alast["5"] = string ("program!") + -| alast["1"] = "awk" + -| alast["2"] = "is" + -| alast["3"] = "a" + -| alast["4"] = "wonderful" + -| alast["5"] = "program!" It looks like we got this far OK. Let's take another step or two: gawk> n - -| 70 clast = join(alast, fcount, n) + -| 69 clast = join(alast, fcount, n) gawk> n - -| 71 cline = join(aline, fcount, m) + -| 70 cline = join(aline, fcount, m) Well, here we are at our error (sorry to spoil the suspense). What we had in mind was to join the fields starting from the second one to @@ -20696,8 +20933,8 @@ make the virtual record to compare, and if the first field was numbered zero, this would work. Let's look at what we've got: gawk> p cline clast - -| cline = string ("gawk is a wonderful program!") - -| clast = string ("awk is a wonderful program!") + -| cline = "gawk is a wonderful program!" + -| clast = "awk is a wonderful program!" Hey, those look pretty familiar! They're just our original, unaltered, input records. A little thinking (the human brain is still @@ -20810,13 +21047,13 @@ controlling breakpoints are: `condition' N `"EXPRESSION"' Add a condition to existing breakpoint or watchpoint N. The - condition is an `awk' expression 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. + condition is an `awk' expression _enclosed in double quotes_ 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. `delete' [N1 N2 ...] [N-M] `d' [N1 N2 ...] [N-M] @@ -20935,9 +21172,9 @@ execution of the program than we saw in our earlier example: `until' [[FILENAME`:']N | FUNCTION] `u' [[FILENAME`:']N | FUNCTION] Without any argument, continue execution until a line past the - current line in current stack frame is reached. With an argument, - continue execution until the specified location is reached, or the - current stack frame returns. + current line in the current stack frame is reached. With an + argument, continue execution until the specified location is + reached, or the current stack frame returns. File: gawk.info, Node: Viewing And Changing Data, Next: Execution Stack, Prev: Debugger Execution Control, Up: List of Debugger Commands @@ -20984,9 +21221,9 @@ AWK STATEMENTS This prints the third field in the input record (if the specified field does not exist, it prints `Null field'). A variable can be - an array element, with the subscripts being constant values. To - print the contents of an array, prefix the name of the array with - the `@' symbol: + an array element, with the subscripts being constant string + values. To print the contents of an array, prefix the name of the + array with the `@' symbol: gawk> print @a @@ -21031,7 +21268,7 @@ AWK STATEMENTS File: gawk.info, Node: Execution Stack, Next: Debugger Info, Prev: Viewing And Changing Data, Up: List of Debugger Commands -14.3.4 Dealing with the Stack +14.3.4 Working with the Stack ----------------------------- Whenever you run a program which contains any function calls, `gawk' @@ -21043,11 +21280,13 @@ are: `backtrace' [COUNT] `bt' [COUNT] +`where' [COUNT] Print a backtrace of all function calls (stack frames), or 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. + number. The alias `where' for `backtrace' is provided for + long-time GDB users who may be used to that command. `down' [COUNT] Move COUNT (default 1) frames down the stack toward the innermost @@ -21084,7 +21323,7 @@ know: The value for WHAT should be one of the following: `args' - Arguments of the selected frame. + List arguments of the selected frame. `break' List all currently set breakpoints. @@ -21093,19 +21332,19 @@ know: List all items in the automatic display list. `frame' - Description of the selected stack frame. + Give a description of the selected stack frame. `functions' List all function definitions including source file names and line numbers. `locals' - Local variables of the selected frame. + List local variables of the selected frame. `source' - The name of the current source file. Each time the program - stops, the current source file is the file containing the - current instruction. When the debugger first starts, the + Print the name of the current source file. Each time the + program stops, the current source file is the file containing + the current instruction. When the debugger first starts, the current source file is the first file included via the `-f' option. The `list FILENAME:LINENO' command can be used at any time to change the current source. @@ -21253,7 +21492,7 @@ categories, as follows: or the file named FILENAME. The possible arguments to `list' are as follows: - `-' + `-' (Minus) Print lines before the lines last printed. `+' @@ -21324,8 +21563,8 @@ Variable name completion File: gawk.info, Node: Limitations, Next: Debugging Summary, Prev: Readline Support, Up: Debugger -14.5 Limitations and Future Plans -================================= +14.5 Limitations +================ We hope you find the `gawk' debugger useful and enjoyable to work with, but as with any program, especially in its early releases, it still has @@ -21337,7 +21576,7 @@ some limitations. A few which are worth being aware of are: what your mistake was, though, you'll feel like a real guru. * If you perused the dump of opcodes in *note Miscellaneous Debugger - Commands::, (or if you are already familiar with `gawk' internals), + 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. @@ -21364,10 +21603,6 @@ some limitations. A few which are worth being aware of are: * The `gawk' debugger only accepts source supplied with the `-f' option. - Look forward to a future release when these and other missing -features may be added, and of course feel free to try to add them -yourself! - File: gawk.info, Node: Debugging Summary, Prev: Limitations, Up: Debugger @@ -21404,8 +21639,7 @@ File: gawk.info, Node: Arbitrary Precision Arithmetic, Next: Dynamic Extension ************************************************************ This major node introduces some basic concepts relating to how -computers do arithmetic and briefly lists the features in `gawk' for -performing arbitrary precision floating point computations. It then +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 @@ -21500,9 +21734,10 @@ Floating point arithmetic 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 the following table. +signed. The possible ranges of values are shown in *note +table-numeric-ranges::. -Numeric representation Miniumum value Maximum value +Numeric representation Minimum value Maximum value --------------------------------------------------------------------------- 32-bit signed integer -2,147,483,648 2,147,483,647 32-bit unsigned integer 0 4,294,967,295 @@ -21515,6 +21750,8 @@ Double precision `2.225074e-308' `1.797693e+308' floating point (approximate) +Table 15.1: Value Ranges for Different Numeric Representations + ---------- Footnotes ---------- (1) We don't know why they expect this, but they do. @@ -21547,7 +21784,7 @@ material here. number and infinity produce infinity. "NaN" - "Not A Number."(1). A special value that results from attempting a + "Not A Number."(1) A special value that results from attempting a calculation that has no answer as a real number. In such a case, programs can either receive a floating-point exception, or get `NaN' back as the result. The IEEE 754 standard recommends that @@ -21605,37 +21842,38 @@ 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: -Name Total bits Precision emin emax +Name Total bits Precision Minimum Maximum + exponent exponent --------------------------------------------------------------------------- Single 32 24 -126 +127 Double 64 53 -1022 +1023 Quadruple 128 113 -16382 +16383 -Table 15.1: Basic IEEE Format Context 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. ---------- Footnotes ---------- - (1) Thanks to Michael Brennan for this description, which I have -paraphrased, and for the examples + (1) Thanks to Michael Brennan for this description, which we have +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 Precison 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, `gawk' uses the GNU MPFR (http://www.mpfr.org) and GNU -MP (http://gmplib.org) (GMP) libraries for arbitrary precision +compiled to do so, `gawk' uses the `http://www.mpfr.org GNU MPFR' and +GNU MP (http://gmplib.org) (GMP) libraries for arbitrary precision arithmetic on numbers. You can see if MPFR support is available like so: $ gawk --version - -| GNU Awk 4.1.1, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) + -| GNU Awk 4.1.2, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) -| Copyright (C) 1989, 1991-2014 Free Software Foundation. ... @@ -21653,10 +21891,11 @@ platform-independent results. With the `-M' command-line option, all floating-point arithmetic operators and numeric functions can yield results to any desired precision level supported by MPFR. - Two built-in variables, `PREC' and `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. *Note -Auto-set::, for more information. + Two predefined variables, `PREC' and `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. +*Note Setting precision::, and *note Setting the rounding mode::, for +more information. File: gawk.info, Node: FP Math Caution, Next: Arbitrary Precision Integers, Prev: MPFR features, Up: Arbitrary Precision Arithmetic @@ -21770,6 +22009,9 @@ you. Code to do this looks something like this: else # not ok +(We assume that you have a simple absolute value function named `abs()' +defined elsewhere in your program.) + File: gawk.info, Node: Errors accumulate, Prev: Comparing FP Values, Up: Inexactness of computations @@ -21852,7 +22094,7 @@ 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 -computations with a particular precision and effective rounding rule, a +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. @@ -21915,7 +22157,7 @@ File: gawk.info, Node: Setting precision, Next: Setting the rounding mode, Pr precision or accuracy of individual numbers. Performing an arithmetic operation or calling a built-in function rounds the result to the current working precision. The default working precision is 53 bits, -which you can modify using the built-in variable `PREC'. You can also +which you can modify using the predefined variable `PREC'. You can also set the value to one of the predefined case-insensitive strings shown in *note table-predefined-precision-strings::, to emulate an IEEE 754 binary format. @@ -21928,7 +22170,7 @@ binary format. `"quad"' Basic 128-bit quadruple precision. `"oct"' 256-bit octuple precision. -Table 15.2: 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: @@ -21942,7 +22184,7 @@ on arithmetic operations: floating-point constant from program source code, `gawk' uses the default precision (that of a C `double'), unless overridden by an assignment to the special variable `PREC' on the command line, to - store it internally as a MPFR number. Changing the precision + store it internally as an MPFR number. Changing the precision using `PREC' in the program text does _not_ change the precision of a constant. @@ -21981,10 +22223,10 @@ Round toward zero `roundTowardZero' `"Z"' or `"z"' Round to nearest, ties away `roundTiesToAway' `"A"' or `"a"' from zero -Table 15.3: `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.3: +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. @@ -22063,15 +22305,15 @@ 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 +which is beyond the limits of ordinary hardware double precision floating point values: $ gawk -M 'BEGIN { > x = 5^4^3^2 - > print "# of digits =", length(x) + > print "number of digits =", length(x) > print substr(x, 1, 20), "...", substr(x, length(x) - 19, 20) > }' - -| # of digits = 183231 + -| number of digits = 183231 -| 62060698786608744707 ... 92256259918212890625 If instead you were to compute the same value using arbitrary @@ -22133,7 +22375,7 @@ user-defined function: # div --- do integer division - function div(numerator, denominator, result, i) + function div(numerator, denominator, result) { split("", result) @@ -22145,6 +22387,39 @@ user-defined function: return 0.0 } + The following example program, contributed by Katie Wasserman, uses +`div()' to compute the digits of pi to as many places as you choose to +set: + + # pi.awk --- compute the digits of pi + + BEGIN { + digits = 100000 + two = 2 * 10 ^ digits + pi = two + for (m = digits * 4; m > 0; --m) { + d = m * 2 + 1 + x = pi * m + div(x, d, result) + pi = result["quotient"] + pi = pi + two + } + print pi + } + + When asked about the algorithm used, Katie replied: + + It's not that well known but it's not that obscure either. It's + Euler's modification to Newton's method for calculating pi. Take + a look at lines (23) - (25) here: + `http://mathworld.wolfram.com/PiFormulas.htm'. + + The algorithm I wrote simply expands the multiply by 2 and works + from the innermost expression outwards. I used this to program HP + calculators because it's quite easy to modify for tiny memory + devices with smallish word sizes. See + `http://www.hpmuseum.org/cgi-sys/cgiwrap/hpmuseum/articles.cgi?read=899'. + ---------- Footnotes ---------- (1) Weisstein, Eric W. `Sylvester's Sequence'. From MathWorld--A @@ -22246,8 +22521,8 @@ File: gawk.info, Node: Floating point summary, Prev: POSIX Floating Point Prob ============ * Most computer arithmetic is done using either integers or - floating-point values. The default for `awk' is to use - double-precision floating-point values. + 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 @@ -22348,7 +22623,7 @@ 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' developers. The rest of this major node explains the facilities that -the API provides and how to use them, and presents a small sample +the API provides and how to use them, and presents a small example extension. In addition, it documents the sample extensions included in the `gawk' distribution, and describes the `gawkextlib' project. *Note Extension Design::, for a discussion of the extension mechanism goals @@ -22360,10 +22635,13 @@ File: gawk.info, Node: Plugin License, Next: Extension Mechanism Outline, Pre 16.2 Extension Licensing ======================== -Every dynamic extension should define the global symbol -`plugin_is_GPL_compatible' to assert that it has been licensed under a -GPL-compatible license. If this symbol does not exist, `gawk' emits a -fatal error and exits when it tries to load your extension. +Every dynamic extension must be distributed under a license that is +compatible with the GNU GPL (*note Copying::). + + In order for the extension to tell `gawk' that it is properly +licensed, the extension must define the global symbol +`plugin_is_GPL_compatible'. If this symbol does not exist, `gawk' +emits a fatal error and exits when it tries to load your extension. The declared type of the symbol should be `int'. It does not need to be in any allocated section, though. The code merely asserts that @@ -22378,7 +22656,7 @@ File: gawk.info, Node: Extension Mechanism Outline, Next: Extension API Descri ================================= Communication between `gawk' and an extension is two-way. First, when -an extension is loaded, it is passed a pointer to a `struct' whose +an extension is loaded, `gawk' passes it a pointer to a `struct' whose fields are function pointers. This is shown in *note figure-load-extension::. @@ -22411,8 +22689,8 @@ 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 `gawk''s symbols. One of these function pointers is to a function for -"registering" new built-in functions. This is shown in *note -figure-load-new-function::. +"registering" new functions. This is shown in *note +figure-register-new-function::. register_ext_func({ "chdir", do_chdir, 1 }); @@ -22426,7 +22704,7 @@ figure-load-new-function::. +-------+-+---+-+---+-+------------------+--------------+-+---+ gawk Main Program Address Space Extension -Figure 16.2: Loading The 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 @@ -22459,8 +22737,8 @@ and understandable. Although all of this sounds somewhat complicated, the result is that extension code is quite straightforward to write and to read. You can -see this in the sample extensions `filefuncs.c' (*note Extension -Example::) and also the `testext.c' code for testing the APIs. +see this in the sample extension `filefuncs.c' (*note Extension +Example::) and also in the `testext.c' code for testing the APIs. Some other bits and pieces: @@ -22491,13 +22769,13 @@ describes the API in detail. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with `gawk'. * Printing Messages:: Functions for printing messages. * Updating `ERRNO':: Functions for updating `ERRNO'. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -22517,6 +22795,8 @@ through function pointers passed into your extension. API function pointers are provided for the following kinds of operations: + * Allocating, reallocating, and releasing memory. + * Registration functions. You may register: - extension functions, @@ -22541,8 +22821,6 @@ operations: * Symbol table access: retrieving a global variable, creating one, or changing one. - * Allocating, reallocating, and releasing memory. - * Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -22596,9 +22874,8 @@ operations: * All pointers filled in by `gawk' point to memory managed by `gawk' and should be treated by the extension as read-only. Memory for _all_ strings passed into `gawk' from the extension _must_ come - from calling the API-provided function pointers `api_malloc()', - `api_calloc()' or `api_realloc()', and is managed by `gawk' from - then on. + from calling one of `gawk_malloc()', `gawk_calloc()' or + `gawk_realloc()', and is managed by `gawk' from then on. * 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 @@ -22614,7 +22891,7 @@ operations: * When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type - (number, string, scalars, value cookie, array, or "undefined"). + (number, string, scalar, value cookie, array, or "undefined"). When the request is "undefined," the returned value will have the real underlying type. @@ -22631,7 +22908,7 @@ 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: Requesting Values, Prev: Extension API Functions Introduction, Up: Extension API Description +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 --------------------------------- @@ -22670,9 +22947,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 the - API-provided function pointers `api_malloc()', `api_calloc()', or - `api_realloc()'!* + 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. @@ -22758,7 +23034,7 @@ can obtain a "scalar cookie"(1) object for that variable, and then use the cookie for getting the variable's value or for changing the variable's value. This is the `awk_scalar_t' type and `scalar_cookie' macro. Given a scalar cookie, `gawk' can directly retrieve or modify -the value, as required, without having to first find it. +the value, as required, without having to find it first. The `awk_value_cookie_t' type and `value_cookie' macro are similar. If you know that you wish to use the same numeric or string _value_ for @@ -22777,62 +23053,30 @@ the value. See also the entry for "Cookie" in the *note Glossary::. -File: gawk.info, Node: Requesting Values, Next: Memory Allocation Functions, Prev: General Data Types, Up: Extension API Description - -16.4.3 Requesting Values ------------------------- +File: gawk.info, Node: Memory Allocation Functions, Next: Constructor Functions, Prev: General Data Types, Up: Extension API Description -All of the functions that return values from `gawk' work in the same -way. You pass in an `awk_valtype_t' value to indicate what kind of -value you expect. If the actual value matches what you requested, the -function returns true and fills in the `awk_value_t' result. -Otherwise, the function returns false, and the `val_type' member -indicates the type of the actual value. You may then print an error -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: --------------------------------------------------------------------------- - - String Number Array Undefined ------------------------------------------------------------------------------- - String String String false false - Number Number if can Number false false - be converted, - else false -Type Array false false Array 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 - - -File: gawk.info, Node: Memory Allocation Functions, Next: Constructor Functions, Prev: Requesting Values, Up: Extension API Description - -16.4.4 Memory Allocation Functions and Convenience Macros +16.4.3 Memory Allocation Functions and Convenience Macros --------------------------------------------------------- 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. +convenience macros. This node presents them all as function +prototypes, in the way that extension code would use them. `void *gawk_malloc(size_t size);' - Call `gawk'-provided `api_malloc()' to allocate storage that may + Call the correct version of `malloc()' to allocate storage that may be passed to `gawk'. `void *gawk_calloc(size_t nmemb, size_t size);' - Call `gawk'-provided `api_calloc()' to allocate storage that may + Call the correct version of `calloc()' to allocate storage that may be passed to `gawk'. `void *gawk_realloc(void *ptr, size_t size);' - Call `gawk'-provided `api_realloc()' to allocate storage that may - be passed to `gawk'. + Call the correct version of `realloc()' to allocate storage that + may be passed to `gawk'. `void gawk_free(void *ptr);' - Call `gawk'-provided `api_free()' to release storage that was + Call the correct version of `free()' to release storage that was allocated with `gawk_malloc()', `gawk_calloc()' or `gawk_realloc()'. @@ -22842,11 +23086,10 @@ C library than was used for the `gawk' executable.(1) If `gawk' were to use its version of `free()' when the memory came from an unrelated version of `malloc()', unexpected behavior would likely result. - Two convenience macros may be used for allocating storage from the -API-provided function pointers `api_malloc()' and `api_realloc()'. If -the allocation fails, they cause `gawk' to exit with a fatal error -message. They should be used as if they were procedure calls that do -not return a value. + Two convenience macros may be used for allocating storage from +`gawk_malloc()' and `gawk_realloc()'. If the allocation fails, they +cause `gawk' to exit with a fatal error message. They should be used +as if they were procedure calls that do not return a value. `#define emalloc(pointer, type, size, message) ...' The arguments to this macro are as follows: @@ -22856,7 +23099,7 @@ not return a value. `type' The type of the pointer variable, used to create a cast for - the call to `api_malloc()'. + the call to `gawk_malloc()'. `size' The total number of bytes to be allocated. @@ -22876,9 +23119,9 @@ not return a value. make_malloced_string(message, strlen(message), & result); `#define erealloc(pointer, type, size, message) ...' - This is like `emalloc()', but it calls `api_realloc()', instead of - `api_malloc()'. The arguments are the same as for the `emalloc()' - macro. + This is like `emalloc()', but it calls `gawk_realloc()', instead + of `gawk_malloc()'. The arguments are the same as for the + `emalloc()' macro. ---------- Footnotes ---------- @@ -22888,7 +23131,7 @@ Unix-like systems as well. File: gawk.info, Node: Constructor Functions, Next: Registration Functions, Prev: Memory Allocation Functions, Up: Extension API Description -16.4.5 Constructor Functions +16.4.4 Constructor Functions ---------------------------- The API provides a number of "constructor" functions for creating @@ -22907,10 +23150,10 @@ extension code would use them. `make_malloced_string(const char *string, size_t length, awk_value_t *result)' This function creates a string value in the `awk_value_t' variable pointed to by `result'. It expects `string' to be a `char *' value - pointing to data previously obtained from the api-provided - functions `api_malloc()', `api_calloc()' or `api_realloc()'. The - idea here is that the data is passed directly to `gawk', which - assumes responsibility for it. It returns `result'. + pointing to data previously obtained from `gawk_malloc()', + `gawk_calloc()' or `gawk_realloc()'. The idea here is that the + data is passed directly to `gawk', which assumes responsibility + for it. It returns `result'. `static inline awk_value_t *' `make_null_string(awk_value_t *result)' @@ -22926,7 +23169,7 @@ extension code would use them. File: gawk.info, Node: Registration Functions, Next: Printing Messages, Prev: Constructor Functions, Up: Extension API Description -16.4.6 Registration Functions +16.4.5 Registration Functions ----------------------------- This minor node describes the API functions for registering parts of @@ -22944,7 +23187,7 @@ your extension with `gawk'. File: gawk.info, Node: Extension Functions, Next: Exit Callback Functions, Up: Registration Functions -16.4.6.1 Registering An Extension Function +16.4.5.1 Registering An Extension Function .......................................... Extension functions are described by the following record: @@ -22962,17 +23205,16 @@ Extension functions are described by the following record: by this name. This is a regular C string. Function names must obey the rules for `awk' identifiers. That is, - they must begin with either a letter or an underscore, which may - be followed by any number of letters, digits, and underscores. - Letter case in function names is significant. + they must begin with either an English letter or an underscore, + which may be followed by any number of letters, digits, and + underscores. Letter case in function names is significant. `awk_value_t *(*function)(int num_actual_args, awk_value_t *result);' - This is a pointer to the C function that provides the desired - functionality. The function must fill in the result with either a + This is a pointer to the C function that provides the extension's + 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 the - api-provided functions `api_malloc()', `api_calloc()' or - `api_realloc()'. + As mentioned earlier, string memory *must* come from one of + `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. @@ -22983,7 +23225,7 @@ Extension functions are described by the following record: `size_t num_expected_args;' This is the number of arguments the function expects to receive. Each extension function may decide what to do if the number of - arguments isn't what it expected. Following `awk' functions, it + arguments isn't what it expected. As with real `awk' functions, it is likely OK to ignore extra arguments. Once you have a record representing your extension function, you @@ -22998,7 +23240,7 @@ register it with `gawk' using this API function: File: gawk.info, Node: Exit Callback Functions, Next: Extension Version String, Prev: Extension Functions, Up: Registration Functions -16.4.6.2 Registering An Exit Callback Function +16.4.5.2 Registering An Exit Callback Function .............................................. An "exit callback" function is a function that `gawk' calls before it @@ -23028,7 +23270,7 @@ order--that is, in the reverse order in which they are registered with File: gawk.info, Node: Extension Version String, Next: Input Parsers, Prev: Exit Callback Functions, Up: Registration Functions -16.4.6.3 Registering An Extension Version String +16.4.5.3 Registering An Extension Version String ................................................ You can register a version string which indicates the name and version @@ -23044,7 +23286,7 @@ invoked with the `--version' option. File: gawk.info, Node: Input Parsers, Next: Output Wrappers, Prev: Extension Version String, Up: Registration Functions -16.4.6.4 Customized Input Parsers +16.4.5.4 Customized Input Parsers ................................. By default, `gawk' reads text files as its input. It uses the value of @@ -23213,7 +23455,7 @@ records. The parameters are as follows: `*rt_start' should be set to point to the data to be used for `RT', and `*rt_len' should be set to the length of the data. Otherwise, `*rt_len' should be set to zero. `gawk' makes its own - copy of this data, so the extension must manage the storage. + copy of this data, so the extension must manage this storage. The return value is the length of the buffer pointed to by `*out', or `EOF' if end-of-file was reached or an error occurred. @@ -23267,7 +23509,7 @@ whether or not to activate an input parser (*note BEGINFILE/ENDFILE::). File: gawk.info, Node: Output Wrappers, Next: Two-way processors, Prev: Input Parsers, Up: Registration Functions -16.4.6.5 Customized Output Wrappers +16.4.5.5 Customized Output Wrappers ................................... An "output wrapper" is the mirror image of an input parser. It allows @@ -23374,7 +23616,7 @@ just use normally. File: gawk.info, Node: Two-way processors, Prev: Output Wrappers, Up: Registration Functions -16.4.6.6 Customized Two-way Processors +16.4.5.6 Customized Two-way Processors ...................................... A "two-way processor" combines an input parser and an output wrapper for @@ -23427,7 +23669,7 @@ can take this" and "take over for this" functions, File: gawk.info, Node: Printing Messages, Next: Updating `ERRNO', Prev: Registration Functions, Up: Extension API Description -16.4.7 Printing Messages +16.4.6 Printing Messages ------------------------ You can print different kinds of warning messages from your extension, @@ -23456,9 +23698,9 @@ of the ISO C 99 variadic macro feature to hide that parameter. More's the pity. -File: gawk.info, Node: Updating `ERRNO', Next: Accessing Parameters, Prev: Printing Messages, Up: Extension API Description +File: gawk.info, Node: Updating `ERRNO', Next: Requesting Values, Prev: Printing Messages, Up: Extension API Description -16.4.8 Updating `ERRNO' +16.4.7 Updating `ERRNO' ----------------------- The following functions allow you to update the `ERRNO' variable: @@ -23473,11 +23715,44 @@ The following functions allow you to update the `ERRNO' variable: Set `ERRNO' directly to the string value of `ERRNO'. `gawk' makes a copy of the value of `string'. -`void unset_ERRNO();' +`void unset_ERRNO(void);' Unset `ERRNO'. -File: gawk.info, Node: Accessing Parameters, Next: Symbol Table Access, Prev: Updating `ERRNO', Up: Extension API Description +File: gawk.info, Node: Requesting Values, Next: Accessing Parameters, Prev: Updating `ERRNO', Up: Extension API Description + +16.4.8 Requesting Values +------------------------ + +All of the functions that return values from `gawk' work in the same +way. You pass in an `awk_valtype_t' value to indicate what kind of +value you expect. If the actual value matches what you requested, the +function returns true and fills in the `awk_value_t' result. +Otherwise, the function returns false, and the `val_type' member +indicates the type of the actual value. You may then print an error +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: +-------------------------------------------------------------------------- + + String Number Array Undefined +------------------------------------------------------------------------------ + String String String false false + Number Number if can Number false false + be converted, + else false +Type Array false false Array 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 + + +File: gawk.info, Node: Accessing Parameters, Next: Symbol Table Access, Prev: Requesting Values, Up: Extension API Description 16.4.9 Accessing and Updating Parameters ---------------------------------------- @@ -23535,7 +23810,7 @@ termed a "symbol table". Fill in the `awk_value_t' structure pointed to by `result' with the value of the variable named by the string `name', which is a regular C string. `wanted' indicates the type of value expected. - Return true if the actual type matches `wanted', false otherwise + Return true if the actual type matches `wanted', false otherwise. In the latter case, `result->val_type' indicates the actual type (*note Table 16.1: table-value-types-returned.). @@ -23553,7 +23828,7 @@ termed a "symbol table". However, with the exception of the `PROCINFO' array, an extension cannot change any of those variables. - NOTE: It is possible for the lookup of `PROCINFO' to fail. This + 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. @@ -23575,14 +23850,14 @@ was discussed earlier, in *note General Data Types::. ` awk_valtype_t wanted,' ` awk_value_t *result);' Retrieve the current value of a scalar cookie. Once you have - obtained a scalar_cookie using `sym_lookup()', you can use this + obtained a scalar cookie using `sym_lookup()', you can use this function to get its value more efficiently. Return false if the value cannot be retrieved. `awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value);' Update the value associated with a scalar cookie. Return false if the new value is not of type `AWK_STRING' or `AWK_NUMBER'. Here - too, the built-in variables may not be updated. + too, the predefined variables may not be updated. It is not obvious at first glance how to work with scalar cookies or what their raison d'e^tre really is. In theory, the `sym_lookup()' and @@ -23634,7 +23909,7 @@ usual. Then get a scalar cookie for the variable using `sym_lookup()': /* install initial value */ sym_update("MAGIC_VAR", make_number(42.0, & value)); - /* get cookie */ + /* get the cookie */ sym_lookup("MAGIC_VAR", AWK_SCALAR, & value); /* save the cookie */ @@ -23685,7 +23960,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 -`api_malloc()', `api_calloc()' or `api_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) @@ -23749,8 +24024,8 @@ Using value cookies in this way saves considerable storage, since all of `VAR1' through `VAR100' share the same value. You might be wondering, "Is this sharing problematic? What happens -if `awk' code assigns a new value to `VAR1', are all the others be -changed too?" +if `awk' code assigns a new value to `VAR1', are all the others changed +too?" That's a great question. The answer is that no, it's not a problem. Internally, `gawk' uses "reference-counted strings". This means that @@ -23816,7 +24091,7 @@ The data types associated with arrays are listed below. ` struct awk_element *next;' ` enum {' ` AWK_ELEMENT_DEFAULT = 0, /* set by gawk */' -` AWK_ELEMENT_DELETE = 1 /* set by extension if should be deleted */' +` AWK_ELEMENT_DELETE = 1 /* set by extension */' ` } flags;' ` awk_value_t index;' ` awk_value_t value;' @@ -23834,8 +24109,8 @@ The data types associated with arrays are listed below. the list. `enum { ... } flags;' - A set of flag values that convey information between `gawk' - and the extension. Currently there is only one: + A set of flag values that convey information between the + extension and `gawk'. Currently there is only one: `AWK_ELEMENT_DELETE'. Setting it causes `gawk' to delete the element from the original array upon release of the flattened array. @@ -23846,8 +24121,8 @@ The data types associated with arrays are listed below. memory pointed to by `index' and `value' belongs to `gawk'. `typedef struct awk_flat_array {' -` awk_const void *awk_const opaque1; /* private data for use by gawk */' -` awk_const void *awk_const opaque2; /* private data for use by gawk */' +` awk_const void *awk_const opaque1; /* for use by gawk */' +` awk_const void *awk_const opaque2; /* for use by gawk */' ` awk_const size_t count; /* how many elements */' ` awk_element_t elements[1]; /* will be extended */' `} awk_flat_array_t;' @@ -23871,7 +24146,7 @@ File: gawk.info, Node: Array Functions, Next: Flattening Arrays, Prev: Array The following functions relate to individual array elements. `awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count);' - For the array represented by `a_cookie', return in `*count' the + For the array represented by `a_cookie', place in `*count' the number of elements it contains. A subarray counts as a single element. Return false if there is an error. @@ -23891,9 +24166,9 @@ The following functions relate to individual array elements. strings (*note Conversion::); thus using integral values is safest. As with _all_ strings passed into `gawk' from an extension, the - string value of `index' must come from the API-provided functions - `api_malloc()', `api_calloc()' or `api_realloc()' and `gawk' - releases the storage. + string value of `index' must come from `gawk_malloc()', + `gawk_calloc()' or `gawk_realloc()', and `gawk' releases the + storage. `awk_bool_t set_array_element(awk_array_t a_cookie,' ` const awk_value_t *const index,' @@ -23915,7 +24190,7 @@ The following functions relate to individual array elements. The following functions relate to arrays as a whole: -`awk_array_t create_array();' +`awk_array_t create_array(void);' Create a new array to which elements may be added. *Note Creating Arrays::, for a discussion of how to create a new array and add elements to it. @@ -23951,7 +24226,8 @@ 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. - First, the `gawk' script that drives the test extension: + We walk through that part of the code one step at a time. First, +the `gawk' script that drives the test extension: @load "testext" BEGIN { @@ -24072,8 +24348,7 @@ flag bit set: valrep2str(& flat_array->elements[i].value)); if (strcmp(value3.str_value.str, - flat_array->elements[i].index.str_value.str) - == 0) { + flat_array->elements[i].index.str_value.str) == 0) { flat_array->elements[i].flags |= AWK_ELEMENT_DELETE; printf("dump_array_and_delete: marking element \"%s\" " "for deletion\n", @@ -24163,9 +24438,9 @@ code: The following C code is a simple test extension to create an array with two regular elements and with a subarray. The leading `#include' -directives and boilerplate variable declarations are omitted for -brevity. The first step is to create a new array and then install it -in the symbol table: +directives and boilerplate variable declarations (*note Extension API +Boilerplate::) are omitted for brevity. The first step is to create a +new array and then install it in the symbol table: /* create_new_array --- create a named array */ @@ -24352,8 +24627,8 @@ invoked. The variables are: option. The value of `do_lint' can change if `awk' code modifies the `LINT' -built-in variable (*note Built-in Variables::). The others should not -change during execution. +predefined variable (*note Built-in Variables::). The others should +not change during execution. File: gawk.info, Node: Extension API Boilerplate, Prev: Extension API Variables, Up: Extension API Description @@ -24387,12 +24662,12 @@ in the `gawkapi.h' header file: /* OR: */ static awk_bool_t - init_my_module(void) + init_my_extension(void) { ... } - static awk_bool_t (*init_func)(void) = init_my_module; + static awk_bool_t (*init_func)(void) = init_my_extension; dl_load_func(func_table, some_name, "name_space_in_quotes") @@ -24424,8 +24699,8 @@ in the `gawkapi.h' header file: `static awk_bool_t (*init_func)(void) = NULL;' ` OR' -`static awk_bool_t init_my_module(void) { ... }' -`static awk_bool_t (*init_func)(void) = init_my_module;' +`static awk_bool_t init_my_extension(void) { ... }' +`static awk_bool_t (*init_func)(void) = init_my_extension;' If you need to do some initialization work, you should define a function that does it (creates variables, opens files, etc.) and then define the `init_func' pointer to point to your function. @@ -24479,8 +24754,9 @@ File: gawk.info, Node: Extension Example, Next: Extension Samples, Prev: Find 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' -program can gather information about a file). This minor node -implements these functions for `gawk' in an extension. +program can gather information about a file). In order to illustrate +the API in action, this minor node implements these functions for +`gawk' in an extension. * Menu: @@ -24504,8 +24780,7 @@ directory to change to: newdir = "/home/arnold/funstuff" ret = chdir(newdir) if (ret < 0) { - printf("could not change to %s: %s\n", - newdir, ERRNO) > "/dev/stderr" + printf("could not change to %s: %s\n", newdir, ERRNO) > "/dev/stderr" exit 1 } ... @@ -24670,7 +24945,7 @@ 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'. - /* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ + /* do_chdir --- provide dynamically loaded chdir() function for gawk */ static awk_value_t * do_chdir(int nargs, awk_value_t *result) @@ -24858,12 +25133,20 @@ and/or the type of the file. It then returns zero, for success: } } - array_set(array, "type", make_const_string(type, strlen(type), &tmp)); + array_set(array, "type", make_const_string(type, strlen(type), & tmp)); return 0; } - Finally, here is the `do_stat()' function. It starts with variable + The third argument to `stat()' was not discussed previously. This +argument is optional. If present, it causes `do_stat()' to use the +`stat()' system call instead of the `lstat()' system call. This is +done by using a function pointer: `statfunc'. `statfunc' is +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 declarations and argument checking: /* do_stat --- provide a stat() function for gawk */ @@ -24888,14 +25171,10 @@ declarations and argument checking: return make_number(-1, result); } - The third argument to `stat()' was not discussed previously. This -argument is optional. If present, it causes `stat()' to use the `stat()' -system call instead of the `lstat()' system call. - Then comes the actual work. First, the function gets the arguments. -Next, it gets the information for the file. The code use `lstat()' -(instead of `stat()') to get the file information, in case the file is -a symbolic link. If there's an error, it sets `ERRNO' and returns: +Next, it gets the information for the file. If the called function +(`lstat()' or `stat()') returns an error, the code sets `ERRNO' and +returns: /* file is first arg, array to hold results is second */ if ( ! get_argument(0, AWK_STRING, & file_param) @@ -24922,7 +25201,7 @@ a symbolic link. If there's an error, it sets `ERRNO' and returns: } The tedious work is done by `fill_stat_array()', shown earlier. -When done, return the result from `fill_stat_array()': +When done, the function returns the result from `fill_stat_array()': ret = fill_stat_array(name, array, & sbuf); @@ -25004,14 +25283,14 @@ create a GNU/Linux shared library: for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] print "testff.awk modified:", - strftime("%m %d %y %H:%M:%S", data["mtime"]) + strftime("%m %d %Y %H:%M:%S", data["mtime"]) print "\nInfo for JUNK" ret = stat("JUNK", data) print "ret =", ret for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] - print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"]) + print "JUNK modified:", strftime("%m %d %Y %H:%M:%S", data["mtime"]) } The `AWKLIBPATH' environment variable tells `gawk' where to find @@ -25023,32 +25302,33 @@ directory and run the program: -| Info for testff.awk -| ret = 0 -| data["blksize"] = 4096 - -| data["mtime"] = 1350838628 + -| data["devbsize"] = 512 + -| data["mtime"] = 1412004710 -| data["mode"] = 33204 -| data["type"] = file -| data["dev"] = 2053 -| data["gid"] = 1000 - -| data["ino"] = 1719496 - -| data["ctime"] = 1350838628 + -| data["ino"] = 10358899 + -| data["ctime"] = 1412004710 -| data["blocks"] = 8 -| data["nlink"] = 1 -| data["name"] = testff.awk - -| data["atime"] = 1350838632 + -| data["atime"] = 1412004716 -| data["pmode"] = -rw-rw-r-- - -| data["size"] = 662 + -| data["size"] = 666 -| data["uid"] = 1000 - -| testff.awk modified: 10 21 12 18:57:08 + -| testff.awk modified: 09 29 2014 18:31:50 -| -| Info for JUNK -| ret = -1 - -| JUNK modified: 01 01 70 02:00:00 + -| JUNK modified: 01 01 1970 02:00:00 ---------- 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 WWW links to the tools. +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 @@ -25076,9 +25356,9 @@ the extension API. * Extension Sample Rev2way:: Reversing data sample two-way processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to `gettimeofday()' and `sleep()'. +* Extension Sample API Tests:: Tests for the API. File: gawk.info, Node: Extension Sample File Functions, Next: Extension Sample Fnmatch, Up: Extension Samples @@ -25089,7 +25369,7 @@ File: gawk.info, Node: Extension Sample File Functions, Next: Extension Sample The `filefuncs' extension provides three different functions, as follows: The usage is: -@load "filefuncs" +`@load "filefuncs"' This is how you load the extension. `result = chdir("/some/directory")' @@ -25145,8 +25425,8 @@ follows: The usage is: `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 constant values, also described below. Return - zero if there were no errors, otherwise return -1. + several predefined values, also described below. 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 @@ -25187,10 +25467,10 @@ requested hierarchies. whether or not `FTS_LOGICAL' is set. `FTS_SEEDOT' - By default, the `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.) + 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.) `FTS_XDEV' During a traversal, do not cross onto a different mounted @@ -25240,15 +25520,16 @@ Otherwise it returns -1. NOTE: The `fts()' extension does not exactly mimic the interface of the C library `fts()' routines, choosing instead to provide an - interface that is based on associative arrays, which should be - 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 could have been provided, this felt less natural than - simply creating a multidimensional array to represent the file - hierarchy and its information. + 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 + could have been provided, this felt less natural than simply + creating a multidimensional array to represent the file hierarchy + and its information. - See `test/fts.awk' in the `gawk' distribution for an example. + See `test/fts.awk' in the `gawk' distribution for an example use of +the `fts()' extension function. File: gawk.info, Node: Extension Sample Fnmatch, Next: Extension Sample Fork, Prev: Extension Sample File Functions, Up: Extension Samples @@ -25443,7 +25724,7 @@ Letter File Type `s' Socket `u' Anything else (unknown) -Table 16.2: File Types Returned By `readdir()' +Table 16.2: File Types Returned By The `readdir' Extension On systems without the file type information, the third field is always `u'. @@ -25514,6 +25795,9 @@ File: gawk.info, Node: Extension Sample Read write array, Next: Extension Samp The `rwarray' extension adds two functions, named `writea()' and `reada()', as follows: +`@load "rwarray"' + This is how you load the extension. + `ret = writea(file, array)' This function takes a string argument, which is the name of the file to which to dump the array, and the array itself as the @@ -25550,7 +25834,7 @@ restored on systems with a different one, but this has not been tried. ret = reada("arraydump.bin", array) -File: gawk.info, Node: Extension Sample Readfile, Next: Extension Sample API Tests, Prev: Extension Sample Read write array, Up: Extension Samples +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 ------------------------------ @@ -25583,21 +25867,9 @@ an input parser: } -File: gawk.info, Node: Extension Sample API Tests, Next: Extension Sample Time, Prev: Extension Sample Readfile, Up: Extension Samples - -16.7.11 API Tests ------------------ - -The `testext' extension exercises parts of the extension API that are -not tested by the other samples. The `extension/testext.c' file -contains both the C code for the extension and `awk' test code inside C -comments that run the tests. The testing framework extracts the `awk' -code and runs the tests. See the source file for more information. - - -File: gawk.info, Node: Extension Sample Time, Prev: Extension Sample API Tests, Up: Extension Samples +File: gawk.info, Node: Extension Sample Time, Next: Extension Sample API Tests, Prev: Extension Sample Readfile, Up: Extension Samples -16.7.12 Extension Time Functions +16.7.11 Extension Time Functions -------------------------------- The `time' extension adds two functions, named `gettimeofday()' and @@ -25626,6 +25898,18 @@ The `time' extension adds two functions, named `gettimeofday()' and delay. +File: gawk.info, Node: Extension Sample API Tests, Prev: Extension Sample Time, Up: Extension Samples + +16.7.12 API Tests +----------------- + +The `testext' extension exercises parts of the extension API that are +not tested by the other samples. The `extension/testext.c' file +contains both the C code for the extension and `awk' test code inside C +comments that run the tests. The testing framework extracts the `awk' +code and runs the tests. See the source file for more information. + + File: gawk.info, Node: gawkextlib, Next: Extension summary, Prev: Extension Samples, Up: Dynamic Extensions 16.8 The `gawkextlib' Project @@ -25638,21 +25922,17 @@ project. As of this writing, there are five extensions: - * XML parser extension, using the Expat - (http://expat.sourceforge.net) XML parsing library. + * GD graphics library extension. * PDF extension. * PostgreSQL extension. - * GD graphics library extension. - * MPFR library extension. This provides access to a number of MPFR functions which `gawk''s native MPFR support does not. - The `time' extension described earlier (*note Extension Sample -Time::) was originally from this project but has been moved in to the -main `gawk' distribution. + * XML parser extension, using the Expat + (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 @@ -25716,7 +25996,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga tasks. * One of these tasks is to "register" the name and implementation of - a new `awk'-level function with `gawk'. The implementation takes + new `awk'-level functions with `gawk'. The implementation takes the form of a C function pointer with a defined signature. By convention, implementation functions are named `do_XXXX()' for some `awk'-level function `XXXX()'. @@ -25728,6 +26008,8 @@ 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. + * Registration functions. You may register extension functions, exit callbacks, a version string, input parsers, output wrappers, and two-way processors. @@ -25742,8 +26024,6 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga * Symbol table access: retrieving a global variable, creating one, or changing one. - * Allocating, reallocating, and releasing memory. - * Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -25752,7 +26032,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga 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. @@ -25767,7 +26047,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga * _All_ memory passed from an extension to `gawk' must come from the API's memory allocation functions. `gawk' takes responsibility for - the memory and will release it when appropriate. + the memory and releases it when appropriate. * The API provides information about the running version of `gawk' so that an extension can make sure it is compatible with the `gawk' @@ -25781,7 +26061,7 @@ File: gawk.info, Node: Extension summary, Next: Extension Exercises, Prev: ga sample extensions. The `gawkextlib' project includes several more, larger, extensions. If you wish to write an extension and contribute it to the community of `gawk' users, the `gawkextlib' - project should be the place to do so. + project is the place to do so. @@ -25814,11 +26094,11 @@ This Info file describes the GNU implementation of `awk', which follows the POSIX specification. Many long-time `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 some systems -derived from 4.4BSD-Lite, used various versions of `gawk' for their -`awk'.) This major node briefly describes the evolution of the `awk' -language, with cross-references to other parts of the Info file where -you can find more information. +4.3-Reno. Subsequent versions of Berkeley Unix, and, for a while, some +systems derived from 4.4BSD-Lite, used various versions of `gawk' for +their `awk'.) This major node briefly describes the evolution of the +`awk' language, with cross-references to other parts of the Info file +where you can find more information. * Menu: @@ -25868,7 +26148,7 @@ the changes, with cross-references to further details: Functions::). * The `ARGC', `ARGV', `FNR', `RLENGTH', `RSTART', and `SUBSEP' - built-in variables (*note Built-in Variables::). + predefined variables (*note Built-in Variables::). * Assignable `$0' (*note Changing Fields::). @@ -25889,12 +26169,10 @@ the changes, with cross-references to further details: Functions::), rather than using only the first character of `FS'. * Dynamic regexps as operands of the `~' and `!~' operators (*note - Regexp Usage::). + Computed Regexps::). * The escape sequences `\b', `\f', and `\r' (*note Escape - Sequences::). (Some vendors have updated their old versions of - `awk' to recognize `\b', `\f', and `\r', but this is not something - you can rely on.) + Sequences::). * Redirection of input for the `getline' function (*note Getline::). @@ -25918,7 +26196,7 @@ The System V Release 4 (1989) version of Unix `awk' added these features * The `-v' option for assigning variables before program execution begins (*note Options::). - * The `--' option for terminating command-line options. + * The `--' signal for terminating command-line options. * The `\a', `\v', and `\x' escape sequences (*note Escape Sequences::). @@ -25933,8 +26211,8 @@ The System V Release 4 (1989) version of Unix `awk' added these features `printf' function (*note Control Letters::). * The ability to dynamically pass the field width and precision - (`"%*.*d"') in the argument list of the `printf' function (*note - Control Letters::). + (`"%*.*d"') in the argument list of `printf' and `sprintf()' + (*note Control Letters::). * The use of regexp constants, such as `/foo/', as expressions, where they are equivalent to using the matching operator, as in `$0 ~ @@ -25961,8 +26239,8 @@ introduced the following changes into the language: * The concept of a numeric string and tighter comparison rules to go with it (*note Typing and Comparison::). - * The use of built-in variables as function parameter names is - forbidden (*note Definition Syntax::. + * The use of predefined variables as function parameter names is + forbidden (*note Definition Syntax::). * More complete documentation of many of the previously undocumented features of the language. @@ -26024,7 +26302,7 @@ can all be disabled with either the `--traditional' or `--posix' options node summarizes the additional features over POSIX `awk' that are in the current version of `gawk'. - * Additional built-in variables: + * Additional predefined variables: - The `ARGIND' `BINMODE', `ERRNO', `FIELDWIDTHS', `FPAT', `IGNORECASE', `LINT', `PROCINFO', `RT', and `TEXTDOMAIN' @@ -26066,11 +26344,6 @@ the current version of `gawk'. - The `BEGINFILE' and `ENDFILE' special patterns. (*note BEGINFILE/ENDFILE::). - - The ability to delete all of an array at once with `delete - ARRAY' (*note Delete::). - - - The `nextfile' statement (*note Nextfile Statement::). - - The `switch' statement (*note Switch Statement::). * Changes to standard `awk' functions: @@ -26079,7 +26352,7 @@ the current version of `gawk'. one end of a two-way pipe to a coprocess (*note Two-way I/O::). - - POSIX compliance for `gsub()' and `sub()'. + - POSIX compliance for `gsub()' and `sub()' with `--posix'. - The `length()' function accepts an array argument and returns the number of elements in the array (*note String @@ -26098,24 +26371,24 @@ the current version of `gawk'. * Additional functions only in `gawk': - - The `and()', `compl()', `lshift()', `or()', `rshift()', and - `xor()' functions for bit manipulation (*note Bitwise - Functions::). + - The `gensub()', `patsplit()', and `strtonum()' functions for + more powerful text manipulation (*note String Functions::). - The `asort()' and `asorti()' functions for sorting arrays (*note Array Sorting::). - - The `bindtextdomain()', `dcgettext()' and `dcngettext()' - functions for internationalization (*note Programmer i18n::). + - The `mktime()', `systime()', and `strftime()' functions for + working with timestamps (*note Time Functions::). - - The `fflush()' function from BWK `awk' (*note I/O + - The `and()', `compl()', `lshift()', `or()', `rshift()', and + `xor()' functions for bit manipulation (*note Bitwise Functions::). - - The `gensub()', `patsplit()', and `strtonum()' functions for - more powerful text manipulation (*note String Functions::). + - The `isarray()' function to check if a variable is an array + or not (*note Type Functions::). - - The `mktime()', `systime()', and `strftime()' functions for - working with timestamps (*note Time Functions::). + - The `bindtextdomain()', `dcgettext()' and `dcngettext()' + functions for internationalization (*note Programmer i18n::). * Changes and/or additions in the command-line options: @@ -26167,10 +26440,12 @@ the current version of `gawk'. * Support for the following obsolete systems was removed from the - code and the documentation for `gawk' version 4.1: + code for `gawk' version 4.1: - Ultrix + * Support for MirBSD was removed at `gawk' version 4.2. + File: gawk.info, Node: Feature History, Next: Common Extensions, Prev: POSIX/GNU, Up: Language History @@ -26563,30 +26838,26 @@ File: gawk.info, Node: Common Extensions, Next: Ranges and Locales, Prev: Fea A.7 Common Extensions Summary ============================= -This minor node summarizes the common extensions supported by `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 --------------------------------------------------------- -`\x' Escape sequence X X X -`FS' as null string X X X -`/dev/stdin' special file X X X -`/dev/stdout' special file X X X -`/dev/stderr' special file X X X -`delete' without subscript X X X -`fflush()' function X X X -`length()' of an array X X X -`nextfile' statement X X X -`**' and `**=' operators X X -`func' keyword X X -`BINMODE' variable X X -`RS' as regexp X X -Time related functions X X - - (Technically speaking, as of late 2012, `fflush()', `delete ARRAY', -and `nextfile' are no longer extensions, since they have been added to -POSIX.) +The following table summarizes the common extensions supported by +`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 +----------------------------------------------------------------------- +`\x' Escape sequence X X X +`FS' as null string X X X +`/dev/stdin' special file X X X +`/dev/stdout' special file X X X +`/dev/stderr' special file X X X +`delete' without subscript X X X X +`fflush()' function X X X X +`length()' of an array X X X +`nextfile' statement X X X X +`**' and `**=' operators X X +`func' keyword X X +`BINMODE' variable X X +`RS' as regexp X X +Time related functions X X File: gawk.info, Node: Ranges and Locales, Next: Contributors, Prev: Common Extensions, Up: Language History @@ -26627,14 +26898,14 @@ like `[a-dx-z]' is still equivalent to `[abcdxyz]', as in ASCII. But outside those locales, the ordering was defined to be based on "collation order". - In many locales, `A' and `a' are both less 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. + What does that mean? In many locales, `A' and `a' are both less +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 should use `[a-z]' to match a lowercase character. But on systems with -non-ASCII locales, this also matched all of the uppercase characters +non-ASCII locales, this also matches all of the uppercase characters except `A' or `Z'! This was a continuous cause of confusion, even well into the twenty-first century. @@ -26761,7 +27032,7 @@ Info file, in approximate chronological order: various PC platforms. * Christos Zoulas provided the `extension()' built-in function for - dynamically adding new modules. (This was obsoleted at `gawk' + dynamically adding new functions. (This was obsoleted at `gawk' 4.1.) * Ju"rgen Kahrs contributed the initial version of the TCP/IP @@ -26831,6 +27102,9 @@ Info file, in approximate chronological order: 4.1 was driven primarily by Arnold Robbins and Andrew Schorr, with notable contributions from the rest of the development team. + * John Malmberg contributed significant improvements to the OpenVMS + port and the related documentation. + * Antonio Giovanni Colombo rewrote a number of examples in the early chapters that were severely dated, for which I am incredibly grateful. @@ -26881,7 +27155,7 @@ 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 did the respective ports. +people who maintain the respective ports. * Menu: @@ -26924,7 +27198,7 @@ There are two ways to get GNU software: supported. If you have the `wget' program, you can use a command like the following: - wget http://ftp.gnu.org/gnu/gawk/gawk-4.1.1.tar.gz + 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 @@ -26943,25 +27217,25 @@ 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.1.tar.gz'), + 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: - gzip -d -c gawk-4.1.1.tar.gz | tar -xvpf - + gzip -d -c gawk-4.1.2.tar.gz | tar -xvpf - On a system with GNU `tar', you can let `tar' do the decompression for you: - tar -xvpzf gawk-4.1.1.tar.gz + tar -xvpzf gawk-4.1.2.tar.gz -Extracting the archive creates a directory named `gawk-4.1.1' in the +Extracting the archive creates a directory named `gawk-4.1.2' in the current directory. The distribution file name is of the form `gawk-V.R.P.tar.gz'. The V represents the major version of `gawk', the R represents the current release of version V, and the P represents a "patch level", meaning that minor bugs have been fixed in the release. The current patch -level is 1, but when retrieving distributions, you should get the +level is 2, but when retrieving distributions, you should get the version with the highest version, release, and patch level. (Note, however, that patch levels greater than or equal to 70 denote "beta" or nonproduction software; you might not want to retrieve such a version @@ -27172,12 +27446,12 @@ Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin environment for MS-Windows. After you have extracted the `gawk' distribution, `cd' to -`gawk-4.1.1'. Like most GNU software, `gawk' is configured -automatically for your system by running the `configure' program. This -program is a Bourne shell script that is generated automatically using -GNU Autoconf. (The Autoconf software is described fully starting with -*note (Autoconf)Top:: autoconf,Autoconf--Generating Automatic -Configuration Scripts.) +`gawk-4.1.2'. As with most GNU software, you configure `gawk' for your +system by running the `configure' program. This program is a Bourne +shell script that is generated automatically using GNU Autoconf. (The +Autoconf software is described fully starting with *note +(Autoconf)Top:: autoconf,Autoconf--Generating Automatic Configuration +Scripts.) To configure `gawk', simply run `configure': @@ -27240,8 +27514,8 @@ command line when compiling `gawk' from scratch, including: User-modified::) has no effect on the running `awk' program. When used with GCC's automatic dead-code-elimination, this option - cuts almost 200K bytes off the size of the `gawk' executable on - GNU/Linux x86 systems. Results on other systems and with other + cuts almost 23K bytes off the size of the `gawk' executable on + GNU/Linux x86_64 systems. Results on other systems and with other compilers are likely to vary. Using this option may bring you some slight performance improvement. @@ -27327,10 +27601,10 @@ File: gawk.info, Node: PC Installation, Next: VMS Installation, Up: Non-Unix B.3.1 Installation on PC Operating Systems ------------------------------------------ -This minor node covers installation and usage of `gawk' on x86 machines -running MS-DOS, any version of MS-Windows, or OS/2. In this minor -node, the term "Windows32" refers to any of Microsoft -Windows-95/98/ME/NT/2000/XP/Vista/7/8. +This minor node covers installation and usage of `gawk' on Intel +architecture machines running MS-DOS, any version of MS-Windows, or +OS/2. In this minor node, the term "Windows32" refers to any of +Microsoft Windows-95/98/ME/NT/2000/XP/Vista/7/8. The limitations of MS-DOS (and MS-DOS shells under the other operating systems) has meant that various "DOS extenders" are often @@ -27415,7 +27689,7 @@ MS-DOS and Windows32 versions. A list of targets is printed if the `gawk' using the DJGPP tools, enter `make djgpp'. (The DJGPP tools needed for the build may be found at `ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/'.) To build a native -MS-Windows binary of `gawk', type `make mingw32'. +MS-Windows binary of `gawk' using the MinGW tools, type `make mingw32'. The 32 bit EMX version of `gawk' works "out of the box" under OS/2. However, it is highly recommended to use GCC 2.95.3 for the compilation. @@ -27507,8 +27781,8 @@ Networking::). EMX (OS/2 only) supports at least the `|&' operator. The MS-DOS and MS-Windows versions of `gawk' search for program files as described in *note AWKPATH Variable::. However, semicolons (rather than colons) separate elements in the `AWKPATH' variable. If -`AWKPATH' is not set or is empty, then the default search path for -MS-Windows and MS-DOS versions is `.;c:/lib/awk;c:/gnu/lib/awk'. +`AWKPATH' is not set or is empty, then the default search path is +`.;c:/lib/awk;c:/gnu/lib/awk'. The search path for OS/2 (32 bit, EMX) is determined by the prefix directory (most likely `/usr' or `c:/usr') that has been specified as @@ -27532,10 +27806,10 @@ programs) silently translate end-of-line `\r\n' to `\n' on input and `\n' to `\r\n' on output. A special `BINMODE' variable (c.e.) allows control over these translations and is interpreted as follows: - * If `BINMODE' is `"r"', or one, then binary mode is set on read + * If `BINMODE' is `"r"' or one, then binary mode is set on read (i.e., no translations on reads). - * If `BINMODE' is `"w"', or two, then binary mode is set on write + * If `BINMODE' is `"w"' or two, then binary mode is set on write (i.e., no translations on writes). * If `BINMODE' is `"rw"' or `"wr"' or three, binary mode is set for @@ -27599,10 +27873,10 @@ GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, and other GNU programs. Compilation and installation for Cygwin is the same as for a Unix system: - tar -xvpzf gawk-4.1.1.tar.gz - cd gawk-4.1.1 + tar -xvpzf gawk-4.1.2.tar.gz + cd gawk-4.1.2 ./configure - make + make && make check When compared to GNU/Linux on the same system, the `configure' step on Cygwin takes considerably longer. However, it does finish, and then @@ -27620,13 +27894,13 @@ 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. Caveat Emptor! +translation of `"\r\n"', since it won't. File: gawk.info, Node: VMS Installation, Prev: PC Installation, Up: Non-Unix Installation -B.3.2 How to Compile and Install `gawk' on Vax/VMS and OpenVMS --------------------------------------------------------------- +B.3.2 Compiling and Installing `gawk' on Vax/VMS and OpenVMS +------------------------------------------------------------ This node describes how to compile and install `gawk' under VMS. The older designation "VMS" is used throughout to refer to OpenVMS. @@ -27716,7 +27990,7 @@ than 32 bits. /name=(as_is,short) Compile time macros need to be defined before the first VMS-supplied -header file is included. +header file is included, as follows: #if (__CRTL_VER >= 70200000) && !defined (__VAX) #define _LARGEFILE 1 @@ -27730,6 +28004,12 @@ header file is included. #endif #endif + If you are writing your own extensions to run on VMS, you must +supply these definitions yourself. The `config.h' file created when +building `gawk' on VMS does this for you; if instead you use that file +or a similar one, then you must remember to include it before any +VMS-supplied header files. + File: gawk.info, Node: VMS Installation Details, Next: VMS Running, Prev: VMS Dynamic Extensions, Up: VMS Installation @@ -27817,12 +28097,12 @@ 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 to a VMS exit + The `exit' value is a Unix-style value and is encoded into a VMS exit status value when the program exits. The VMS severity bits will be set based on the `exit' value. A failure is indicated by 1 and VMS sets the `ERROR' status. A fatal -error is indicated by 2 and VMS will set the `FATAL' status. All other +error is indicated by 2 and VMS sets the `FATAL' status. All other values will have the `SUCCESS' status. The exit value is encoded to comply with VMS coding standards and will have the `C_FACILITY_NO' of `0x350000' with the constant `0xA000' added to the number shifted over @@ -27835,9 +28115,9 @@ by 3 bits to make room for the severity codes. A C program that uses `exec()' to call `gawk' will get the original Unix-style exit value. - Older versions of `gawk' treated a Unix exit code 0 as 1, a failure -as 2, a fatal error as 4, and passed all the other numbers through. -This violated the VMS exit status coding requirements. + Older versions of `gawk' for VMS treated a Unix exit code 0 as 1, a +failure as 2, a fatal error as 4, and passed all the other numbers +through. This violated the VMS exit status coding requirements. VAX/VMS floating point uses unbiased rounding. *Note Round Function::. @@ -27868,8 +28148,8 @@ reorganized to supply individual PCSI packages for each component. See The normal build procedure for `gawk' produces a program that is suitable for use with GNV. - The `vms/gawk_build_steps.txt' in the source documents the procedure -for building a VMS PCSI kit that is compatible with GNV. + The file `vms/gawk_build_steps.txt' in the distribution documents +the procedure for building a VMS PCSI kit that is compatible with GNV. File: gawk.info, Node: VMS Old Gawk, Prev: VMS GNV, Up: VMS Installation @@ -27898,10 +28178,10 @@ B.4 Reporting Problems and Bugs please report it to the developers; we cannot promise to do anything but we might well want to fix it. - Before reporting a bug, make sure you have actually found a real bug. -Carefully reread the documentation and see if it really 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, 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 documentation! Before reporting a bug or trying to fix it yourself, try to isolate @@ -27915,20 +28195,21 @@ really in the documentation. Please 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, send email to <bug-gawk@gnu.org>. + 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. If necessary, the primary maintainer can be -reached directly at <arnold@skeeve.com>. The bug reporting address is -preferred since the email list is archived at the GNU Project. _All -email should be in English. This is the only language understood in -common by all the maintainers._ +receive your bug report. Although you can send mail to the maintainers +directly, the bug reporting address is preferred since 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 official recognized ways for reporting bugs. Really. + above are the only official 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 @@ -27937,30 +28218,30 @@ common by all the maintainers._ 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' maintainer won't even see + 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 web sites. + 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 me; I will try to help you out, although I -may not have the time to fix the problem. You can send me electronic -mail at the Internet address noted previously. +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 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. +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. - The people maintaining the non-Unix ports of `gawk' are as follows: + The people maintaining the various `gawk' ports are: +Unix and POSIX systems Arnold Robbins, <arnold@skeeve.com>. MS-DOS with DJGPP Scott Deifik, <scottd.mail@sbcglobal.net>. MS-Windows with MinGW Eli Zaretskii, <eliz@gnu.org>. OS/2 Andreas Buening, <andreas.buening@nexgo.de>. -VMS Pat Rankin, <r.pat.rankin@gmail.com>, and John - Malmberg, <wb8tyw@qsl.net>. +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 @@ -27976,7 +28257,7 @@ B.5 Other Freely Available `awk' Implementations `// Do C++ comments work? answer: yes! of course' -- Michael Brennan - There are a number of other freely available `awk' implementations. +There are a number of other freely available `awk' implementations. This minor node briefly describes where to get them: Unix `awk' @@ -28047,9 +28328,9 @@ Unix `awk' `pawk' Nelson H.F. Beebe at the University of Utah has modified BWK `awk' to provide timing and profiling information. It is different from - `gawk' with the `--profile' option. (*note Profiling::), in that - it uses CPU-based profiling, not line-count profiling. You may - find it at either + `gawk' with the `--profile' option (*note Profiling::), in that it + uses CPU-based profiling, not line-count profiling. You may find + it at either `ftp://ftp.math.utah.edu/pub/pawk/pawk-20030606.tar.gz' or `http://www.math.utah.edu/pub/pawk/pawk-20030606.tar.gz'. @@ -28065,11 +28346,11 @@ Busybox Awk The OpenSolaris POSIX `awk' The versions of `awk' in `/usr/xpg4/bin' and `/usr/xpg6/bin' on Solaris are more-or-less POSIX-compliant. They are based on the - `awk' from Mortice Kern Systems for PCs. This author was able to - make this code compile and work under GNU/Linux with 1-2 hours of - work. Making it more generally portable (using GNU Autoconf - and/or Automake) would take more work, and this has not been done, - at least to our knowledge. + `awk' from Mortice Kern Systems for PCs. We were able to make + this code compile and work under GNU/Linux with 1-2 hours of work. + Making it more generally portable (using GNU Autoconf and/or + 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. @@ -28125,9 +28406,9 @@ B.6 Summary * The `gawk' distribution is available from GNU project's main distribution site, `ftp.gnu.org'. The canonical build recipe is: - wget http://ftp.gnu.org/gnu/gawk/gawk-4.1.1.tar.gz - tar -xvpzf gawk-4.1.1.tar.gz - cd gawk-4.1.1 + wget http://ftp.gnu.org/gnu/gawk/gawk-4.1.2.tar.gz + tar -xvpzf gawk-4.1.2.tar.gz + cd gawk-4.1.2 ./configure && make && make check * `gawk' may be built on non-POSIX systems as well. The currently @@ -28258,9 +28539,9 @@ there are several steps that you need to take in order to make it possible to include them: 1. Before building the new feature into `gawk' itself, consider - writing it as an extension module (*note Dynamic Extensions::). - If that's not possible, continue with the rest of the steps in - this list. + writing it as an extension (*note Dynamic Extensions::). If + that's not possible, continue with the rest of the steps in this + list. 2. Be prepared to sign the appropriate paperwork. In order for the FSF to distribute your changes, you must either place those @@ -28427,9 +28708,9 @@ steps: 6. Be willing to continue to maintain the port. Non-Unix operating systems are supported by volunteers who maintain the code needed - to compile and run `gawk' on their systems. If noone volunteers to - maintain a port, it becomes unsupported and it may be necessary to - remove it from the distribution. + to compile and run `gawk' on their systems. If no-one volunteers + to maintain a port, it becomes unsupported and it may be necessary + to remove it from the distribution. 7. Supply an appropriate `gawkmisc.???' file. Each port has its own `gawkmisc.???' that implements certain operating system specific @@ -28484,8 +28765,8 @@ the derived files, because that keeps the repository less cluttered, and it is easier to see the substantive changes when comparing versions and trying to understand what changed between commits. - However, there are two reasons why the `gawk' maintainer likes to -have everything in the repository. + However, there are several reasons why the `gawk' maintainer likes +to have everything in the repository. First, because it is then easy to reproduce any given version completely, without relying upon the availability of (older, likely @@ -28538,6 +28819,13 @@ maintainer is no different than Jane User who wants to try to build Thus, the maintainer thinks that it's not just important, but critical, that for any given branch, the above incantation _just works_. + A third reason to have all the files is that without them, using `git +bisect' to try to find the commit that introduced a bug is exceedingly +difficult. The maintainer tried to do that on another project that +requires running bootstrapping scripts just to create `configure' and +so on; it was really painful. When the repository is self-contained, +using `git bisect' in it is very easy. + What are some of the consequences and/or actions to take? 1. We don't mind that there are differing files in the different @@ -28809,7 +29097,7 @@ C.5.3 Other Design Decisions ---------------------------- As an arbitrary design decision, extensions can read the values of -built-in variables and arrays (such as `ARGV' and `FS'), but cannot +predefined variables and arrays (such as `ARGV' and `FS'), but cannot change them, with the exception of `PROCINFO'. The reason for this is to prevent an extension function from @@ -29376,11 +29664,11 @@ FDL Field When `awk' reads an input record, it splits the record into pieces separated by whitespace (or by a separator regexp that you can - change by setting the built-in variable `FS'). Such pieces are + change by setting the predefined variable `FS'). Such pieces are called fields. If the pieces are of fixed length, you can use the built-in variable `FIELDWIDTHS' to describe their lengths. If you wish to specify the contents of fields instead of the field - separator, you can use the built-in variable `FPAT' to do so. + separator, you can use the predefined variable `FPAT' to do so. (*Note Field Separators::, *note Constant Size::, and *note Splitting By Content::.) @@ -29397,7 +29685,7 @@ Format Format strings control the appearance of output in the `strftime()' and `sprintf()' functions, and in the `printf' statement as well. Also, data conversions from numbers to strings - are controlled by the format strings contained in the built-in + are controlled by the format strings contained in the predefined variables `CONVFMT' and `OFMT'. (*Note Control Letters::.) Free Documentation License @@ -30964,7 +31252,7 @@ Index * Menu: -* ! (exclamation point), ! operator: Boolean Ops. (line 67) +* ! (exclamation point), ! operator: Boolean Ops. (line 69) * ! (exclamation point), ! operator <1>: Egrep Program. (line 175) * ! (exclamation point), ! operator <2>: Ranges. (line 48) * ! (exclamation point), ! operator: Precedence. (line 52) @@ -30977,10 +31265,9 @@ Index * ! (exclamation point), !~ operator <3>: Comparison Operators. (line 11) * ! (exclamation point), !~ operator <4>: Regexp Constants. (line 6) -* ! (exclamation point), !~ operator <5>: Computed Regexps. (line 6) -* ! (exclamation point), !~ operator <6>: Case-sensitivity. (line 26) +* ! (exclamation point), !~ operator <5>: Case-sensitivity. (line 26) +* ! (exclamation point), !~ operator <6>: Computed Regexps. (line 6) * ! (exclamation point), !~ operator: Regexp Usage. (line 19) -* " (double quote) in shell commands: Read Terminal. (line 25) * " (double quote), in regexp constants: Computed Regexps. (line 29) * " (double quote), in shell commands: Quoting. (line 54) * # (number sign), #! (executable scripts): Executable Scripts. @@ -30995,22 +31282,22 @@ Index * % (percent sign), %= operator <1>: Precedence. (line 95) * % (percent sign), %= operator: Assignment Ops. (line 130) * & (ampersand), && operator <1>: Precedence. (line 86) -* & (ampersand), && operator: Boolean Ops. (line 57) +* & (ampersand), && operator: Boolean Ops. (line 59) * & (ampersand), gsub()/gensub()/sub() functions and: Gory Details. (line 6) * ' (single quote): One-shot. (line 15) -* ' (single quote) in gawk command lines: Long. (line 33) +* ' (single quote) in gawk command lines: Long. (line 35) * ' (single quote), in shell commands: Quoting. (line 48) * ' (single quote), vs. apostrophe: Comments. (line 27) -* ' (single quote), with double quotes: Quoting. (line 70) +* ' (single quote), with double quotes: Quoting. (line 73) * () (parentheses), in a profile: Profiling. (line 146) -* () (parentheses), regexp operator: Regexp Operators. (line 80) +* () (parentheses), regexp operator: Regexp Operators. (line 81) * * (asterisk), * operator, as multiplication operator: Precedence. (line 55) * * (asterisk), * operator, as regexp operator: Regexp Operators. - (line 88) -* * (asterisk), * operator, null strings, matching: Gory Details. - (line 143) + (line 89) +* * (asterisk), * operator, null strings, matching: String Functions. + (line 535) * * (asterisk), ** operator <1>: Precedence. (line 49) * * (asterisk), ** operator: Arithmetic Ops. (line 81) * * (asterisk), **= operator <1>: Precedence. (line 95) @@ -31022,7 +31309,7 @@ Index * + (plus sign), ++ operator: Increment Ops. (line 11) * + (plus sign), += operator <1>: Precedence. (line 95) * + (plus sign), += operator: Assignment Ops. (line 82) -* + (plus sign), regexp operator: Regexp Operators. (line 103) +* + (plus sign), regexp operator: Regexp Operators. (line 105) * , (comma), in range patterns: Ranges. (line 6) * - (hyphen), - operator: Precedence. (line 52) * - (hyphen), -- operator <1>: Precedence. (line 46) @@ -31054,30 +31341,30 @@ Index * --include option: Options. (line 159) * --lint option <1>: Options. (line 185) * --lint option: Command Line. (line 20) -* --lint-old option: Options. (line 293) +* --lint-old option: Options. (line 295) * --load option: Options. (line 173) * --non-decimal-data option <1>: Nondecimal Data. (line 6) * --non-decimal-data option: Options. (line 211) * --non-decimal-data option, strtonum() function and: Nondecimal Data. - (line 36) -* --optimize option: Options. (line 235) -* --posix option: Options. (line 252) -* --posix option, --traditional option and: Options. (line 271) -* --pretty-print option: Options. (line 224) + (line 35) +* --optimize option: Options. (line 237) +* --posix option: Options. (line 254) +* --posix option, --traditional option and: Options. (line 273) +* --pretty-print option: Options. (line 226) * --profile option <1>: Profiling. (line 12) -* --profile option: Options. (line 240) -* --re-interval option: Options. (line 277) -* --sandbox option: Options. (line 284) +* --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 97) + (line 96) * --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 271) -* --use-lc-numeric option: Options. (line 219) -* --version option: Options. (line 298) +* --traditional option, --posix option and: Options. (line 273) +* --use-lc-numeric option: Options. (line 221) +* --version option: Options. (line 300) * --with-whiny-user-strftime configuration option: Additional Configuration Options. (line 35) * -b option: Options. (line 68) @@ -31085,42 +31372,42 @@ Index * -c option: Options. (line 81) * -D option: Options. (line 108) * -d option: Options. (line 93) -* -e option: Options. (line 333) +* -e option: Options. (line 336) * -E option: Options. (line 125) * -e option: Options. (line 117) * -f option: Options. (line 25) * -F option: Options. (line 21) * -f option: Long. (line 12) -* -F option, -Ft sets FS to TAB: Options. (line 306) +* -F option, -Ft sets FS to TAB: Options. (line 308) * -F option, command-line: Command Line Field Separator. (line 6) -* -f option, multiple uses: Options. (line 311) +* -f option, multiple uses: Options. (line 313) * -g option: Options. (line 147) * -h option: Options. (line 154) * -i option: Options. (line 159) -* -L option: Options. (line 293) +* -L option: Options. (line 295) * -l option: Options. (line 173) * -M option: Options. (line 205) -* -N option: Options. (line 219) +* -N option: Options. (line 221) * -n option: Options. (line 211) -* -O option: Options. (line 235) -* -o option: Options. (line 224) -* -P option: Options. (line 252) -* -p option: Options. (line 240) -* -r option: Options. (line 277) -* -S option: Options. (line 284) +* -O option: Options. (line 237) +* -o option: Options. (line 226) +* -P option: Options. (line 254) +* -p option: Options. (line 242) +* -r option: Options. (line 279) +* -S option: Options. (line 286) * -v option: Assignment Options. (line 12) -* -V option: Options. (line 298) +* -V option: Options. (line 300) * -v option: Options. (line 32) * -W option: Options. (line 46) * . (period), regexp operator: Regexp Operators. (line 44) * .gmo files: Explaining gettext. (line 42) * .gmo files, specifying directory of <1>: Programmer i18n. (line 47) * .gmo files, specifying directory of: Explaining gettext. (line 54) -* .mo files, converting from .po: I18N Example. (line 63) +* .mo files, converting from .po: I18N Example. (line 64) * .po files <1>: Translator i18n. (line 6) * .po files: Explaining gettext. (line 37) -* .po files, converting to .mo: I18N Example. (line 63) +* .po files, converting to .mo: I18N Example. (line 64) * .pot files: Explaining gettext. (line 31) * / (forward slash) to enclose regular expressions: Regexp. (line 10) * / (forward slash), / operator: Precedence. (line 55) @@ -31130,8 +31417,8 @@ Index (line 148) * / (forward slash), patterns and: Expression Patterns. (line 24) * /= operator vs. /=.../ regexp constant: Assignment Ops. (line 148) -* /dev/... special files: Special FD. (line 46) -* /dev/fd/N special files (gawk): Special FD. (line 46) +* /dev/... special files: Special FD. (line 48) +* /dev/fd/N special files (gawk): Special FD. (line 48) * /inet/... special files (gawk): TCP/IP Networking. (line 6) * /inet4/... special files (gawk): TCP/IP Networking. (line 6) * /inet6/... special files (gawk): TCP/IP Networking. (line 6) @@ -31165,11 +31452,14 @@ Index * ? (question mark), ?: operator: Precedence. (line 92) * ? (question mark), regexp operator <1>: GNU Regexp Operators. (line 59) -* ? (question mark), regexp operator: Regexp Operators. (line 112) +* ? (question mark), regexp operator: Regexp Operators. (line 111) +* @-notation for indirect function calls: Indirect Calls. (line 47) +* @include directive: Include Files. (line 8) +* @load directive: Loading Shared Libraries. + (line 8) * [] (square brackets), regexp operator: Regexp Operators. (line 56) * \ (backslash): Comments. (line 50) -* \ (backslash) in shell commands: Read Terminal. (line 25) -* \ (backslash), \" escape sequence: Escape Sequences. (line 82) +* \ (backslash), \" escape sequence: Escape Sequences. (line 84) * \ (backslash), \' operator (gawk): GNU Regexp Operators. (line 56) * \ (backslash), \/ escape sequence: Escape Sequences. (line 75) @@ -31201,8 +31491,7 @@ Index * \ (backslash), \y operator (gawk): GNU Regexp Operators. (line 38) * \ (backslash), as field separator: Command Line Field Separator. - (line 27) -* \ (backslash), continuing lines and <1>: Egrep Program. (line 223) + (line 24) * \ (backslash), continuing lines and: Statements/Lines. (line 19) * \ (backslash), continuing lines and, comments and: Statements/Lines. (line 76) @@ -31213,7 +31502,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 118) + (line 120) * \ (backslash), in regexp constants: Computed Regexps. (line 29) * \ (backslash), in shell commands: Quoting. (line 48) * \ (backslash), regexp operator: Regexp Operators. (line 18) @@ -31265,12 +31554,12 @@ Index * ambiguity, syntactic: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 148) * ampersand (&), && operator <1>: Precedence. (line 86) -* ampersand (&), && operator: Boolean Ops. (line 57) +* ampersand (&), && operator: Boolean Ops. (line 59) * ampersand (&), gsub()/gensub()/sub() functions and: Gory Details. (line 6) -* anagram.awk program: Anagram Program. (line 22) +* anagram.awk program: Anagram Program. (line 21) * anagrams, finding: Anagram Program. (line 6) -* and: Bitwise Functions. (line 39) +* and: Bitwise Functions. (line 40) * AND bitwise operation: Bitwise Functions. (line 6) * and Boolean-logic operator: Boolean Ops. (line 6) * ANSI: Glossary. (line 34) @@ -31286,33 +31575,33 @@ Index * arctangent: Numeric Functions. (line 11) * ARGC/ARGV variables: Auto-set. (line 15) * ARGC/ARGV variables, command-line arguments: Other Arguments. - (line 12) + (line 15) * ARGC/ARGV variables, how to use: ARGC and ARGV. (line 6) -* ARGC/ARGV variables, portability and: Executable Scripts. (line 42) +* ARGC/ARGV variables, portability and: Executable Scripts. (line 59) * ARGIND variable: Auto-set. (line 44) -* ARGIND variable, command-line arguments: Other Arguments. (line 12) +* ARGIND variable, command-line arguments: Other Arguments. (line 15) * arguments, command-line <1>: ARGC and ARGV. (line 6) * arguments, command-line <2>: Auto-set. (line 15) * arguments, command-line: Other Arguments. (line 6) * arguments, command-line, invoking awk: Command Line. (line 6) * arguments, in function calls: Function Calls. (line 18) * arguments, processing: Getopt Function. (line 6) -* ARGV array, indexing into: Other Arguments. (line 12) +* ARGV array, indexing into: Other Arguments. (line 15) * arithmetic operators: Arithmetic Ops. (line 6) * array manipulation in extensions: Array Manipulation. (line 6) * array members: Reference to Elements. (line 6) * array scanning order, controlling: Controlling Scanning. (line 14) -* array, number of elements: String Functions. (line 197) +* array, number of elements: String Functions. (line 200) * 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 92) +* arrays, and IGNORECASE variable: Array Intro. (line 94) * arrays, as parameters to functions: Pass By Value/Reference. (line 47) * arrays, associative: Array Intro. (line 50) -* arrays, associative, library functions and: Library Names. (line 57) +* arrays, associative, library functions and: Library Names. (line 58) * arrays, deleting entire contents: Delete. (line 39) * arrays, elements that don't exist: Reference to Elements. (line 23) @@ -31320,13 +31609,12 @@ 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 42) +* arrays, elements, retrieving number of: String Functions. (line 41) * arrays, for statement and: Scanning an Array. (line 20) * arrays, indexing: Array Intro. (line 50) * arrays, merging into strings: Join Function. (line 6) * arrays, multidimensional: Multidimensional. (line 10) * arrays, multidimensional, scanning: Multiscanning. (line 11) -* arrays, names of, and names of functions/variables: Arrays. (line 18) * arrays, numeric subscripts: Numeric Array Subscripts. (line 6) * arrays, referencing elements: Reference to Elements. @@ -31336,7 +31624,7 @@ Index (line 6) * arrays, sorting, and IGNORECASE variable: Array Sorting Functions. (line 83) -* arrays, sparse: Array Intro. (line 71) +* arrays, sparse: Array Intro. (line 72) * arrays, subscripts, uninitialized variables as: Uninitialized Subscripts. (line 6) * arrays, unassigned elements: Reference to Elements. @@ -31347,12 +31635,12 @@ Index * ASCII: Ordinal Functions. (line 45) * asort <1>: Array Sorting Functions. (line 6) -* asort: String Functions. (line 42) +* asort: String Functions. (line 41) * asort() function (gawk), arrays, sorting: Array Sorting Functions. (line 6) * asorti <1>: Array Sorting Functions. (line 6) -* asorti: String Functions. (line 42) +* asorti: String Functions. (line 41) * asorti() function (gawk), arrays, sorting: Array Sorting Functions. (line 6) * assert() function (C library): Assert Function. (line 6) @@ -31368,9 +31656,9 @@ Index * asterisk (*), * operator, as multiplication operator: Precedence. (line 55) * asterisk (*), * operator, as regexp operator: Regexp Operators. - (line 88) -* asterisk (*), * operator, null strings, matching: Gory Details. - (line 143) + (line 89) +* asterisk (*), * operator, null strings, matching: String Functions. + (line 535) * asterisk (*), ** operator <1>: Precedence. (line 49) * asterisk (*), ** operator: Arithmetic Ops. (line 81) * asterisk (*), **= operator <1>: Precedence. (line 95) @@ -31382,11 +31670,11 @@ Index * awf (amazingly workable formatter) program: Glossary. (line 24) * awk debugging, enabling: Options. (line 108) * awk language, POSIX version: Assignment Ops. (line 137) -* awk profiling, enabling: Options. (line 240) +* awk profiling, enabling: Options. (line 242) * awk programs <1>: Two Rules. (line 6) * awk programs <2>: Executable Scripts. (line 6) * awk programs: Getting Started. (line 12) -* awk programs, complex: When. (line 29) +* awk programs, complex: When. (line 27) * awk programs, documenting <1>: Library Names. (line 6) * awk programs, documenting: Comments. (line 6) * awk programs, examples of: Sample Programs. (line 6) @@ -31408,7 +31696,7 @@ Index * awk, gawk and <1>: This Manual. (line 14) * awk, gawk and: Preface. (line 21) * awk, history of: History. (line 17) -* awk, implementation issues, pipes: Redirection. (line 135) +* awk, implementation issues, pipes: Redirection. (line 129) * awk, implementations: Other Versions. (line 6) * awk, implementations, limits: Getline Notes. (line 14) * awk, invoking: Command Line. (line 6) @@ -31417,14 +31705,13 @@ Index * awk, POSIX and: Preface. (line 21) * awk, POSIX and, See Also POSIX awk: Preface. (line 21) * awk, regexp constants and: Comparison Operators. - (line 102) + (line 103) * awk, See Also gawk: Preface. (line 34) * awk, terms describing: This Manual. (line 6) * awk, uses for <1>: When. (line 6) * awk, uses for <2>: Getting Started. (line 12) * awk, uses for: Preface. (line 21) -* awk, versions of <1>: V7/SVR3.1. (line 6) -* awk, versions of: Names. (line 10) +* awk, versions of: V7/SVR3.1. (line 6) * awk, versions of, changes between SVR3.1 and SVR4: SVR4. (line 6) * awk, versions of, changes between SVR4 and POSIX awk: POSIX. (line 6) @@ -31441,8 +31728,7 @@ Index * awkvars.out file: Options. (line 93) * b debugger command (alias for break): Breakpoint Control. (line 11) * backslash (\): Comments. (line 50) -* backslash (\) in shell commands: Read Terminal. (line 25) -* backslash (\), \" escape sequence: Escape Sequences. (line 82) +* backslash (\), \" escape sequence: Escape Sequences. (line 84) * backslash (\), \' operator (gawk): GNU Regexp Operators. (line 56) * backslash (\), \/ escape sequence: Escape Sequences. (line 75) @@ -31474,8 +31760,7 @@ Index * backslash (\), \y operator (gawk): GNU Regexp Operators. (line 38) * backslash (\), as field separator: Command Line Field Separator. - (line 27) -* backslash (\), continuing lines and <1>: Egrep Program. (line 223) + (line 24) * backslash (\), continuing lines and: Statements/Lines. (line 19) * backslash (\), continuing lines and, comments and: Statements/Lines. (line 76) @@ -31486,7 +31771,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 118) + (line 120) * backslash (\), in regexp constants: Computed Regexps. (line 29) * backslash (\), in shell commands: Quoting. (line 48) * backslash (\), regexp operator: Regexp Operators. (line 18) @@ -31504,20 +31789,20 @@ Index * BEGIN pattern, getline and: Getline Notes. (line 19) * BEGIN pattern, headings, adding: Print Examples. (line 43) * BEGIN pattern, next/nextfile statements and <1>: Next Statement. - (line 45) + (line 44) * BEGIN pattern, next/nextfile statements and: I/O And BEGIN/END. - (line 36) + (line 37) * BEGIN pattern, OFS/ORS variables, assigning values to: Output Separators. (line 20) * 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) -* BEGIN pattern, running awk programs and: Cut Program. (line 68) +* BEGIN pattern, running awk programs and: Cut Program. (line 63) * BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n. (line 60) * BEGINFILE pattern: BEGINFILE/ENDFILE. (line 6) * BEGINFILE pattern, Boolean patterns and: Expression Patterns. (line 70) -* beginfile() user-defined function: Filetrans Function. (line 62) +* beginfile() user-defined function: Filetrans Function. (line 61) * Bentley, Jon: Glossary. (line 143) * Benzinger, Michael: Contributors. (line 97) * Berry, Karl <1>: Ranges and Locales. (line 74) @@ -31531,11 +31816,11 @@ Index * BINMODE variable <1>: PC Using. (line 33) * BINMODE variable: User-modified. (line 15) * bit-manipulation functions: Bitwise Functions. (line 6) -* bits2str() user-defined function: Bitwise Functions. (line 70) -* bitwise AND: Bitwise Functions. (line 39) -* bitwise complement: Bitwise Functions. (line 43) -* bitwise OR: Bitwise Functions. (line 49) -* bitwise XOR: Bitwise Functions. (line 55) +* bits2str() user-defined function: Bitwise Functions. (line 71) +* bitwise AND: Bitwise Functions. (line 40) +* bitwise complement: Bitwise Functions. (line 44) +* bitwise OR: Bitwise Functions. (line 50) +* bitwise XOR: Bitwise Functions. (line 56) * bitwise, complement: Bitwise Functions. (line 25) * bitwise, operations: Bitwise Functions. (line 6) * bitwise, shift: Bitwise Functions. (line 32) @@ -31551,15 +31836,15 @@ Index * bracket expressions <1>: Bracket Expressions. (line 6) * bracket expressions: Regexp Operators. (line 56) * bracket expressions, character classes: Bracket Expressions. - (line 30) + (line 32) * bracket expressions, collating elements: Bracket Expressions. - (line 77) + (line 79) * bracket expressions, collating symbols: Bracket Expressions. - (line 84) + (line 86) * bracket expressions, complemented: Regexp Operators. (line 64) * bracket expressions, equivalence classes: Bracket Expressions. - (line 90) -* bracket expressions, non-ASCII: Bracket Expressions. (line 77) + (line 92) +* bracket expressions, non-ASCII: Bracket Expressions. (line 79) * bracket expressions, range expressions: Bracket Expressions. (line 6) * break debugger command: Breakpoint Control. (line 11) @@ -31575,12 +31860,12 @@ Index * Brennan, Michael <1>: Other Versions. (line 6) * Brennan, Michael <2>: Simple Sed. (line 25) * Brennan, Michael <3>: Delete. (line 56) -* Brennan, Michael <4>: Acknowledgments. (line 76) +* Brennan, Michael <4>: Acknowledgments. (line 78) * Brennan, Michael: Foreword. (line 83) * 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 490) -* Brian Kernighan's awk <4>: Delete. (line 48) +* Brian Kernighan's awk <3>: String Functions. (line 491) +* 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) * Brian Kernighan's awk <7>: Break Statement. (line 51) @@ -31591,7 +31876,7 @@ Index (line 67) * Brian Kernighan's awk <12>: GNU Regexp Operators. (line 83) -* Brian Kernighan's awk <13>: Escape Sequences. (line 122) +* Brian Kernighan's awk <13>: Escape Sequences. (line 124) * 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) @@ -31601,12 +31886,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 71) +* Buening, Andreas <1>: Bugs. (line 72) * 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 140) -* buffering, interactive vs. noninteractive: I/O Functions. (line 109) +* buffering, input/output: I/O Functions. (line 139) +* buffering, interactive vs. noninteractive: I/O Functions. (line 108) * buffers, flushing: I/O Functions. (line 32) * buffers, operators for: GNU Regexp Operators. (line 48) @@ -31614,11 +31899,8 @@ 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) -* built-in variables: Built-in Variables. (line 6) -* built-in variables, -v option, setting with: Options. (line 40) -* built-in variables, conveying information: Auto-set. (line 6) -* built-in variables, user-modifiable: User-modified. (line 6) * Busybox Awk: Other Versions. (line 88) +* c.e., See common extensions: Conventions. (line 51) * call by reference: Pass By Value/Reference. (line 47) * call by value: Pass By Value/Reference. @@ -31634,8 +31916,8 @@ Index * case keyword: Switch Statement. (line 6) * 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 92) -* case sensitivity, converting case: String Functions. (line 520) +* case sensitivity, array indices and: Array Intro. (line 94) +* case sensitivity, converting case: String Functions. (line 521) * case sensitivity, example programs: Library Functions. (line 53) * case sensitivity, gawk: Case-sensitivity. (line 26) * case sensitivity, regexps and: Case-sensitivity. (line 6) @@ -31671,14 +31953,14 @@ Index * close() function, portability: Close Files And Pipes. (line 81) * close() function, return value: Close Files And Pipes. - (line 131) + (line 132) * close() function, two-way pipes and: Two-way I/O. (line 59) * Close, Diane <1>: Contributors. (line 20) * Close, Diane: Manual History. (line 34) * Collado, Manuel: Acknowledgments. (line 60) -* collating elements: Bracket Expressions. (line 77) -* collating symbols: Bracket Expressions. (line 84) -* Colombo, Antonio <1>: Contributors. (line 137) +* collating elements: Bracket Expressions. (line 79) +* collating symbols: Bracket Expressions. (line 86) +* Colombo, Antonio <1>: Contributors. (line 140) * Colombo, Antonio: Acknowledgments. (line 60) * columns, aligning: Print Examples. (line 70) * columns, cutting: Cut Program. (line 6) @@ -31707,15 +31989,15 @@ Index * commenting, backslash continuation and: Statements/Lines. (line 76) * common extensions, ** operator: Arithmetic Ops. (line 30) * common extensions, **= operator: Assignment Ops. (line 137) -* common extensions, /dev/stderr special file: Special FD. (line 46) -* common extensions, /dev/stdin special file: Special FD. (line 46) -* common extensions, /dev/stdout special file: Special FD. (line 46) +* common extensions, /dev/stderr special file: Special FD. (line 48) +* common extensions, /dev/stdin special file: Special FD. (line 48) +* common extensions, /dev/stdout special file: Special FD. (line 48) * common extensions, \x escape sequence: Escape Sequences. (line 61) * common extensions, BINMODE variable: PC Using. (line 33) * common extensions, delete to delete entire arrays: Delete. (line 39) -* common extensions, func keyword: Definition Syntax. (line 89) +* common extensions, func keyword: Definition Syntax. (line 93) * common extensions, length() applied to an array: String Functions. - (line 197) + (line 200) * common extensions, RS as a regexp: gawk split records. (line 6) * common extensions, single character fields: Single Character Fields. (line 6) @@ -31724,7 +32006,7 @@ Index (line 9) * comparison expressions, as patterns: Expression Patterns. (line 14) * comparison expressions, string vs. regexp: Comparison Operators. - (line 78) + (line 79) * compatibility mode (gawk), extensions: POSIX/GNU. (line 6) * compatibility mode (gawk), file names: Special Caveats. (line 9) * compatibility mode (gawk), hexadecimal numbers: Nondecimal-numbers. @@ -31738,7 +32020,7 @@ Index * compiling gawk for MS-DOS and MS-Windows: PC Compiling. (line 13) * compiling gawk for VMS: VMS Compilation. (line 6) * compiling gawk with EMX for OS/2: PC Compiling. (line 28) -* compl: Bitwise Functions. (line 43) +* compl: Bitwise Functions. (line 44) * complement, bitwise: Bitwise Functions. (line 25) * compound statements, control statements and: Statements. (line 10) * concatenating: Concatenation. (line 8) @@ -31764,15 +32046,15 @@ Index * control statements: Statements. (line 6) * controlling array scanning order: Controlling Scanning. (line 14) -* convert string to lower case: String Functions. (line 521) -* convert string to number: String Functions. (line 388) -* convert string to upper case: String Functions. (line 527) +* 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) * converting integer array subscripts: Numeric Array Subscripts. (line 31) * converting, dates to timestamps: Time Functions. (line 76) -* converting, numbers to strings <1>: Bitwise Functions. (line 109) +* converting, numbers to strings <1>: Bitwise Functions. (line 110) * converting, numbers to strings: Strings And Numbers. (line 6) -* converting, strings to numbers <1>: Bitwise Functions. (line 109) +* converting, strings to numbers <1>: Bitwise Functions. (line 110) * converting, strings to numbers: Strings And Numbers. (line 6) * CONVFMT variable <1>: User-modified. (line 30) * CONVFMT variable: Strings And Numbers. (line 29) @@ -31780,7 +32062,7 @@ Index (line 6) * cookie: Glossary. (line 149) * coprocesses <1>: Two-way I/O. (line 25) -* coprocesses: Redirection. (line 102) +* coprocesses: Redirection. (line 96) * coprocesses, closing: Close Files And Pipes. (line 6) * coprocesses, getline from: Getline/Coprocess. (line 6) @@ -31788,7 +32070,7 @@ Index * cosine: Numeric Functions. (line 15) * counting: Wc Program. (line 6) * csh utility: Statements/Lines. (line 44) -* csh utility, POSIXLY_CORRECT environment variable: Options. (line 351) +* csh utility, POSIXLY_CORRECT environment variable: Options. (line 354) * csh utility, |& operator, comparison with: Two-way I/O. (line 25) * ctime() user-defined function: Function Example. (line 74) * currency symbols, localization: Explaining gettext. (line 104) @@ -31813,25 +32095,25 @@ Index (line 43) * dark corner, break statement: Break Statement. (line 51) * dark corner, close() function: Close Files And Pipes. - (line 131) + (line 132) * 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) -* dark corner, escape sequences: Other Arguments. (line 31) +* dark corner, escape sequences: Other Arguments. (line 38) * dark corner, escape sequences, for metacharacters: Escape Sequences. - (line 140) + (line 142) * 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, FILENAME variable: Getline Notes. (line 19) -* dark corner, FNR/NR variables: Auto-set. (line 309) +* dark corner, FNR/NR variables: Auto-set. (line 321) * 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 110) +* dark corner, input files: awk split records. (line 111) * dark corner, invoking awk: Command Line. (line 16) -* dark corner, length() function: String Functions. (line 183) +* dark corner, length() function: String Functions. (line 186) * dark corner, locale's decimal point character: Locale influences conversions. (line 17) * dark corner, multiline records: Multiple Line. (line 35) @@ -31843,7 +32125,7 @@ Index (line 148) * dark corner, regexp constants, as arguments to user-defined functions: Using Constant Regexps. (line 43) -* dark corner, split() function: String Functions. (line 359) +* dark corner, split() function: String Functions. (line 360) * 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) @@ -31857,7 +32139,7 @@ Index (line 112) * Davies, Stephen <1>: Contributors. (line 74) * Davies, Stephen: Acknowledgments. (line 60) -* Day, Robert P.J.: Acknowledgments. (line 76) +* Day, Robert P.J.: Acknowledgments. (line 78) * dcgettext <1>: Programmer i18n. (line 19) * dcgettext: I18N Functions. (line 22) * dcgettext() function (gawk), portability and: I18N Portability. @@ -31884,7 +32166,7 @@ Index * debugger commands, disable: Breakpoint Control. (line 69) * debugger commands, display: Viewing And Changing Data. (line 8) -* debugger commands, down: Execution Stack. (line 21) +* debugger commands, down: Execution Stack. (line 23) * debugger commands, dump: Miscellaneous Debugger Commands. (line 9) * debugger commands, e (enable): Breakpoint Control. (line 73) @@ -31893,10 +32175,10 @@ Index (line 10) * debugger commands, eval: Viewing And Changing Data. (line 23) -* debugger commands, f (frame): Execution Stack. (line 25) +* debugger commands, f (frame): Execution Stack. (line 27) * debugger commands, finish: Debugger Execution Control. (line 39) -* debugger commands, frame: Execution Stack. (line 25) +* debugger commands, frame: Execution Stack. (line 27) * debugger commands, h (help): Miscellaneous Debugger Commands. (line 66) * debugger commands, help: Miscellaneous Debugger Commands. @@ -31958,11 +32240,12 @@ Index (line 83) * debugger commands, unwatch: Viewing And Changing Data. (line 84) -* debugger commands, up: Execution Stack. (line 34) +* debugger commands, up: Execution Stack. (line 36) * debugger commands, w (watch): Viewing And Changing Data. (line 67) * debugger commands, watch: Viewing And Changing Data. (line 67) +* debugger commands, where (backtrace): Execution Stack. (line 13) * debugger default list amount: Debugger Info. (line 69) * debugger history file: Debugger Info. (line 80) * debugger history size: Debugger Info. (line 65) @@ -31972,10 +32255,10 @@ Index * debugger, read commands from a file: Debugger Info. (line 96) * debugging awk programs: Debugger. (line 6) * debugging gawk, bug reports: Bugs. (line 9) -* decimal point character, locale specific: Options. (line 268) +* 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 71) +* Deifik, Scott <1>: Bugs. (line 72) * Deifik, Scott <2>: Contributors. (line 53) * Deifik, Scott: Acknowledgments. (line 60) * delete ARRAY: Delete. (line 39) @@ -31989,7 +32272,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 197) +* differences between gawk and awk: String Functions. (line 200) * differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV. (line 90) * differences in awk and gawk, ARGIND variable: Auto-set. (line 44) @@ -32012,7 +32295,7 @@ Index * 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, error messages: Special FD. (line 16) +* 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) @@ -32023,48 +32306,48 @@ Index * differences in awk and gawk, IGNORECASE variable: User-modified. (line 76) * differences in awk and gawk, implementation limitations <1>: Redirection. - (line 135) + (line 129) * differences in awk and gawk, implementation limitations: Getline Notes. (line 14) * differences in awk and gawk, indirect function calls: Indirect Calls. (line 6) * differences in awk and gawk, input/output operators <1>: Redirection. - (line 102) + (line 96) * differences in awk and gawk, input/output operators: Getline/Coprocess. (line 6) * differences in awk and gawk, line continuations: Conditional Exp. (line 34) * differences in awk and gawk, LINT variable: User-modified. (line 88) * differences in awk and gawk, match() function: String Functions. - (line 260) + (line 262) * differences in awk and gawk, print/printf statements: Format Modifiers. (line 13) -* differences in awk and gawk, PROCINFO array: Auto-set. (line 136) +* differences in awk and gawk, PROCINFO array: Auto-set. (line 137) * differences in awk and gawk, read timeouts: Read Timeout. (line 6) * differences in awk and gawk, record separators: awk split records. - (line 124) + (line 125) * differences in awk and gawk, regexp constants: Using Constant Regexps. (line 43) * differences in awk and gawk, regular expressions: Case-sensitivity. (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 265) +* differences in awk and gawk, RT variable: Auto-set. (line 272) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. - (line 347) + (line 348) * 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 269) +* differences in awk and gawk, SYMTAB variable: Auto-set. (line 276) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. - (line 152) + (line 151) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. (line 66) * directories, command-line: Command-line directories. (line 6) -* directories, searching: Programs Exercises. (line 63) +* directories, searching: Programs Exercises. (line 70) * directories, searching for loadable extensions: AWKLIBPATH Variable. (line 6) * directories, searching for source files: AWKPATH Variable. (line 6) @@ -32085,11 +32368,11 @@ Index * dollar sign ($), incrementing fields and arrays: Increment Ops. (line 30) * dollar sign ($), regexp operator: Regexp Operators. (line 35) -* double quote (") in shell commands: Read Terminal. (line 25) * double quote ("), in regexp constants: Computed Regexps. (line 29) * double quote ("), in shell commands: Quoting. (line 54) -* down debugger command: Execution Stack. (line 21) +* down debugger command: Execution Stack. (line 23) * Drepper, Ulrich: Acknowledgments. (line 52) +* Duman, Patrice: Acknowledgments. (line 74) * dump all variables of a program: Options. (line 93) * dump debugger command: Miscellaneous Debugger Commands. (line 9) @@ -32098,10 +32381,10 @@ 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 141) -* effective user ID of gawk user: Auto-set. (line 145) +* effective group ID of gawk user: Auto-set. (line 142) +* effective user ID of gawk user: Auto-set. (line 146) * egrep utility <1>: Egrep Program. (line 6) -* egrep utility: Bracket Expressions. (line 24) +* egrep utility: Bracket Expressions. (line 26) * egrep.awk program: Egrep Program. (line 54) * elements in arrays, assigning values: Assigning Elements. (line 6) * elements in arrays, deleting: Delete. (line 6) @@ -32115,7 +32398,7 @@ Index * empty array elements: Reference to Elements. (line 18) * empty pattern: Empty. (line 6) -* empty strings: awk split records. (line 114) +* empty strings: awk split records. (line 115) * empty strings, See null strings: Regexp Field Splitting. (line 43) * enable breakpoint: Breakpoint Control. (line 73) @@ -32127,22 +32410,21 @@ Index * END pattern, and profiling: Profiling. (line 62) * END pattern, assert() user-defined function and: Assert Function. (line 75) -* END pattern, backslash continuation and: Egrep Program. (line 223) * END pattern, Boolean patterns and: Expression Patterns. (line 70) * END pattern, exit statement and: Exit Statement. (line 12) * END pattern, next/nextfile statements and <1>: Next Statement. - (line 45) + (line 44) * END pattern, next/nextfile statements and: I/O And BEGIN/END. - (line 36) + (line 37) * 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() user-defined function: Filetrans Function. (line 62) -* endgrent() function (C library): Group Functions. (line 213) -* endgrent() user-defined function: Group Functions. (line 216) -* endpwent() function (C library): Passwd Functions. (line 210) -* endpwent() user-defined function: Passwd Functions. (line 213) +* endfile() user-defined function: Filetrans Function. (line 61) +* endgrent() function (C library): Group Functions. (line 211) +* endgrent() user-defined function: Group Functions. (line 214) +* endpwent() function (C library): Passwd Functions. (line 207) +* endpwent() user-defined function: Passwd Functions. (line 210) * English, Steve: Advanced Features. (line 6) * ENVIRON array: Auto-set. (line 60) * environment variables used by gawk: Environment Variables. @@ -32153,14 +32435,14 @@ Index * equals sign (=), == operator <1>: Precedence. (line 65) * equals sign (=), == operator: Comparison Operators. (line 11) -* EREs (Extended Regular Expressions): Bracket Expressions. (line 24) +* EREs (Extended Regular Expressions): Bracket Expressions. (line 26) * ERRNO variable <1>: TCP/IP Networking. (line 54) * ERRNO variable: Auto-set. (line 82) * ERRNO variable, with BEGINFILE pattern: BEGINFILE/ENDFILE. (line 26) * ERRNO variable, with close() function: Close Files And Pipes. - (line 139) + (line 140) * ERRNO variable, with getline command: Getline. (line 19) -* error handling: Special FD. (line 16) +* error handling: Special FD. (line 19) * error handling, ERRNO variable and: Auto-set. (line 82) * error output: Special FD. (line 6) * escape processing, gsub()/gensub()/sub() functions: Gory Details. @@ -32176,7 +32458,7 @@ Index * examining fields: Fields. (line 6) * exclamation point (!), ! operator <1>: Egrep Program. (line 175) * exclamation point (!), ! operator <2>: Precedence. (line 52) -* exclamation point (!), ! operator: Boolean Ops. (line 67) +* exclamation point (!), ! operator: Boolean Ops. (line 69) * exclamation point (!), != operator <1>: Precedence. (line 65) * exclamation point (!), != operator: Comparison Operators. (line 11) @@ -32186,8 +32468,8 @@ Index * exclamation point (!), !~ operator <3>: Comparison Operators. (line 11) * exclamation point (!), !~ operator <4>: Regexp Constants. (line 6) -* exclamation point (!), !~ operator <5>: Computed Regexps. (line 6) -* exclamation point (!), !~ operator <6>: Case-sensitivity. (line 26) +* exclamation point (!), !~ operator <5>: Case-sensitivity. (line 26) +* exclamation point (!), !~ operator <6>: Computed Regexps. (line 6) * exclamation point (!), !~ operator: Regexp Usage. (line 19) * exit statement: Exit Statement. (line 6) * exit status, of gawk: Exit Status. (line 6) @@ -32195,8 +32477,8 @@ Index * exit the debugger: Miscellaneous Debugger Commands. (line 99) * exp: Numeric Functions. (line 33) -* expand utility: Very Simple. (line 69) -* Expat XML parser library: gawkextlib. (line 35) +* expand utility: Very Simple. (line 72) +* Expat XML parser library: gawkextlib. (line 31) * exponent: Numeric Functions. (line 33) * expressions: Expressions. (line 6) * expressions, as patterns: Expression Patterns. (line 6) @@ -32208,14 +32490,14 @@ Index * expressions, matching, See comparison expressions: Typing and Comparison. (line 9) * expressions, selecting: Conditional Exp. (line 6) -* Extended Regular Expressions (EREs): Bracket Expressions. (line 24) +* Extended Regular Expressions (EREs): Bracket Expressions. (line 26) * extension API: Extension API Description. (line 6) * extension API informational variables: Extension API Informational Variables. (line 6) * extension API version: Extension Versioning. (line 6) -* extension API, version number: Auto-set. (line 232) +* extension API, version number: Auto-set. (line 239) * extension example: Extension Example. (line 6) * extension registration: Registration Functions. (line 6) @@ -32227,26 +32509,28 @@ Index * extensions, Brian Kernighan's awk: BTL. (line 6) * extensions, common, ** operator: Arithmetic Ops. (line 30) * extensions, common, **= operator: Assignment Ops. (line 137) -* extensions, common, /dev/stderr special file: Special FD. (line 46) -* extensions, common, /dev/stdin special file: Special FD. (line 46) -* extensions, common, /dev/stdout special file: Special FD. (line 46) +* extensions, common, /dev/stderr special file: Special FD. (line 48) +* extensions, common, /dev/stdin special file: Special FD. (line 48) +* extensions, common, /dev/stdout special file: Special FD. (line 48) * extensions, common, \x escape sequence: Escape Sequences. (line 61) * extensions, common, BINMODE variable: PC Using. (line 33) * extensions, common, delete to delete entire arrays: Delete. (line 39) * extensions, common, fflush() function: I/O Functions. (line 43) -* extensions, common, func keyword: Definition Syntax. (line 89) +* extensions, common, func keyword: Definition Syntax. (line 93) * extensions, common, length() applied to an array: String Functions. - (line 197) + (line 200) * extensions, common, RS as a regexp: gawk split records. (line 6) * extensions, common, single character fields: Single Character Fields. (line 6) * extensions, in gawk, not in POSIX awk: POSIX/GNU. (line 6) +* extensions, loading, @load directive: Loading Shared Libraries. + (line 8) * extensions, mawk: Common Extensions. (line 6) * extensions, where to find: gawkextlib. (line 6) * extract.awk program: Extract Program. (line 79) * extraction, of marked strings (internationalization): String Extraction. (line 6) -* f debugger command (alias for frame): Execution Stack. (line 25) +* f debugger command (alias for frame): Execution Stack. (line 27) * false, logical: Truth Values. (line 6) * FDL (Free Documentation License): GNU Free Documentation License. (line 7) @@ -32274,7 +32558,7 @@ Index (line 6) * field separators, regular expressions as: Field Separators. (line 51) * field separators, See Also OFS: Changing Fields. (line 64) -* field separators, spaces as: Cut Program. (line 109) +* field separators, spaces as: Cut Program. (line 103) * fields <1>: Basic High Level. (line 73) * fields <2>: Fields. (line 6) * fields: Reading Files. (line 14) @@ -32291,9 +32575,10 @@ Index * FIELDWIDTHS variable <1>: User-modified. (line 37) * FIELDWIDTHS variable: Constant Size. (line 23) * 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 46) +* file names, standard streams in gawk: Special FD. (line 48) * FILENAME variable <1>: Auto-set. (line 98) * FILENAME variable: Reading Files. (line 6) * FILENAME variable, getline, setting with: Getline Notes. (line 19) @@ -32301,12 +32586,12 @@ Index * files, .gmo: Explaining gettext. (line 42) * files, .gmo, specifying directory of <1>: Programmer i18n. (line 47) * files, .gmo, specifying directory of: Explaining gettext. (line 54) -* files, .mo, converting from .po: I18N Example. (line 63) +* files, .mo, converting from .po: I18N Example. (line 64) * files, .po <1>: Translator i18n. (line 6) * files, .po: Explaining gettext. (line 37) -* files, .po, converting to .mo: I18N Example. (line 63) +* files, .po, converting to .mo: I18N Example. (line 64) * files, .pot: Explaining gettext. (line 31) -* files, /dev/... special files: Special FD. (line 46) +* files, /dev/... special files: Special FD. (line 48) * files, /inet/... (gawk): TCP/IP Networking. (line 6) * files, /inet4/... (gawk): TCP/IP Networking. (line 6) * files, /inet6/... (gawk): TCP/IP Networking. (line 6) @@ -32324,12 +32609,12 @@ Index * files, managing, data file boundaries: Filetrans Function. (line 6) * files, message object: Explaining gettext. (line 42) * files, message object, converting from portable object files: I18N Example. - (line 63) + (line 64) * files, message object, specifying directory of <1>: Programmer i18n. (line 47) * files, message object, specifying directory of: Explaining gettext. (line 54) -* files, multiple passes over: Other Arguments. (line 49) +* files, multiple passes over: Other Arguments. (line 56) * files, multiple, duplicating output into: Tee Program. (line 6) * files, output, See output files: Close Files And Pipes. (line 6) @@ -32338,14 +32623,14 @@ Index * files, portable object: Explaining gettext. (line 37) * files, portable object template: Explaining gettext. (line 31) * files, portable object, converting to message object files: I18N Example. - (line 63) + (line 64) * files, portable object, generating: Options. (line 147) * files, processing, ARGIND variable and: Auto-set. (line 51) * files, reading: Rewind Function. (line 6) * files, reading, multiline records: Multiple Line. (line 6) * files, searching for regular expressions: Egrep Program. (line 6) * files, skipping: File Checking. (line 6) -* files, source, search path for: Programs Exercises. (line 63) +* 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) @@ -32355,7 +32640,7 @@ Index * Fish, Fred: Contributors. (line 50) * fixed-width data: Constant Size. (line 10) * flag variables <1>: Tee Program. (line 20) -* flag variables: Boolean Ops. (line 67) +* flag variables: Boolean Ops. (line 69) * floating-point, numbers, arbitrary precision: Arbitrary Precision Arithmetic. (line 6) * floating-point, VAX/VMS: VMS Running. (line 51) @@ -32364,7 +32649,7 @@ Index (line 12) * FNR variable <1>: Auto-set. (line 107) * FNR variable: Records. (line 6) -* FNR variable, changing: Auto-set. (line 309) +* FNR variable, changing: Auto-set. (line 321) * for statement: For Statement. (line 6) * for statement, looping over arrays: Scanning an Array. (line 20) * fork() extension function: Extension Sample Fork. @@ -32378,7 +32663,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 381) +* formatting strings: String Functions. (line 382) * forward slash (/) to enclose regular expressions: Regexp. (line 10) * forward slash (/), / operator: Precedence. (line 55) * forward slash (/), /= operator <1>: Precedence. (line 95) @@ -32389,7 +32674,7 @@ Index * FPAT variable <1>: User-modified. (line 43) * FPAT variable: Splitting By Content. (line 27) -* frame debugger command: Execution Stack. (line 25) +* frame debugger command: Execution Stack. (line 27) * Free Documentation License (FDL): GNU Free Documentation License. (line 7) * Free Software Foundation (FSF) <1>: Glossary. (line 296) @@ -32401,9 +32686,9 @@ Index * FS variable, --field-separator option and: Options. (line 21) * FS variable, as null string: Single Character Fields. (line 20) -* FS variable, as TAB character: Options. (line 264) +* FS variable, as TAB character: Options. (line 266) * FS variable, changing value of: Field Separators. (line 35) -* FS variable, running awk programs and: Cut Program. (line 68) +* FS variable, running awk programs and: Cut Program. (line 63) * FS variable, setting from command line: Command Line Field Separator. (line 6) * FS, containing ^: Regexp Field Splitting. @@ -32417,6 +32702,7 @@ Index * FUNCTAB array: Auto-set. (line 123) * 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. @@ -32424,10 +32710,10 @@ Index * functions, built-in <1>: Functions. (line 6) * functions, built-in: Function Calls. (line 10) * functions, built-in, evaluation order: Calling Built-in. (line 30) -* functions, defining: Definition Syntax. (line 6) +* functions, defining: Definition Syntax. (line 9) * functions, library: Library Functions. (line 6) * functions, library, assertions: Assert Function. (line 6) -* functions, library, associative arrays and: Library Names. (line 57) +* functions, library, associative arrays and: Library Names. (line 58) * functions, library, C library: Getopt Function. (line 6) * functions, library, character values as numbers: Ordinal Functions. (line 6) @@ -32447,9 +32733,8 @@ Index * functions, library, rounding numbers: Round Function. (line 6) * functions, library, user database, reading: Passwd Functions. (line 6) -* functions, names of <1>: Definition Syntax. (line 20) -* functions, names of: Arrays. (line 18) -* functions, recursive: Definition Syntax. (line 79) +* functions, names of: Definition Syntax. (line 23) +* functions, recursive: Definition Syntax. (line 83) * functions, string-translation: I18N Functions. (line 6) * functions, undefined: Pass By Value/Reference. (line 71) @@ -32460,23 +32745,20 @@ Index * functions, user-defined, next/nextfile statements and <1>: Nextfile Statement. (line 47) * functions, user-defined, next/nextfile statements and: Next Statement. - (line 45) -* G-d: Acknowledgments. (line 92) + (line 44) +* G-d: Acknowledgments. (line 94) * Garfinkle, Scott: Contributors. (line 34) * gawk program, dynamic profiling: Profiling. (line 179) -* gawk version: Auto-set. (line 207) -* gawk, ARGIND variable in: Other Arguments. (line 12) +* gawk version: Auto-set. (line 214) +* 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 39) +* gawk, bitwise operations in: Bitwise Functions. (line 40) * gawk, break statement in: Break Statement. (line 51) -* gawk, built-in variables and: Built-in Variables. (line 14) -* gawk, character classes and: Bracket Expressions. (line 98) +* gawk, character classes and: Bracket Expressions. (line 100) * gawk, coding style in: Adding Code. (line 39) * gawk, command-line options, and regular expressions: GNU Regexp Operators. (line 70) -* gawk, comparison operators and: Comparison Operators. - (line 50) * gawk, configuring: Configuration Philosophy. (line 6) * gawk, configuring, options: Additional Configuration Options. @@ -32488,10 +32770,10 @@ Index * gawk, ERRNO variable in <2>: Auto-set. (line 82) * gawk, ERRNO variable in <3>: BEGINFILE/ENDFILE. (line 26) * gawk, ERRNO variable in <4>: Close Files And Pipes. - (line 139) + (line 140) * gawk, ERRNO variable in: Getline. (line 19) -* gawk, escape sequences: Escape Sequences. (line 130) -* gawk, extensions, disabling: Options. (line 252) +* gawk, escape sequences: Escape Sequences. (line 132) +* 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) @@ -32507,8 +32789,8 @@ Index * 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 58) -* gawk, IGNORECASE variable in <3>: Array Intro. (line 92) +* gawk, IGNORECASE variable in <2>: String Functions. (line 57) +* 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) * gawk, implementation issues: Notes. (line 6) @@ -32516,13 +32798,13 @@ Index * gawk, implementation issues, downward compatibility: Compatibility Mode. (line 6) * gawk, implementation issues, limits: Getline Notes. (line 14) -* gawk, implementation issues, pipes: Redirection. (line 135) +* gawk, implementation issues, pipes: Redirection. (line 129) * gawk, installing: Installation. (line 6) * gawk, internationalization and, See internationalization: Internationalization. (line 13) * gawk, interpreter, adding code to: Using Internal File Ops. (line 6) -* gawk, interval expressions and: Regexp Operators. (line 140) +* gawk, interval expressions and: Regexp Operators. (line 139) * gawk, line continuation in: Conditional Exp. (line 34) * gawk, LINT variable in: User-modified. (line 88) * gawk, list of contributors to: Contributors. (line 6) @@ -32531,28 +32813,29 @@ Index * gawk, newlines in: Statements/Lines. (line 12) * gawk, octal numbers and: Nondecimal-numbers. (line 42) * gawk, OS/2 version of: PC Using. (line 16) +* 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 136) +* gawk, PROCINFO array in: Auto-set. (line 137) * gawk, regexp constants and: Using Constant Regexps. (line 28) * gawk, regular expressions, case sensitivity: Case-sensitivity. (line 26) * gawk, regular expressions, operators: GNU Regexp Operators. (line 6) -* gawk, regular expressions, precedence: Regexp Operators. (line 162) -* gawk, RT variable in <1>: Auto-set. (line 265) +* gawk, regular expressions, precedence: Regexp Operators. (line 161) +* gawk, RT variable in <1>: Auto-set. (line 272) * gawk, RT variable in <2>: Multiple Line. (line 129) -* gawk, RT variable in: awk split records. (line 124) +* 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, string-translation functions: I18N Functions. (line 6) -* gawk, SYMTAB array in: Auto-set. (line 269) -* gawk, TEXTDOMAIN variable in: User-modified. (line 152) +* gawk, SYMTAB array in: Auto-set. (line 276) +* gawk, TEXTDOMAIN variable in: User-modified. (line 151) * gawk, timestamps: Time Functions. (line 6) * gawk, uses for: Preface. (line 34) -* gawk, versions of, information about, printing: Options. (line 298) +* gawk, versions of, information about, printing: Options. (line 300) * gawk, VMS version of: VMS Installation. (line 6) * gawk, word-boundary operator: GNU Regexp Operators. (line 63) @@ -32568,12 +32851,12 @@ Index * getaddrinfo() function (C library): TCP/IP Networking. (line 38) * getgrent() function (C library): Group Functions. (line 6) * getgrent() user-defined function: Group Functions. (line 6) -* getgrgid() function (C library): Group Functions. (line 184) -* getgrgid() user-defined function: Group Functions. (line 187) -* getgrnam() function (C library): Group Functions. (line 173) -* getgrnam() user-defined function: Group Functions. (line 178) -* getgruser() function (C library): Group Functions. (line 193) -* getgruser() function, user-defined: Group Functions. (line 196) +* getgrgid() function (C library): Group Functions. (line 182) +* getgrgid() user-defined function: Group Functions. (line 185) +* getgrnam() function (C library): Group Functions. (line 171) +* getgrnam() user-defined function: Group Functions. (line 176) +* getgruser() function (C library): Group Functions. (line 191) +* getgruser() function, user-defined: Group Functions. (line 194) * getline command: Reading Files. (line 20) * getline command, _gr_init() user-defined function: Group Functions. (line 83) @@ -32597,10 +32880,10 @@ Index * getopt() user-defined function: Getopt Function. (line 108) * getpwent() function (C library): Passwd Functions. (line 16) * getpwent() user-defined function: Passwd Functions. (line 16) -* getpwnam() function (C library): Passwd Functions. (line 177) -* getpwnam() user-defined function: Passwd Functions. (line 182) -* getpwuid() function (C library): Passwd Functions. (line 188) -* getpwuid() user-defined function: Passwd Functions. (line 192) +* getpwnam() function (C library): Passwd Functions. (line 174) +* getpwnam() user-defined function: Passwd Functions. (line 179) +* getpwuid() function (C library): Passwd Functions. (line 185) +* getpwuid() user-defined function: Passwd Functions. (line 189) * gettext library: Explaining gettext. (line 6) * gettext library, locale categories: Explaining gettext. (line 81) * gettext() function (C library): Explaining gettext. (line 63) @@ -32610,7 +32893,7 @@ Index * git utility <2>: Accessing The Source. (line 10) * git utility <3>: Other Versions. (line 29) -* git utility: gawkextlib. (line 29) +* git utility: gawkextlib. (line 25) * Git, use of for gawk source code: Derived Files. (line 6) * GNITS mailing list: Acknowledgments. (line 52) * GNU awk, See gawk: Preface. (line 51) @@ -32634,12 +32917,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 180) +* group ID of gawk user: Auto-set. (line 187) * groups, information about: Group Functions. (line 6) * gsub <1>: String Functions. (line 139) * gsub: Using Constant Regexps. (line 43) -* gsub() function, arguments of: String Functions. (line 460) +* gsub() function, arguments of: String Functions. (line 461) * gsub() function, escape processing: Gory Details. (line 6) * h debugger command (alias for help): Miscellaneous Debugger Commands. (line 66) @@ -32674,7 +32957,7 @@ Index * ignore breakpoint: Breakpoint Control. (line 87) * ignore debugger command: Breakpoint Control. (line 87) * IGNORECASE variable: User-modified. (line 76) -* IGNORECASE variable, and array indices: Array Intro. (line 92) +* IGNORECASE variable, and array indices: Array Intro. (line 94) * IGNORECASE variable, and array sorting functions: Array Sorting Functions. (line 83) * IGNORECASE variable, in example programs: Library Functions. @@ -32685,9 +32968,9 @@ Index * Illumos, POSIX-compliant awk: Other Versions. (line 105) * implementation issues, gawk: Notes. (line 6) * implementation issues, gawk, debugging: Compatibility Mode. (line 6) -* implementation issues, gawk, limits <1>: Redirection. (line 135) +* implementation issues, gawk, limits <1>: Redirection. (line 129) * implementation issues, gawk, limits: Getline Notes. (line 14) -* in operator <1>: For Statement. (line 75) +* in operator <1>: For Statement. (line 76) * in operator <2>: Precedence. (line 83) * in operator: Comparison Operators. (line 11) @@ -32697,10 +32980,12 @@ Index * in operator, testing if array element exists: Reference to Elements. (line 38) * 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) * indexing arrays: Array Intro. (line 50) * indirect function calls: Indirect Calls. (line 6) +* indirect function calls, @-notation: Indirect Calls. (line 47) * infinite precision: Arbitrary Precision Arithmetic. (line 6) * info debugger command: Debugger Info. (line 13) @@ -32714,9 +32999,9 @@ Index * input files, examples: Sample Data Files. (line 6) * input files, reading: Reading Files. (line 6) * input files, running awk without: Read Terminal. (line 6) -* input files, variable assignments and: Other Arguments. (line 19) +* input files, variable assignments and: Other Arguments. (line 26) * input pipeline: Getline/Pipe. (line 9) -* input record, length of: String Functions. (line 174) +* input record, length of: String Functions. (line 177) * input redirection: Getline/File. (line 6) * input, data, nondecimal: Nondecimal Data. (line 6) * input, explicit: Getline. (line 6) @@ -32740,14 +33025,14 @@ Index * integers, arbitrary precision: Arbitrary Precision Integers. (line 6) * integers, unsigned: Computer Arithmetic. (line 41) -* interacting with other programs: I/O Functions. (line 75) +* interacting with other programs: I/O Functions. (line 74) * internationalization <1>: I18N and L10N. (line 6) * internationalization: I18N Functions. (line 6) * internationalization, localization <1>: Internationalization. (line 13) -* internationalization, localization: User-modified. (line 152) +* internationalization, localization: User-modified. (line 151) * internationalization, localization, character classes: Bracket Expressions. - (line 98) + (line 100) * internationalization, localization, gawk and: Internationalization. (line 13) * internationalization, localization, locale categories: Explaining gettext. @@ -32759,9 +33044,9 @@ Index * internationalizing a program: Explaining gettext. (line 6) * interpreted programs <1>: Glossary. (line 356) * interpreted programs: Basic High Level. (line 15) -* interval expressions, regexp operator: Regexp Operators. (line 117) +* interval expressions, regexp operator: Regexp Operators. (line 116) * inventory-shipped file: Sample Data Files. (line 32) -* invoke shell command: I/O Functions. (line 75) +* invoke shell command: I/O Functions. (line 74) * isarray: Type Functions. (line 11) * ISO: Glossary. (line 367) * ISO 8859-1: Glossary. (line 133) @@ -32787,7 +33072,7 @@ Index * Kernighan, Brian <6>: Library Functions. (line 12) * Kernighan, Brian <7>: Concatenation. (line 6) * Kernighan, Brian <8>: Getline/Pipe. (line 6) -* Kernighan, Brian <9>: Acknowledgments. (line 76) +* Kernighan, Brian <9>: Acknowledgments. (line 78) * Kernighan, Brian <10>: Conventions. (line 38) * Kernighan, Brian: History. (line 17) * kill command, dynamic profiling: Profiling. (line 188) @@ -32803,7 +33088,7 @@ Index * LC_CTYPE locale category: Explaining gettext. (line 98) * LC_MESSAGES locale category: Explaining gettext. (line 88) * LC_MESSAGES locale category, bindtextdomain() function (gawk): Programmer i18n. - (line 99) + (line 101) * LC_MONETARY locale category: Explaining gettext. (line 104) * LC_NUMERIC locale category: Explaining gettext. (line 108) * LC_TIME locale category: Explaining gettext. (line 112) @@ -32814,19 +33099,19 @@ Index * left angle bracket (<), <= operator <1>: Precedence. (line 65) * left angle bracket (<), <= operator: Comparison Operators. (line 11) -* left shift: Bitwise Functions. (line 46) +* left shift: Bitwise Functions. (line 47) * left shift, bitwise: Bitwise Functions. (line 32) * leftmost longest match: Multiple Line. (line 26) -* length: String Functions. (line 167) -* length of input record: String Functions. (line 174) -* length of string: String Functions. (line 167) +* length: String Functions. (line 170) +* length of input record: String Functions. (line 177) +* length of string: String Functions. (line 170) * Lesser General Public License (LGPL): Glossary. (line 396) * LGPL (Lesser General Public License): Glossary. (line 396) * libmawk: Other Versions. (line 121) * 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. - (line 57) + (line 58) * libraries of awk functions, character values as numbers: Ordinal Functions. (line 6) * libraries of awk functions, command-line options: Getopt Function. @@ -32846,7 +33131,7 @@ Index * libraries of awk functions, user database, reading: Passwd Functions. (line 6) * line breaks: Statements/Lines. (line 6) -* line continuations: Boolean Ops. (line 62) +* line continuations: Boolean Ops. (line 64) * line continuations, gawk: Conditional Exp. (line 34) * line continuations, in print statement: Print Examples. (line 76) * line continuations, with C shell: More Complex. (line 30) @@ -32862,7 +33147,7 @@ Index * lint checking, empty programs: Command Line. (line 16) * lint checking, issuing warnings: Options. (line 185) * lint checking, POSIXLY_CORRECT environment variable: Options. - (line 336) + (line 339) * lint checking, undefined functions: Pass By Value/Reference. (line 88) * LINT variable: User-modified. (line 88) @@ -32873,10 +33158,12 @@ Index * list debugger command: Miscellaneous Debugger Commands. (line 72) * list function definitions, in debugger: Debugger Info. (line 30) +* loading extensions, @load directive: Loading Shared Libraries. + (line 8) * loading, extensions: Options. (line 173) * local variables, in a function: Variable Scope. (line 6) * locale categories: Explaining gettext. (line 81) -* locale decimal point character: Options. (line 268) +* locale decimal point character: Options. (line 270) * locale, definition of: Locales. (line 6) * localization: I18N and L10N. (line 6) * localization, See internationalization, localization: I18N and L10N. @@ -32890,7 +33177,7 @@ Index * long options: Command Line. (line 13) * loops: While Statement. (line 6) * loops, break statement and: Break Statement. (line 6) -* loops, continue statements and: For Statement. (line 64) +* loops, continue statements and: For Statement. (line 65) * loops, count for header, in a profile: Profiling. (line 131) * loops, do-while: Do Statement. (line 6) * loops, exiting: Break Statement. (line 6) @@ -32899,68 +33186,66 @@ Index * loops, See Also while statement: While Statement. (line 6) * loops, while: While Statement. (line 6) * ls utility: More Complex. (line 15) -* lshift: Bitwise Functions. (line 46) +* lshift: Bitwise Functions. (line 47) * lvalues/rvalues: Assignment Ops. (line 32) * 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 71) +* Malmberg, John <1>: Bugs. (line 72) * Malmberg, John: Acknowledgments. (line 60) +* Malmberg, John E.: Contributors. (line 137) * mark parity: Ordinal Functions. (line 45) * marked string extraction (internationalization): String Extraction. (line 6) * marked strings, extracting: String Extraction. (line 6) * Marx, Groucho: Increment Ops. (line 60) -* match: String Functions. (line 207) -* match regexp in string: String Functions. (line 207) +* match: String Functions. (line 210) +* match regexp in string: String Functions. (line 210) * match() function, RSTART/RLENGTH variables: String Functions. - (line 224) + (line 227) * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) -* matching, null strings: Gory Details. (line 143) +* matching, null strings: String Functions. (line 535) * mawk utility <1>: Other Versions. (line 44) * 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 130) -* maximum precision supported by MPFR library: Auto-set. (line 221) +* mawk utility: Escape Sequences. (line 132) +* maximum precision supported by MPFR library: Auto-set. (line 228) * McIlroy, Doug: Glossary. (line 149) * McPhee, Patrick: Contributors. (line 100) * message object files: Explaining gettext. (line 42) * message object files, converting from portable object files: I18N Example. - (line 63) + (line 64) * message object files, specifying directory of <1>: Programmer i18n. (line 47) * message object files, specifying directory of: Explaining gettext. (line 54) * messages from extensions: Printing Messages. (line 6) * metacharacters in regular expressions: Regexp Operators. (line 6) -* metacharacters, escape sequences for: Escape Sequences. (line 136) -* minimum precision supported by MPFR library: Auto-set. (line 224) +* metacharacters, escape sequences for: Escape Sequences. (line 138) +* minimum precision supported by MPFR library: Auto-set. (line 231) * mktime: Time Functions. (line 25) * modifiers, in format specifiers: Format Modifiers. (line 6) * monetary information, localization: Explaining gettext. (line 104) * Moore, Duncan: Getline Notes. (line 40) -* msgfmt utility: I18N Example. (line 63) +* msgfmt utility: I18N Example. (line 64) * multiple precision: Arbitrary Precision Arithmetic. (line 6) * multiple-line records: Multiple Line. (line 6) * n debugger command (alias for next): Debugger Execution Control. (line 43) -* names, arrays/variables <1>: Library Names. (line 6) -* names, arrays/variables: Arrays. (line 18) +* names, arrays/variables: Library Names. (line 6) * names, functions <1>: Library Names. (line 6) -* names, functions: Definition Syntax. (line 20) -* namespace issues <1>: Library Names. (line 6) -* namespace issues: Arrays. (line 18) -* namespace issues, functions: Definition Syntax. (line 20) -* nawk utility: Names. (line 10) +* names, functions: Definition Syntax. (line 23) +* namespace issues: Library Names. (line 6) +* namespace issues, functions: Definition Syntax. (line 23) * NetBSD: Glossary. (line 611) * networks, programming: TCP/IP Networking. (line 6) * networks, support for: Special Network. (line 6) -* newlines <1>: Boolean Ops. (line 67) -* newlines <2>: Options. (line 258) +* newlines <1>: Boolean Ops. (line 69) +* newlines <2>: Options. (line 260) * newlines: Statements/Lines. (line 6) * newlines, as field separators: Default Field Splitting. (line 6) @@ -32975,14 +33260,14 @@ Index (line 43) * next file statement: Feature History. (line 169) * next statement <1>: Next Statement. (line 6) -* next statement: Boolean Ops. (line 85) -* next statement, BEGIN/END patterns and: I/O And BEGIN/END. (line 36) +* next statement: Boolean Ops. (line 95) +* next statement, BEGIN/END patterns and: I/O And BEGIN/END. (line 37) * next statement, BEGINFILE/ENDFILE patterns and: BEGINFILE/ENDFILE. (line 49) -* next statement, user-defined functions and: Next Statement. (line 45) +* next statement, user-defined functions and: Next Statement. (line 44) * nextfile statement: Nextfile Statement. (line 6) * nextfile statement, BEGIN/END patterns and: I/O And BEGIN/END. - (line 36) + (line 37) * nextfile statement, BEGINFILE/ENDFILE patterns and: BEGINFILE/ENDFILE. (line 26) * nextfile statement, user-defined functions and: Nextfile Statement. @@ -32998,23 +33283,23 @@ Index * non-existent array elements: Reference to Elements. (line 23) * not Boolean-logic operator: Boolean Ops. (line 6) -* NR variable <1>: Auto-set. (line 131) +* NR variable <1>: Auto-set. (line 132) * NR variable: Records. (line 6) -* NR variable, changing: Auto-set. (line 309) +* NR variable, changing: Auto-set. (line 321) * null strings <1>: Basic Data Typing. (line 26) * null strings <2>: Truth Values. (line 6) * null strings <3>: Regexp Field Splitting. (line 43) -* null strings: awk split records. (line 114) -* null strings in gawk arguments, quoting and: Quoting. (line 79) +* null strings: awk split records. (line 115) +* null strings in gawk arguments, quoting and: Quoting. (line 82) * null strings, and deleting array elements: Delete. (line 27) * null strings, as array subscripts: Uninitialized Subscripts. (line 43) * null strings, converting numbers to strings: Strings And Numbers. (line 21) -* null strings, matching: Gory Details. (line 143) -* number as string of bits: Bitwise Functions. (line 109) -* number of array elements: String Functions. (line 197) +* null strings, matching: String Functions. (line 535) +* number as string of bits: Bitwise Functions. (line 110) +* number of array elements: String Functions. (line 200) * number sign (#), #! (executable scripts): Executable Scripts. (line 6) * number sign (#), commenting: Comments. (line 6) @@ -33023,7 +33308,7 @@ Index * numbers, as values of characters: Ordinal Functions. (line 6) * numbers, Cliff random: Cliff Random Function. (line 6) -* numbers, converting <1>: Bitwise Functions. (line 109) +* numbers, converting <1>: Bitwise Functions. (line 110) * numbers, converting: Strings And Numbers. (line 6) * numbers, converting, to strings: User-modified. (line 30) * numbers, hexadecimal: Nondecimal-numbers. (line 6) @@ -33034,7 +33319,6 @@ Index * numeric, output format: OFMT. (line 6) * numeric, strings: Variable Typing. (line 6) * o debugger command (alias for option): Debugger Info. (line 57) -* oawk utility: Names. (line 10) * obsolete features: Obsolete. (line 6) * octal numbers: Nondecimal-numbers. (line 6) * octal values, enabling interpretation of: Options. (line 211) @@ -33042,7 +33326,7 @@ Index * OFMT variable <2>: Strings And Numbers. (line 57) * OFMT variable: OFMT. (line 15) * OFMT variable, POSIX awk and: OFMT. (line 27) -* OFS variable <1>: User-modified. (line 114) +* OFS variable <1>: User-modified. (line 113) * OFS variable <2>: Output Separators. (line 6) * OFS variable: Changing Fields. (line 64) * OpenBSD: Glossary. (line 611) @@ -33072,7 +33356,7 @@ Index * operators, precedence: Increment Ops. (line 60) * operators, relational, See operators, comparison: Typing and Comparison. (line 9) -* operators, short-circuit: Boolean Ops. (line 57) +* operators, short-circuit: Boolean Ops. (line 59) * operators, string: Concatenation. (line 8) * operators, string-matching: Regexp Usage. (line 19) * operators, string-matching, for buffers: GNU Regexp Operators. @@ -33088,14 +33372,14 @@ Index * options, long <1>: Options. (line 6) * options, long: Command Line. (line 13) * options, printing list of: Options. (line 154) -* or: Bitwise Functions. (line 49) +* or: Bitwise Functions. (line 50) * OR bitwise operation: Bitwise Functions. (line 6) * or Boolean-logic operator: Boolean Ops. (line 6) * ord() extension function: Extension Sample Ord. (line 12) * ord() user-defined function: Ordinal Functions. (line 16) * order of evaluation, concatenation: Concatenation. (line 41) -* ORS variable <1>: User-modified. (line 119) +* ORS variable <1>: User-modified. (line 118) * ORS variable: Output Separators. (line 20) * output field separator, See OFS variable: Changing Fields. (line 64) * output record separator, See ORS variable: Output Separators. @@ -33115,11 +33399,11 @@ Index * 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 189) +* parent process ID of gawk process: Auto-set. (line 196) * parentheses (), in a profile: Profiling. (line 146) -* parentheses (), regexp operator: Regexp Operators. (line 80) +* parentheses (), regexp operator: Regexp Operators. (line 81) * password file: Passwd Functions. (line 16) -* patsplit: String Functions. (line 294) +* patsplit: String Functions. (line 296) * patterns: Patterns and Actions. (line 6) * patterns, comparison expressions as: Expression Patterns. (line 14) @@ -33146,7 +33430,7 @@ Index (line 6) * pipe, input: Getline/Pipe. (line 9) * pipe, output: Redirection. (line 57) -* Pitts, Dave <1>: Bugs. (line 71) +* Pitts, Dave <1>: Bugs. (line 72) * Pitts, Dave: Acknowledgments. (line 60) * Plauger, P.J.: Library Functions. (line 12) * plug-in: Extension Intro. (line 6) @@ -33155,39 +33439,39 @@ Index * plus sign (+), ++ operator: Increment Ops. (line 11) * plus sign (+), += operator <1>: Precedence. (line 95) * plus sign (+), += operator: Assignment Ops. (line 82) -* plus sign (+), regexp operator: Regexp Operators. (line 103) +* plus sign (+), regexp operator: Regexp Operators. (line 105) * pointers to functions: Indirect Calls. (line 6) -* portability: Escape Sequences. (line 100) +* portability: Escape Sequences. (line 102) * portability, #! (executable scripts): Executable Scripts. (line 33) * portability, ** operator and: Arithmetic Ops. (line 81) * portability, **= operator and: Assignment Ops. (line 143) -* portability, ARGV variable: Executable Scripts. (line 42) +* portability, ARGV variable: Executable Scripts. (line 59) * portability, backslash continuation and: Statements/Lines. (line 30) * portability, backslash in escape sequences: Escape Sequences. - (line 118) + (line 120) * portability, close() function and: Close Files And Pipes. (line 81) * portability, data files as single record: gawk split records. (line 65) * portability, deleting array elements: Delete. (line 56) * portability, example programs: Library Functions. (line 42) -* portability, functions, defining: Definition Syntax. (line 105) +* portability, functions, defining: Definition Syntax. (line 109) * 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 176) +* portability, length() function: String Functions. (line 179) * portability, new awk vs. old awk: Strings And Numbers. (line 57) * portability, next statement in user-defined functions: Pass By Value/Reference. (line 91) * 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 356) -* portability, substr() function: String Functions. (line 510) +* portability, POSIXLY_CORRECT environment variable: Options. (line 359) +* portability, substr() function: String Functions. (line 511) * 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. - (line 63) + (line 64) * portable object files, generating: Options. (line 147) * portable object template files: Explaining gettext. (line 31) * porting gawk: New Ports. (line 6) @@ -33203,11 +33487,11 @@ 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 118) + (line 120) * POSIX awk, BEGIN/END patterns: I/O And BEGIN/END. (line 16) -* POSIX awk, bracket expressions and: Bracket Expressions. (line 24) +* POSIX awk, bracket expressions and: Bracket Expressions. (line 26) * POSIX awk, bracket expressions and, character classes: Bracket Expressions. - (line 30) + (line 32) * POSIX awk, break statement and: Break Statement. (line 51) * POSIX awk, changes in awk versions: POSIX. (line 6) * POSIX awk, continue statement and: Continue Statement. (line 44) @@ -33217,29 +33501,33 @@ Index (line 40) * 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 89) +* 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 176) +* POSIX awk, functions and, length(): String Functions. (line 179) * POSIX awk, GNU long options and: Options. (line 15) -* POSIX awk, interval expressions in: Regexp Operators. (line 136) -* POSIX awk, next/nextfile statements and: Next Statement. (line 45) +* POSIX awk, interval expressions in: Regexp Operators. (line 135) +* POSIX awk, next/nextfile statements and: Next Statement. (line 44) * POSIX awk, numeric strings and: Variable Typing. (line 6) * POSIX awk, OFMT variable and <1>: Strings And Numbers. (line 57) * POSIX awk, OFMT variable and: OFMT. (line 27) * POSIX awk, period (.), using: Regexp Operators. (line 51) -* POSIX awk, printf format strings and: Format Modifiers. (line 159) -* POSIX awk, regular expressions and: Regexp Operators. (line 162) +* POSIX awk, printf format strings and: Format Modifiers. (line 158) +* POSIX awk, regular expressions and: Regexp Operators. (line 161) * POSIX awk, timestamps and: Time Functions. (line 6) * POSIX awk, | I/O operator and: Getline/Pipe. (line 55) -* POSIX mode: Options. (line 252) +* POSIX mode: Options. (line 254) * POSIX, awk and: Preface. (line 21) * POSIX, gawk extensions not included in: POSIX/GNU. (line 6) * POSIX, programs, implementing in awk: Clones. (line 6) -* POSIXLY_CORRECT environment variable: Options. (line 336) -* PREC variable: User-modified. (line 124) +* POSIXLY_CORRECT environment variable: Options. (line 339) +* PREC variable: User-modified. (line 123) * precedence <1>: Precedence. (line 6) * precedence: Increment Ops. (line 60) -* precedence, regexp operators: Regexp Operators. (line 157) +* precedence, regexp operators: Regexp Operators. (line 156) +* predefined variables: Built-in Variables. (line 6) +* predefined variables, -v option, setting with: Options. (line 40) +* predefined variables, conveying information: Auto-set. (line 6) +* predefined variables, user-modifiable: User-modified. (line 6) * print debugger command: Viewing And Changing Data. (line 36) * print statement: Printing. (line 16) @@ -33247,7 +33535,7 @@ Index * print statement, commas, omitting: Print Examples. (line 31) * print statement, I/O operators in: Precedence. (line 71) * print statement, line continuations and: Print Examples. (line 76) -* print statement, OFMT variable and: User-modified. (line 114) +* print statement, OFMT variable and: User-modified. (line 113) * print statement, See Also redirection, of output: Redirection. (line 17) * print statement, sprintf() function and: Round Function. (line 6) @@ -33278,27 +33566,27 @@ 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 183) -* process ID of gawk process: Auto-set. (line 186) +* process group idIDof gawk process: Auto-set. (line 190) +* process ID of gawk process: Auto-set. (line 193) * 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 136) +* PROCINFO array: Auto-set. (line 137) * 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 161) -* PROCINFO array, uses: Auto-set. (line 242) + (line 154) +* PROCINFO array, uses: Auto-set. (line 249) * PROCINFO, values of sorted_in: Controlling Scanning. (line 26) * profiling awk programs: Profiling. (line 6) * profiling awk programs, dynamically: Profiling. (line 179) -* program identifiers: Auto-set. (line 154) +* program identifiers: Auto-set. (line 155) * program, definition of: Getting Started. (line 21) * programming conventions, --non-decimal-data option: Nondecimal Data. - (line 36) + (line 35) * programming conventions, ARGC/ARGV variables: Auto-set. (line 35) * programming conventions, exit statement: Exit Statement. (line 38) * programming conventions, function parameters: Return Statement. @@ -33306,7 +33594,7 @@ Index * programming conventions, functions, calling: Calling Built-in. (line 10) * programming conventions, functions, writing: Definition Syntax. - (line 61) + (line 65) * programming conventions, gawk extensions: Internal File Ops. (line 45) * programming conventions, private variable names: Library Names. @@ -33326,13 +33614,13 @@ Index * question mark (?), ?: operator: Precedence. (line 92) * question mark (?), regexp operator <1>: GNU Regexp Operators. (line 59) -* question mark (?), regexp operator: Regexp Operators. (line 112) +* question mark (?), regexp operator: Regexp Operators. (line 111) * QuikTrim Awk: Other Versions. (line 135) * quit debugger command: Miscellaneous Debugger Commands. (line 99) * QUIT signal (MS-Windows): Profiling. (line 214) * quoting in gawk command lines: Long. (line 26) -* quoting in gawk command lines, tricks for: Quoting. (line 88) +* quoting in gawk command lines, tricks for: Quoting. (line 91) * quoting, for small awk programs: Comments. (line 27) * r debugger command (alias for run): Debugger Execution Control. (line 62) @@ -33348,12 +33636,11 @@ Index * range expressions (regexps): Bracket Expressions. (line 6) * range patterns: Ranges. (line 6) * range patterns, line continuation and: Ranges. (line 65) -* Rankin, Pat <1>: Bugs. (line 71) -* Rankin, Pat <2>: Contributors. (line 37) -* Rankin, Pat <3>: Assignment Ops. (line 100) +* Rankin, Pat <1>: Contributors. (line 37) +* Rankin, Pat <2>: Assignment Ops. (line 100) * Rankin, Pat: Acknowledgments. (line 60) * reada() extension function: Extension Sample Read write array. - (line 15) + (line 18) * readable data files, checking: File Checking. (line 6) * readable.awk program: File Checking. (line 11) * readdir extension: Extension Sample Readdir. @@ -33363,20 +33650,20 @@ Index * readfile() user-defined function: Readfile Function. (line 30) * reading input files: Reading Files. (line 6) * recipe for a programming language: History. (line 6) -* record separators <1>: User-modified. (line 133) +* record separators <1>: User-modified. (line 132) * record separators: awk split records. (line 6) * record separators, changing: awk split records. (line 85) * record separators, regular expressions as: awk split records. - (line 124) + (line 125) * record separators, with multiline records: Multiple Line. (line 10) * records <1>: Basic High Level. (line 73) * records: Reading Files. (line 14) * records, multiline: Multiple Line. (line 6) * records, printing: Print. (line 22) * records, splitting input into: Records. (line 6) -* records, terminating: awk split records. (line 124) -* records, treating files as: gawk split records. (line 92) -* recursive functions: Definition Syntax. (line 79) +* records, terminating: awk split records. (line 125) +* records, treating files as: gawk split records. (line 93) +* recursive functions: Definition Syntax. (line 83) * redirect gawk output, in debugger: Debugger Info. (line 72) * redirection of input: Getline/File. (line 6) * redirection of output: Redirection. (line 6) @@ -33384,7 +33671,7 @@ Index (line 77) * regexp: Regexp. (line 6) * regexp constants <1>: Comparison Operators. - (line 102) + (line 103) * regexp constants <2>: Regexp Constants. (line 6) * regexp constants: Regexp Usage. (line 57) * regexp constants, /=.../, /= operator and: Assignment Ops. (line 148) @@ -33403,7 +33690,7 @@ Index * regular expressions, as patterns <1>: Regexp Patterns. (line 6) * regular expressions, as patterns: Regexp Usage. (line 6) * regular expressions, as record separators: awk split records. - (line 124) + (line 125) * regular expressions, case sensitivity <1>: User-modified. (line 76) * regular expressions, case sensitivity: Case-sensitivity. (line 6) * regular expressions, computed: Computed Regexps. (line 6) @@ -33414,7 +33701,7 @@ Index (line 59) * regular expressions, gawk, command-line options: GNU Regexp Operators. (line 70) -* regular expressions, interval expressions and: Options. (line 277) +* regular expressions, interval expressions and: Options. (line 279) * regular expressions, leftmost longest match: Leftmost Longest. (line 6) * regular expressions, operators <1>: Regexp Operators. (line 6) @@ -33426,16 +33713,16 @@ Index * regular expressions, operators, gawk: GNU Regexp Operators. (line 6) * regular expressions, operators, precedence of: Regexp Operators. - (line 157) + (line 156) * regular expressions, searching for: Egrep Program. (line 6) * relational operators, See comparison operators: Typing and Comparison. (line 9) -* replace in string: String Functions. (line 406) +* replace in string: String Functions. (line 407) * 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 131) + (line 132) * rev() user-defined function: Function Example. (line 54) * revoutput extension: Extension Sample Revout. (line 11) @@ -33451,40 +33738,40 @@ Index (line 11) * right angle bracket (>), >> operator (I/O) <1>: Precedence. (line 65) * right angle bracket (>), >> operator (I/O): Redirection. (line 50) -* right shift: Bitwise Functions. (line 52) +* 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 252) -* RLENGTH variable, match() function and: String Functions. (line 224) +* RLENGTH variable: Auto-set. (line 259) +* RLENGTH variable, match() function and: String Functions. (line 227) * Robbins, Arnold <1>: Future Extensions. (line 6) -* Robbins, Arnold <2>: Bugs. (line 32) -* Robbins, Arnold <3>: Contributors. (line 141) +* Robbins, Arnold <2>: Bugs. (line 72) +* Robbins, Arnold <3>: Contributors. (line 144) * Robbins, Arnold <4>: General Data Types. (line 6) * Robbins, Arnold <5>: Alarm Program. (line 6) * Robbins, Arnold <6>: Passwd Functions. (line 90) * Robbins, Arnold <7>: Getline/Pipe. (line 39) * Robbins, Arnold: Command Line Field Separator. - (line 74) + (line 71) * Robbins, Bill: Getline/Pipe. (line 39) -* Robbins, Harry: Acknowledgments. (line 92) -* Robbins, Jean: Acknowledgments. (line 92) +* Robbins, Harry: Acknowledgments. (line 94) +* Robbins, Jean: Acknowledgments. (line 94) * Robbins, Miriam <1>: Passwd Functions. (line 90) * Robbins, Miriam <2>: Getline/Pipe. (line 39) -* Robbins, Miriam: Acknowledgments. (line 92) +* Robbins, Miriam: Acknowledgments. (line 94) * Rommel, Kai Uwe: Contributors. (line 42) * round to nearest integer: Numeric Functions. (line 38) * round() user-defined function: Round Function. (line 16) * rounding numbers: Round Function. (line 6) -* ROUNDMODE variable: User-modified. (line 128) -* RS variable <1>: User-modified. (line 133) +* ROUNDMODE variable: User-modified. (line 127) +* RS variable <1>: User-modified. (line 132) * RS variable: awk split records. (line 12) * RS variable, multiline records and: Multiple Line. (line 17) -* rshift: Bitwise Functions. (line 52) -* RSTART variable: Auto-set. (line 258) -* RSTART variable, match() function and: String Functions. (line 224) -* RT variable <1>: Auto-set. (line 265) +* 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) * RT variable <2>: Multiple Line. (line 129) -* RT variable: awk split records. (line 124) +* RT variable: awk split records. (line 125) * Rubin, Paul <1>: Contributors. (line 15) * Rubin, Paul: History. (line 30) * rule, definition of: Getting Started. (line 21) @@ -33495,14 +33782,14 @@ Index (line 68) * sample debugging session: Sample Debugging Session. (line 6) -* sandbox mode: Options. (line 284) +* sandbox mode: Options. (line 286) * save debugger options: Debugger Info. (line 84) * scalar or array: Type Functions. (line 11) * scalar values: Basic Data Typing. (line 13) * 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 292) +* Schorr, Andrew <2>: Auto-set. (line 304) * Schorr, Andrew: Acknowledgments. (line 60) * Schreiber, Bert: Acknowledgments. (line 38) * Schreiber, Rita: Acknowledgments. (line 38) @@ -33510,11 +33797,11 @@ Index * search in string: String Functions. (line 155) * search paths <1>: VMS Running. (line 58) * search paths <2>: PC Using. (line 10) -* search paths: Programs Exercises. (line 63) +* 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 <2>: PC Using. (line 10) -* search paths, for source files <3>: Programs Exercises. (line 63) +* 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) @@ -33534,22 +33821,21 @@ Index * separators, field, FIELDWIDTHS variable and: User-modified. (line 37) * separators, field, FPAT variable and: User-modified. (line 43) * separators, field, POSIX and: Fields. (line 6) -* separators, for records <1>: User-modified. (line 133) +* separators, for records <1>: User-modified. (line 132) * separators, for records: awk split records. (line 6) * separators, for records, regular expressions as: awk split records. - (line 124) + (line 125) * separators, for statements in actions: Action Overview. (line 19) -* separators, subscript: User-modified. (line 146) +* separators, subscript: User-modified. (line 145) * set breakpoint: Breakpoint Control. (line 11) * set debugger command: Viewing And Changing Data. (line 59) * set directory of message catalogs: I18N Functions. (line 12) * set watchpoint: Viewing And Changing Data. (line 67) -* shadowing of variable values: Definition Syntax. (line 67) -* shell quoting, double quote: Read Terminal. (line 25) +* shadowing of variable values: Definition Syntax. (line 71) * shell quoting, rules for: Quoting. (line 6) -* shells, piping commands into: Redirection. (line 142) +* shells, piping commands into: Redirection. (line 136) * shells, quoting: Using Shell Variables. (line 12) * shells, quoting, rules for: Quoting. (line 18) @@ -33558,7 +33844,7 @@ Index * shells, variables: Using Shell Variables. (line 6) * shift, bitwise: Bitwise Functions. (line 32) -* short-circuit operators: Boolean Ops. (line 57) +* short-circuit operators: Boolean Ops. (line 59) * show all source files, in debugger: Debugger Info. (line 45) * show breakpoints: Debugger Info. (line 21) * show function arguments, in debugger: Debugger Info. (line 18) @@ -33584,35 +33870,35 @@ Index * sidebar, A Constant's Base Does Not Affect Its Value: Nondecimal-numbers. (line 64) * sidebar, Backslash Before Regular Characters: Escape Sequences. - (line 116) + (line 118) * sidebar, Changing FS Does Not Affect the Fields: Field Splitting Summary. (line 38) -* sidebar, Changing NR and FNR: Auto-set. (line 307) +* sidebar, Changing NR and FNR: Auto-set. (line 319) * sidebar, Controlling Output Buffering with system(): I/O Functions. - (line 138) + (line 137) * sidebar, Escape Sequences for Metacharacters: Escape Sequences. - (line 134) + (line 136) * sidebar, FS and IGNORECASE: Field Splitting Summary. (line 64) * sidebar, Interactive Versus Noninteractive Buffering: I/O Functions. - (line 107) -* sidebar, Matching the Null String: Gory Details. (line 141) + (line 106) +* sidebar, Matching the Null String: String Functions. (line 533) * sidebar, Operator Evaluation Order: Increment Ops. (line 58) -* sidebar, Piping into sh: Redirection. (line 140) -* sidebar, Portability Issues with #!: Executable Scripts. (line 31) +* sidebar, Piping into sh: Redirection. (line 134) * sidebar, Pre-POSIX awk Used OFMT For String Conversion: Strings And Numbers. (line 55) * 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. - (line 83) + (line 82) * sidebar, Syntactic Ambiguities Between /= and Regular Expressions: Assignment Ops. (line 146) +* sidebar, Understanding #!: Executable Scripts. (line 31) * sidebar, Understanding $0: Changing Fields. (line 134) * sidebar, Using \n in Bracket Expressions of Dynamic Regexps: Computed Regexps. (line 57) * sidebar, Using close()'s Return Value: Close Files And Pipes. - (line 129) + (line 130) * SIGHUP signal, for dynamic profiling: Profiling. (line 211) * SIGINT signal (MS-Windows): Profiling. (line 214) * signals, HUP/SIGHUP, for profiling: Profiling. (line 211) @@ -33627,21 +33913,21 @@ Index * sin: Numeric Functions. (line 91) * sine: Numeric Functions. (line 91) * single quote ('): One-shot. (line 15) -* single quote (') in gawk command lines: Long. (line 33) +* single quote (') in gawk command lines: Long. (line 35) * single quote ('), in shell commands: Quoting. (line 48) * single quote ('), vs. apostrophe: Comments. (line 27) -* single quote ('), with double quotes: Quoting. (line 70) +* single quote ('), with double quotes: Quoting. (line 73) * single-character fields: Single Character Fields. (line 6) * single-step execution, in the debugger: Debugger Execution Control. (line 43) * Skywalker, Luke: Undocumented. (line 6) -* sleep utility: Alarm Program. (line 111) +* 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 42) -* sort array indices: String Functions. (line 42) +* sort array: String Functions. (line 41) +* sort array indices: String Functions. (line 41) * sort function, arrays, sorting: Array Sorting Functions. (line 6) * sort utility: Word Sorting. (line 50) @@ -33662,17 +33948,17 @@ Index * 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 files, search path for: Programs Exercises. (line 63) -* sparse arrays: Array Intro. (line 71) +* source files, search path for: Programs Exercises. (line 70) +* sparse arrays: Array Intro. (line 72) * Spencer, Henry: Glossary. (line 11) -* split: String Functions. (line 313) -* split string into array: String Functions. (line 294) +* split: String Functions. (line 315) +* split string into array: String Functions. (line 296) * 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 381) +* sprintf <1>: String Functions. (line 382) * sprintf: OFMT. (line 15) -* sprintf() function, OFMT variable and: User-modified. (line 114) +* sprintf() function, OFMT variable and: User-modified. (line 113) * sprintf() function, print/printf statements and: Round Function. (line 6) * sqrt: Numeric Functions. (line 94) @@ -33708,18 +33994,18 @@ Index * string constants, vs. regexp constants: Computed Regexps. (line 39) * string extraction (internationalization): String Extraction. (line 6) -* string length: String Functions. (line 167) +* string length: String Functions. (line 170) * string operators: Concatenation. (line 8) -* string, regular expression match: String Functions. (line 207) +* string, regular expression match: String Functions. (line 210) * 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 333) -* strings, converting <1>: Bitwise Functions. (line 109) +* strings splitting, example: String Functions. (line 334) +* strings, converting <1>: Bitwise Functions. (line 110) * strings, converting: Strings And Numbers. (line 6) -* strings, converting letter case: String Functions. (line 520) +* strings, converting letter case: String Functions. (line 521) * strings, converting, numbers to: User-modified. (line 30) -* strings, empty, See null strings: awk split records. (line 114) +* strings, empty, See null strings: awk split records. (line 115) * strings, extracting: String Extraction. (line 6) * strings, for localization: Programmer i18n. (line 14) * strings, length limitations: Scalar Constants. (line 20) @@ -33727,15 +34013,15 @@ Index * strings, null: Regexp Field Splitting. (line 43) * strings, numeric: Variable Typing. (line 6) -* strtonum: String Functions. (line 388) +* strtonum: String Functions. (line 389) * strtonum() function (gawk), --non-decimal-data option and: Nondecimal Data. - (line 36) -* sub <1>: String Functions. (line 406) + (line 35) +* sub <1>: String Functions. (line 407) * sub: Using Constant Regexps. (line 43) -* sub() function, arguments of: String Functions. (line 460) +* sub() function, arguments of: String Functions. (line 461) * sub() function, escape processing: Gory Details. (line 6) -* subscript separators: User-modified. (line 146) +* subscript separators: User-modified. (line 145) * subscripts in arrays, multidimensional: Multidimensional. (line 10) * subscripts in arrays, multidimensional, scanning: Multiscanning. (line 11) @@ -33743,30 +34029,30 @@ Index (line 6) * subscripts in arrays, uninitialized variables as: Uninitialized Subscripts. (line 6) -* SUBSEP variable: User-modified. (line 146) +* 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 479) -* substring: String Functions. (line 479) +* substr: String Functions. (line 480) +* substring: String Functions. (line 480) * Sumner, Andrew: Other Versions. (line 64) -* supplementary groups of gawk process: Auto-set. (line 237) +* supplementary groups of gawk process: Auto-set. (line 244) * switch statement: Switch Statement. (line 6) -* SYMTAB array: Auto-set. (line 269) +* SYMTAB array: Auto-set. (line 276) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 148) -* system: I/O Functions. (line 75) +* system: I/O Functions. (line 74) * systime: Time Functions. (line 66) * t debugger command (alias for tbreak): Breakpoint Control. (line 90) * tbreak debugger command: Breakpoint Control. (line 90) -* Tcl: Library Names. (line 57) +* Tcl: Library Names. (line 58) * TCP/IP: TCP/IP Networking. (line 6) * TCP/IP, support for: Special Network. (line 6) * tee utility: Tee Program. (line 6) * tee.awk program: Tee Program. (line 26) * temporary breakpoint: Breakpoint Control. (line 90) -* terminating records: awk split records. (line 124) -* testbits.awk program: Bitwise Functions. (line 70) +* terminating records: awk split records. (line 125) +* testbits.awk program: Bitwise Functions. (line 71) * testext extension: Extension Sample API Tests. (line 6) * Texinfo <1>: Adding Code. (line 100) @@ -33782,7 +34068,7 @@ Index * text, printing: Print. (line 22) * text, printing, unduplicated lines of: Uniq Program. (line 6) * TEXTDOMAIN variable <1>: Programmer i18n. (line 9) -* TEXTDOMAIN variable: User-modified. (line 152) +* TEXTDOMAIN variable: User-modified. (line 151) * TEXTDOMAIN variable, BEGIN pattern and: Programmer i18n. (line 60) * TEXTDOMAIN variable, portability and: I18N Portability. (line 20) * textdomain() function (C library): Explaining gettext. (line 28) @@ -33791,8 +34077,8 @@ Index * tilde (~), ~ operator <3>: Comparison Operators. (line 11) * tilde (~), ~ operator <4>: Regexp Constants. (line 6) -* tilde (~), ~ operator <5>: Computed Regexps. (line 6) -* tilde (~), ~ operator <6>: Case-sensitivity. (line 26) +* tilde (~), ~ operator <5>: Case-sensitivity. (line 26) +* tilde (~), ~ operator <6>: Computed Regexps. (line 6) * tilde (~), ~ operator: Regexp Usage. (line 19) * time functions: Time Functions. (line 6) * time, alarm clock example program: Alarm Program. (line 11) @@ -33805,45 +34091,45 @@ Index * timestamps, converting dates to: Time Functions. (line 76) * timestamps, formatted: Getlocaltime Function. (line 6) -* tolower: String Functions. (line 521) -* toupper: String Functions. (line 527) +* tolower: String Functions. (line 522) +* toupper: String Functions. (line 528) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Debugger Commands. (line 108) * traceback, display in debugger: Execution Stack. (line 13) * translate string: I18N Functions. (line 22) * translate.awk program: Translate Program. (line 55) -* treating files, as single records: gawk split records. (line 92) +* treating files, as single records: gawk split records. (line 93) * troubleshooting, --non-decimal-data option: Options. (line 211) * troubleshooting, == operator: Comparison Operators. (line 37) * troubleshooting, awk uses FS not IFS: Field Separators. (line 30) * troubleshooting, backslash before nonspecial character: Escape Sequences. - (line 118) + (line 120) * troubleshooting, division: Arithmetic Ops. (line 44) * troubleshooting, fatal errors, field widths, specifying: Constant Size. (line 23) * troubleshooting, fatal errors, printf format strings: Format Modifiers. - (line 159) -* troubleshooting, fflush() function: I/O Functions. (line 63) + (line 158) +* troubleshooting, fflush() function: I/O Functions. (line 62) * troubleshooting, function call syntax: Function Calls. (line 30) * troubleshooting, gawk: Compatibility Mode. (line 6) * troubleshooting, gawk, bug reports: Bugs. (line 9) * 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 470) -* troubleshooting, match() function: String Functions. (line 289) +* troubleshooting, gsub()/sub() functions: String Functions. (line 471) +* troubleshooting, match() function: String Functions. (line 291) * troubleshooting, print statement, omitting commas: Print Examples. (line 31) -* troubleshooting, printing: Redirection. (line 118) -* troubleshooting, quotes with file names: Special FD. (line 68) +* troubleshooting, printing: Redirection. (line 112) +* troubleshooting, quotes with file names: Special FD. (line 62) * troubleshooting, readable data files: File Checking. (line 6) * troubleshooting, regexp constants vs. string constants: Computed Regexps. (line 39) * troubleshooting, string concatenation: Concatenation. (line 26) -* troubleshooting, substr() function: String Functions. (line 497) -* troubleshooting, system() function: I/O Functions. (line 97) +* troubleshooting, substr() function: String Functions. (line 498) +* troubleshooting, system() function: I/O Functions. (line 96) * troubleshooting, typographical errors, global variables: Options. (line 98) * true, logical: Truth Values. (line 6) @@ -33875,11 +34161,11 @@ Index * uniq.awk program: Uniq Program. (line 65) * Unix: Glossary. (line 611) * Unix awk, backslashes in escape sequences: Escape Sequences. - (line 130) + (line 132) * Unix awk, close() function and: Close Files And Pipes. - (line 131) + (line 132) * Unix awk, password files, field separators and: Command Line Field Separator. - (line 65) + (line 62) * Unix, awk scripts and: Executable Scripts. (line 6) * UNIXROOT variable, on OS/2 systems: PC Using. (line 16) * unsigned integers: Computer Arithmetic. (line 41) @@ -33887,7 +34173,7 @@ Index (line 83) * unwatch debugger command: Viewing And Changing Data. (line 84) -* up debugger command: Execution Stack. (line 34) +* up debugger command: Execution Stack. (line 36) * user database, reading: Passwd Functions. (line 6) * user-defined functions: User-defined. (line 6) * user-defined, functions, counts, in a profile: Profiling. (line 137) @@ -33898,17 +34184,14 @@ Index * USR1 signal, for dynamic profiling: Profiling. (line 188) * values, numeric: Basic Data Typing. (line 13) * values, string: Basic Data Typing. (line 13) -* variable assignments and input files: Other Arguments. (line 19) +* variable assignments and input files: Other Arguments. (line 26) * variable typing: Typing and Comparison. (line 9) * variables <1>: Basic Data Typing. (line 6) * variables: Other Features. (line 6) * variables, assigning on command line: Assignment Options. (line 6) -* variables, built-in <1>: Built-in Variables. (line 6) -* variables, built-in: Using Variables. (line 20) -* variables, built-in, -v option, setting with: Options. (line 40) -* variables, built-in, conveying information: Auto-set. (line 6) -* variables, flag: Boolean Ops. (line 67) +* variables, built-in: Using Variables. (line 23) +* variables, flag: Boolean Ops. (line 69) * variables, getline command into, using <1>: Getline/Variable/Coprocess. (line 6) * variables, getline command into, using <2>: Getline/Variable/Pipe. @@ -33918,22 +34201,24 @@ Index * variables, getline command into, using: Getline/Variable. (line 6) * variables, global, for library functions: Library Names. (line 11) * variables, global, printing list of: Options. (line 93) -* variables, initializing: Using Variables. (line 20) +* variables, initializing: Using Variables. (line 23) * variables, local to a function: Variable Scope. (line 6) -* variables, names of: Arrays. (line 18) +* variables, predefined: Built-in Variables. (line 6) +* variables, predefined -v option, setting with: Options. (line 40) +* variables, predefined conveying information: Auto-set. (line 6) * variables, private: Library Names. (line 11) * variables, setting: Options. (line 32) -* variables, shadowing: Definition Syntax. (line 67) +* variables, shadowing: Definition Syntax. (line 71) * variables, types of: Assignment Ops. (line 40) * variables, types of, comparison expressions and: Typing and Comparison. (line 9) * variables, uninitialized, as array subscripts: Uninitialized Subscripts. (line 6) * variables, user-defined: Variables. (line 6) -* version of gawk: Auto-set. (line 207) -* version of gawk extension API: Auto-set. (line 232) -* version of GNU MP library: Auto-set. (line 218) -* version of GNU MPFR library: Auto-set. (line 214) +* 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) * vertical bar (|): Regexp Operators. (line 70) * vertical bar (|), | operator (I/O) <1>: Precedence. (line 65) * vertical bar (|), | operator (I/O): Getline/Pipe. (line 9) @@ -33941,7 +34226,7 @@ Index * vertical bar (|), |& operator (I/O) <2>: Precedence. (line 65) * vertical bar (|), |& operator (I/O): Getline/Coprocess. (line 6) * vertical bar (|), || operator <1>: Precedence. (line 89) -* vertical bar (|), || operator: Boolean Ops. (line 57) +* vertical bar (|), || operator: Boolean Ops. (line 59) * Vinschen, Corinna: Acknowledgments. (line 60) * w debugger command (alias for watch): Viewing And Changing Data. (line 67) @@ -33962,12 +34247,15 @@ Index * wc.awk program: Wc Program. (line 46) * Weinberger, Peter <1>: Contributors. (line 11) * Weinberger, Peter: History. (line 17) +* where debugger command: Execution Stack. (line 13) +* where debugger command (alias for backtrace): Execution Stack. + (line 13) * while statement: While Statement. (line 6) * while statement, use of regexps in: Regexp Usage. (line 19) * whitespace, as field separators: Default Field Splitting. (line 6) * whitespace, functions, calling: Calling Built-in. (line 10) -* whitespace, newlines as: Options. (line 258) +* whitespace, newlines as: Options. (line 260) * Williams, Kent: Contributors. (line 34) * Woehlke, Matthew: Contributors. (line 79) * Woods, John: Contributors. (line 27) @@ -33982,12 +34270,12 @@ Index * words, duplicate, searching for: Dupword Program. (line 6) * words, usage counts, generating: Word Sorting. (line 6) * writea() extension function: Extension Sample Read write array. - (line 9) + (line 12) * xgettext utility: String Extraction. (line 13) -* xor: Bitwise Functions. (line 55) +* xor: Bitwise Functions. (line 56) * XOR bitwise operation: Bitwise Functions. (line 6) * Yawitz, Efraim: Contributors. (line 131) -* Zaretskii, Eli <1>: Bugs. (line 71) +* Zaretskii, Eli <1>: Bugs. (line 72) * Zaretskii, Eli <2>: Contributors. (line 55) * Zaretskii, Eli: Acknowledgments. (line 60) * zerofile.awk program: Empty Files. (line 21) @@ -34001,571 +34289,576 @@ Index * | (vertical bar), | operator (I/O): Getline/Pipe. (line 9) * | (vertical bar), |& operator (I/O) <1>: Two-way I/O. (line 25) * | (vertical bar), |& operator (I/O) <2>: Precedence. (line 65) -* | (vertical bar), |& operator (I/O) <3>: Redirection. (line 102) +* | (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 119) + (line 120) * | (vertical bar), || operator <1>: Precedence. (line 89) -* | (vertical bar), || operator: Boolean Ops. (line 57) +* | (vertical bar), || operator: Boolean Ops. (line 59) * ~ (tilde), ~ operator <1>: Expression Patterns. (line 24) * ~ (tilde), ~ operator <2>: Precedence. (line 80) * ~ (tilde), ~ operator <3>: Comparison Operators. (line 11) * ~ (tilde), ~ operator <4>: Regexp Constants. (line 6) -* ~ (tilde), ~ operator <5>: Computed Regexps. (line 6) -* ~ (tilde), ~ operator <6>: Case-sensitivity. (line 26) +* ~ (tilde), ~ operator <5>: Case-sensitivity. (line 26) +* ~ (tilde), ~ operator <6>: Computed Regexps. (line 6) * ~ (tilde), ~ operator: Regexp Usage. (line 19) Tag Table: Node: Top1204 -Node: Foreword41858 -Node: Preface46203 -Ref: Preface-Footnote-149226 -Ref: Preface-Footnote-249333 -Node: History49565 -Node: Names51939 -Ref: Names-Footnote-153403 -Node: This Manual53476 -Ref: This Manual-Footnote-159255 -Node: Conventions59355 -Node: Manual History61700 -Ref: Manual History-Footnote-164776 -Ref: Manual History-Footnote-264817 -Node: How To Contribute64891 -Node: Acknowledgments66130 -Node: Getting Started70878 -Node: Running gawk73312 -Node: One-shot74502 -Node: Read Terminal75727 -Ref: Read Terminal-Footnote-177690 -Node: Long77861 -Node: Executable Scripts79255 -Ref: Executable Scripts-Footnote-181088 -Ref: Executable Scripts-Footnote-281190 -Node: Comments81743 -Node: Quoting84216 -Node: DOS Quoting89529 -Node: Sample Data Files90204 -Node: Very Simple92758 -Node: Two Rules97531 -Node: More Complex99425 -Ref: More Complex-Footnote-1102357 -Node: Statements/Lines102442 -Ref: Statements/Lines-Footnote-1106898 -Node: Other Features107163 -Node: When108091 -Ref: When-Footnote-1109952 -Node: Intro Summary110017 -Node: Invoking Gawk110783 -Node: Command Line112298 -Node: Options113089 -Ref: Options-Footnote-1128736 -Node: Other Arguments128761 -Node: Naming Standard Input131423 -Node: Environment Variables132516 -Node: AWKPATH Variable133074 -Ref: AWKPATH Variable-Footnote-1135940 -Ref: AWKPATH Variable-Footnote-2135985 -Node: AWKLIBPATH Variable136245 -Node: Other Environment Variables137004 -Node: Exit Status140456 -Node: Include Files141131 -Node: Loading Shared Libraries144709 -Node: Obsolete146093 -Node: Undocumented146790 -Node: Invoking Summary147057 -Node: Regexp148657 -Node: Regexp Usage150107 -Node: Escape Sequences152140 -Node: Regexp Operators158040 -Ref: Regexp Operators-Footnote-1165520 -Ref: Regexp Operators-Footnote-2165667 -Node: Bracket Expressions165765 -Ref: table-char-classes167655 -Node: GNU Regexp Operators170595 -Node: Case-sensitivity174304 -Ref: Case-sensitivity-Footnote-1177196 -Ref: Case-sensitivity-Footnote-2177431 -Node: Leftmost Longest177539 -Node: Computed Regexps178740 -Node: Regexp Summary182112 -Node: Reading Files183581 -Node: Records185673 -Node: awk split records186416 -Node: gawk split records191274 -Ref: gawk split records-Footnote-1195795 -Node: Fields195832 -Ref: Fields-Footnote-1198796 -Node: Nonconstant Fields198882 -Ref: Nonconstant Fields-Footnote-1201112 -Node: Changing Fields201314 -Node: Field Separators207268 -Node: Default Field Splitting209970 -Node: Regexp Field Splitting211087 -Node: Single Character Fields214414 -Node: Command Line Field Separator215473 -Node: Full Line Fields218899 -Ref: Full Line Fields-Footnote-1219407 -Node: Field Splitting Summary219453 -Ref: Field Splitting Summary-Footnote-1222585 -Node: Constant Size222686 -Node: Splitting By Content227292 -Ref: Splitting By Content-Footnote-1231365 -Node: Multiple Line231405 -Ref: Multiple Line-Footnote-1237261 -Node: Getline237440 -Node: Plain Getline239656 -Node: Getline/Variable241751 -Node: Getline/File242898 -Node: Getline/Variable/File244282 -Ref: Getline/Variable/File-Footnote-1245881 -Node: Getline/Pipe245968 -Node: Getline/Variable/Pipe248654 -Node: Getline/Coprocess249761 -Node: Getline/Variable/Coprocess251013 -Node: Getline Notes251750 -Node: Getline Summary254554 -Ref: table-getline-variants254962 -Node: Read Timeout255874 -Ref: Read Timeout-Footnote-1259701 -Node: Command-line directories259759 -Node: Input Summary260663 -Node: Input Exercises263800 -Node: Printing264533 -Node: Print266255 -Node: Print Examples267748 -Node: Output Separators270527 -Node: OFMT272543 -Node: Printf273901 -Node: Basic Printf274807 -Node: Control Letters276346 -Node: Format Modifiers280337 -Node: Printf Examples286364 -Node: Redirection288828 -Node: Special Files295800 -Node: Special FD296333 -Ref: Special FD-Footnote-1299930 -Node: Special Network300004 -Node: Special Caveats300854 -Node: Close Files And Pipes301650 -Ref: Close Files And Pipes-Footnote-1308811 -Ref: Close Files And Pipes-Footnote-2308959 -Node: Output Summary309109 -Node: Output exercises310106 -Node: Expressions310786 -Node: Values311971 -Node: Constants312647 -Node: Scalar Constants313327 -Ref: Scalar Constants-Footnote-1314186 -Node: Nondecimal-numbers314436 -Node: Regexp Constants317436 -Node: Using Constant Regexps317911 -Node: Variables320983 -Node: Using Variables321638 -Node: Assignment Options323362 -Node: Conversion325237 -Node: Strings And Numbers325761 -Ref: Strings And Numbers-Footnote-1328823 -Node: Locale influences conversions328932 -Ref: table-locale-affects331649 -Node: All Operators332237 -Node: Arithmetic Ops332867 -Node: Concatenation335372 -Ref: Concatenation-Footnote-1338191 -Node: Assignment Ops338297 -Ref: table-assign-ops343280 -Node: Increment Ops344583 -Node: Truth Values and Conditions348021 -Node: Truth Values349104 -Node: Typing and Comparison350153 -Node: Variable Typing350946 -Node: Comparison Operators354598 -Ref: table-relational-ops355008 -Node: POSIX String Comparison358558 -Ref: POSIX String Comparison-Footnote-1359642 -Node: Boolean Ops359780 -Ref: Boolean Ops-Footnote-1363850 -Node: Conditional Exp363941 -Node: Function Calls365668 -Node: Precedence369548 -Node: Locales373217 -Node: Expressions Summary374848 -Node: Patterns and Actions377389 -Node: Pattern Overview378505 -Node: Regexp Patterns380182 -Node: Expression Patterns380725 -Node: Ranges384506 -Node: BEGIN/END387612 -Node: Using BEGIN/END388374 -Ref: Using BEGIN/END-Footnote-1391110 -Node: I/O And BEGIN/END391216 -Node: BEGINFILE/ENDFILE393487 -Node: Empty396418 -Node: Using Shell Variables396735 -Node: Action Overview399018 -Node: Statements401345 -Node: If Statement403193 -Node: While Statement404691 -Node: Do Statement406735 -Node: For Statement407891 -Node: Switch Statement411043 -Node: Break Statement413431 -Node: Continue Statement415472 -Node: Next Statement417297 -Node: Nextfile Statement419687 -Node: Exit Statement422323 -Node: Built-in Variables424727 -Node: User-modified425854 -Ref: User-modified-Footnote-1433543 -Node: Auto-set433605 -Ref: Auto-set-Footnote-1446524 -Ref: Auto-set-Footnote-2446729 -Node: ARGC and ARGV446785 -Node: Pattern Action Summary450689 -Node: Arrays452912 -Node: Array Basics454461 -Node: Array Intro455287 -Ref: figure-array-elements457260 -Node: Reference to Elements459667 -Node: Assigning Elements462046 -Node: Array Example462537 -Node: Scanning an Array464269 -Node: Controlling Scanning467270 -Ref: Controlling Scanning-Footnote-1472443 -Node: Delete472759 -Ref: Delete-Footnote-1475510 -Node: Numeric Array Subscripts475567 -Node: Uninitialized Subscripts477750 -Node: Multidimensional479375 -Node: Multiscanning482488 -Node: Arrays of Arrays484077 -Node: Arrays Summary488740 -Node: Functions490845 -Node: Built-in491718 -Node: Calling Built-in492796 -Node: Numeric Functions494784 -Ref: Numeric Functions-Footnote-1499620 -Ref: Numeric Functions-Footnote-2499977 -Ref: Numeric Functions-Footnote-3500025 -Node: String Functions500294 -Ref: String Functions-Footnote-1523291 -Ref: String Functions-Footnote-2523420 -Ref: String Functions-Footnote-3523668 -Node: Gory Details523755 -Ref: table-sub-escapes525528 -Ref: table-sub-proposed527048 -Ref: table-posix-sub528412 -Ref: table-gensub-escapes529952 -Ref: Gory Details-Footnote-1531128 -Node: I/O Functions531279 -Ref: I/O Functions-Footnote-1538389 -Node: Time Functions538536 -Ref: Time Functions-Footnote-1549000 -Ref: Time Functions-Footnote-2549068 -Ref: Time Functions-Footnote-3549226 -Ref: Time Functions-Footnote-4549337 -Ref: Time Functions-Footnote-5549449 -Ref: Time Functions-Footnote-6549676 -Node: Bitwise Functions549942 -Ref: table-bitwise-ops550504 -Ref: Bitwise Functions-Footnote-1554749 -Node: Type Functions554933 -Node: I18N Functions556075 -Node: User-defined557720 -Node: Definition Syntax558524 -Ref: Definition Syntax-Footnote-1563703 -Node: Function Example563772 -Ref: Function Example-Footnote-1566412 -Node: Function Caveats566434 -Node: Calling A Function566952 -Node: Variable Scope567907 -Node: Pass By Value/Reference570895 -Node: Return Statement574405 -Node: Dynamic Typing577389 -Node: Indirect Calls578318 -Node: Functions Summary588031 -Node: Library Functions590570 -Ref: Library Functions-Footnote-1594188 -Ref: Library Functions-Footnote-2594331 -Node: Library Names594502 -Ref: Library Names-Footnote-1597975 -Ref: Library Names-Footnote-2598195 -Node: General Functions598281 -Node: Strtonum Function599309 -Node: Assert Function602089 -Node: Round Function605415 -Node: Cliff Random Function606956 -Node: Ordinal Functions607972 -Ref: Ordinal Functions-Footnote-1611049 -Ref: Ordinal Functions-Footnote-2611301 -Node: Join Function611512 -Ref: Join Function-Footnote-1613283 -Node: Getlocaltime Function613483 -Node: Readfile Function617219 -Node: Data File Management619058 -Node: Filetrans Function619690 -Node: Rewind Function623759 -Node: File Checking625317 -Ref: File Checking-Footnote-1626449 -Node: Empty Files626650 -Node: Ignoring Assigns628629 -Node: Getopt Function630183 -Ref: Getopt Function-Footnote-1641486 -Node: Passwd Functions641689 -Ref: Passwd Functions-Footnote-1650668 -Node: Group Functions650756 -Ref: Group Functions-Footnote-1658697 -Node: Walking Arrays658910 -Node: Library Functions Summary660513 -Node: Library exercises661901 -Node: Sample Programs663181 -Node: Running Examples663951 -Node: Clones664679 -Node: Cut Program665903 -Node: Egrep Program675771 -Ref: Egrep Program-Footnote-1683742 -Node: Id Program683852 -Node: Split Program687516 -Ref: Split Program-Footnote-1691054 -Node: Tee Program691182 -Node: Uniq Program693989 -Node: Wc Program701419 -Ref: Wc Program-Footnote-1705684 -Node: Miscellaneous Programs705776 -Node: Dupword Program706989 -Node: Alarm Program709020 -Node: Translate Program713834 -Ref: Translate Program-Footnote-1718225 -Ref: Translate Program-Footnote-2718495 -Node: Labels Program718629 -Ref: Labels Program-Footnote-1722000 -Node: Word Sorting722084 -Node: History Sorting726127 -Node: Extract Program727963 -Node: Simple Sed735499 -Node: Igawk Program738561 -Ref: Igawk Program-Footnote-1752865 -Ref: Igawk Program-Footnote-2753066 -Node: Anagram Program753204 -Node: Signature Program756272 -Node: Programs Summary757519 -Node: Programs Exercises758734 -Node: Advanced Features762385 -Node: Nondecimal Data764333 -Node: Array Sorting765910 -Node: Controlling Array Traversal766607 -Node: Array Sorting Functions774887 -Ref: Array Sorting Functions-Footnote-1778794 -Node: Two-way I/O778988 -Ref: Two-way I/O-Footnote-1783932 -Ref: Two-way I/O-Footnote-2784111 -Node: TCP/IP Networking784193 -Node: Profiling787038 -Node: Advanced Features Summary794589 -Node: Internationalization796453 -Node: I18N and L10N797933 -Node: Explaining gettext798619 -Ref: Explaining gettext-Footnote-1803645 -Ref: Explaining gettext-Footnote-2803829 -Node: Programmer i18n803994 -Ref: Programmer i18n-Footnote-1808788 -Node: Translator i18n808837 -Node: String Extraction809631 -Ref: String Extraction-Footnote-1810764 -Node: Printf Ordering810850 -Ref: Printf Ordering-Footnote-1813632 -Node: I18N Portability813696 -Ref: I18N Portability-Footnote-1816145 -Node: I18N Example816208 -Ref: I18N Example-Footnote-1818914 -Node: Gawk I18N818986 -Node: I18N Summary819624 -Node: Debugger820963 -Node: Debugging821985 -Node: Debugging Concepts822426 -Node: Debugging Terms824282 -Node: Awk Debugging826879 -Node: Sample Debugging Session827771 -Node: Debugger Invocation828291 -Node: Finding The Bug829624 -Node: List of Debugger Commands836106 -Node: Breakpoint Control837438 -Node: Debugger Execution Control841102 -Node: Viewing And Changing Data844462 -Node: Execution Stack847820 -Node: Debugger Info849333 -Node: Miscellaneous Debugger Commands853327 -Node: Readline Support858511 -Node: Limitations859403 -Node: Debugging Summary861677 -Node: Arbitrary Precision Arithmetic862845 -Node: Computer Arithmetic864332 -Ref: Computer Arithmetic-Footnote-1868719 -Node: Math Definitions868776 -Ref: table-ieee-formats872065 -Ref: Math Definitions-Footnote-1872605 -Node: MPFR features872708 -Node: FP Math Caution874325 -Ref: FP Math Caution-Footnote-1875375 -Node: Inexactness of computations875744 -Node: Inexact representation876692 -Node: Comparing FP Values878047 -Node: Errors accumulate879011 -Node: Getting Accuracy880444 -Node: Try To Round883103 -Node: Setting precision884002 -Ref: table-predefined-precision-strings884684 -Node: Setting the rounding mode886477 -Ref: table-gawk-rounding-modes886841 -Ref: Setting the rounding mode-Footnote-1890295 -Node: Arbitrary Precision Integers890474 -Ref: Arbitrary Precision Integers-Footnote-1894247 -Node: POSIX Floating Point Problems894396 -Ref: POSIX Floating Point Problems-Footnote-1898272 -Node: Floating point summary898310 -Node: Dynamic Extensions900514 -Node: Extension Intro902066 -Node: Plugin License903331 -Node: Extension Mechanism Outline904016 -Ref: figure-load-extension904440 -Ref: figure-load-new-function905925 -Ref: figure-call-new-function906927 -Node: Extension API Description908911 -Node: Extension API Functions Introduction910361 -Node: General Data Types915228 -Ref: General Data Types-Footnote-1920921 -Node: Requesting Values921220 -Ref: table-value-types-returned921957 -Node: Memory Allocation Functions922915 -Ref: Memory Allocation Functions-Footnote-1925662 -Node: Constructor Functions925758 -Node: Registration Functions927516 -Node: Extension Functions928201 -Node: Exit Callback Functions930503 -Node: Extension Version String931751 -Node: Input Parsers932401 -Node: Output Wrappers942215 -Node: Two-way processors946731 -Node: Printing Messages948935 -Ref: Printing Messages-Footnote-1950012 -Node: Updating `ERRNO'950164 -Node: Accessing Parameters950903 -Node: Symbol Table Access952133 -Node: Symbol table by name952647 -Node: Symbol table by cookie954623 -Ref: Symbol table by cookie-Footnote-1958756 -Node: Cached values958819 -Ref: Cached values-Footnote-1962323 -Node: Array Manipulation962414 -Ref: Array Manipulation-Footnote-1963512 -Node: Array Data Types963551 -Ref: Array Data Types-Footnote-1966254 -Node: Array Functions966346 -Node: Flattening Arrays970220 -Node: Creating Arrays977072 -Node: Extension API Variables981803 -Node: Extension Versioning982439 -Node: Extension API Informational Variables984340 -Node: Extension API Boilerplate985426 -Node: Finding Extensions989230 -Node: Extension Example989790 -Node: Internal File Description990520 -Node: Internal File Ops994611 -Ref: Internal File Ops-Footnote-11006043 -Node: Using Internal File Ops1006183 -Ref: Using Internal File Ops-Footnote-11008530 -Node: Extension Samples1008798 -Node: Extension Sample File Functions1010322 -Node: Extension Sample Fnmatch1017890 -Node: Extension Sample Fork1019372 -Node: Extension Sample Inplace1020585 -Node: Extension Sample Ord1022260 -Node: Extension Sample Readdir1023096 -Ref: table-readdir-file-types1023952 -Node: Extension Sample Revout1024751 -Node: Extension Sample Rev2way1025342 -Node: Extension Sample Read write array1026083 -Node: Extension Sample Readfile1027962 -Node: Extension Sample API Tests1029062 -Node: Extension Sample Time1029587 -Node: gawkextlib1030902 -Node: Extension summary1033715 -Node: Extension Exercises1037408 -Node: Language History1038130 -Node: V7/SVR3.11039773 -Node: SVR41042093 -Node: POSIX1043535 -Node: BTL1044921 -Node: POSIX/GNU1045655 -Node: Feature History1051371 -Node: Common Extensions1064462 -Node: Ranges and Locales1065774 -Ref: Ranges and Locales-Footnote-11070391 -Ref: Ranges and Locales-Footnote-21070418 -Ref: Ranges and Locales-Footnote-31070652 -Node: Contributors1070873 -Node: History summary1076298 -Node: Installation1077667 -Node: Gawk Distribution1078618 -Node: Getting1079102 -Node: Extracting1079926 -Node: Distribution contents1081568 -Node: Unix Installation1087338 -Node: Quick Installation1087955 -Node: Additional Configuration Options1090397 -Node: Configuration Philosophy1092135 -Node: Non-Unix Installation1094486 -Node: PC Installation1094944 -Node: PC Binary Installation1096255 -Node: PC Compiling1098103 -Ref: PC Compiling-Footnote-11101102 -Node: PC Testing1101207 -Node: PC Using1102383 -Node: Cygwin1106535 -Node: MSYS1107344 -Node: VMS Installation1107858 -Node: VMS Compilation1108654 -Ref: VMS Compilation-Footnote-11109876 -Node: VMS Dynamic Extensions1109934 -Node: VMS Installation Details1111307 -Node: VMS Running1113559 -Node: VMS GNV1116393 -Node: VMS Old Gawk1117116 -Node: Bugs1117586 -Node: Other Versions1121590 -Node: Installation summary1127817 -Node: Notes1128873 -Node: Compatibility Mode1129738 -Node: Additions1130520 -Node: Accessing The Source1131445 -Node: Adding Code1132881 -Node: New Ports1139059 -Node: Derived Files1143540 -Ref: Derived Files-Footnote-11148621 -Ref: Derived Files-Footnote-21148655 -Ref: Derived Files-Footnote-31149251 -Node: Future Extensions1149365 -Node: Implementation Limitations1149971 -Node: Extension Design1151219 -Node: Old Extension Problems1152373 -Ref: Old Extension Problems-Footnote-11153890 -Node: Extension New Mechanism Goals1153947 -Ref: Extension New Mechanism Goals-Footnote-11157307 -Node: Extension Other Design Decisions1157496 -Node: Extension Future Growth1159602 -Node: Old Extension Mechanism1160438 -Node: Notes summary1162200 -Node: Basic Concepts1163386 -Node: Basic High Level1164067 -Ref: figure-general-flow1164339 -Ref: figure-process-flow1164938 -Ref: Basic High Level-Footnote-11168167 -Node: Basic Data Typing1168352 -Node: Glossary1171680 -Node: Copying1196832 -Node: GNU Free Documentation License1234388 -Node: Index1259524 +Node: Foreword42103 +Node: Preface46450 +Ref: Preface-Footnote-149320 +Ref: Preface-Footnote-249427 +Ref: Preface-Footnote-349660 +Node: History49802 +Node: Names52150 +Ref: Names-Footnote-153244 +Node: This Manual53390 +Ref: This Manual-Footnote-159219 +Node: Conventions59319 +Node: Manual History61659 +Ref: Manual History-Footnote-164650 +Ref: Manual History-Footnote-264691 +Node: How To Contribute64765 +Node: Acknowledgments66004 +Node: Getting Started70812 +Node: Running gawk73246 +Node: One-shot74436 +Node: Read Terminal75661 +Node: Long77688 +Node: Executable Scripts79204 +Ref: Executable Scripts-Footnote-181993 +Node: Comments82095 +Node: Quoting84568 +Node: DOS Quoting90074 +Node: Sample Data Files90749 +Node: Very Simple93342 +Node: Two Rules98233 +Node: More Complex100119 +Node: Statements/Lines102981 +Ref: Statements/Lines-Footnote-1107437 +Node: Other Features107702 +Node: When108633 +Ref: When-Footnote-1110389 +Node: Intro Summary110454 +Node: Invoking Gawk111337 +Node: Command Line112852 +Node: Options113643 +Ref: Options-Footnote-1129409 +Node: Other Arguments129434 +Node: Naming Standard Input132395 +Node: Environment Variables133488 +Node: AWKPATH Variable134046 +Ref: AWKPATH Variable-Footnote-1136898 +Ref: AWKPATH Variable-Footnote-2136943 +Node: AWKLIBPATH Variable137203 +Node: Other Environment Variables137962 +Node: Exit Status141453 +Node: Include Files142128 +Node: Loading Shared Libraries145716 +Node: Obsolete147143 +Node: Undocumented147840 +Node: Invoking Summary148107 +Node: Regexp149773 +Node: Regexp Usage151232 +Node: Escape Sequences153265 +Node: Regexp Operators159365 +Ref: Regexp Operators-Footnote-1166799 +Ref: Regexp Operators-Footnote-2166946 +Node: Bracket Expressions167044 +Ref: table-char-classes169061 +Node: Leftmost Longest172001 +Node: Computed Regexps173303 +Node: GNU Regexp Operators176700 +Node: Case-sensitivity180402 +Ref: Case-sensitivity-Footnote-1183292 +Ref: Case-sensitivity-Footnote-2183527 +Node: Regexp Summary183635 +Node: Reading Files185104 +Node: Records187198 +Node: awk split records187930 +Node: gawk split records192844 +Ref: gawk split records-Footnote-1197383 +Node: Fields197420 +Ref: Fields-Footnote-1200218 +Node: Nonconstant Fields200304 +Ref: Nonconstant Fields-Footnote-1202540 +Node: Changing Fields202742 +Node: Field Separators208674 +Node: Default Field Splitting211378 +Node: Regexp Field Splitting212495 +Node: Single Character Fields215845 +Node: Command Line Field Separator216904 +Node: Full Line Fields220116 +Ref: Full Line Fields-Footnote-1220624 +Node: Field Splitting Summary220670 +Ref: Field Splitting Summary-Footnote-1223801 +Node: Constant Size223902 +Node: Splitting By Content228508 +Ref: Splitting By Content-Footnote-1232581 +Node: Multiple Line232621 +Ref: Multiple Line-Footnote-1238510 +Node: Getline238689 +Node: Plain Getline240900 +Node: Getline/Variable243540 +Node: Getline/File244687 +Node: Getline/Variable/File246071 +Ref: Getline/Variable/File-Footnote-1247672 +Node: Getline/Pipe247759 +Node: Getline/Variable/Pipe250442 +Node: Getline/Coprocess251573 +Node: Getline/Variable/Coprocess252825 +Node: Getline Notes253564 +Node: Getline Summary256356 +Ref: table-getline-variants256768 +Node: Read Timeout257597 +Ref: Read Timeout-Footnote-1261411 +Node: Command-line directories261469 +Node: Input Summary262373 +Node: Input Exercises265625 +Node: Printing266353 +Node: Print268130 +Node: Print Examples269587 +Node: Output Separators272366 +Node: OFMT274384 +Node: Printf275738 +Node: Basic Printf276523 +Node: Control Letters278094 +Node: Format Modifiers282078 +Node: Printf Examples288085 +Node: Redirection290567 +Node: Special FD297406 +Ref: Special FD-Footnote-1300563 +Node: Special Files300637 +Node: Other Inherited Files301253 +Node: Special Network302253 +Node: Special Caveats303114 +Node: Close Files And Pipes304065 +Ref: Close Files And Pipes-Footnote-1311244 +Ref: Close Files And Pipes-Footnote-2311392 +Node: Output Summary311542 +Node: Output Exercises312538 +Node: Expressions313218 +Node: Values314403 +Node: Constants315079 +Node: Scalar Constants315759 +Ref: Scalar Constants-Footnote-1316618 +Node: Nondecimal-numbers316868 +Node: Regexp Constants319868 +Node: Using Constant Regexps320393 +Node: Variables323531 +Node: Using Variables324186 +Node: Assignment Options326096 +Node: Conversion327971 +Node: Strings And Numbers328495 +Ref: Strings And Numbers-Footnote-1331559 +Node: Locale influences conversions331668 +Ref: table-locale-affects334413 +Node: All Operators335001 +Node: Arithmetic Ops335631 +Node: Concatenation338136 +Ref: Concatenation-Footnote-1340955 +Node: Assignment Ops341061 +Ref: table-assign-ops346044 +Node: Increment Ops347322 +Node: Truth Values and Conditions350760 +Node: Truth Values351843 +Node: Typing and Comparison352892 +Node: Variable Typing353685 +Node: Comparison Operators357337 +Ref: table-relational-ops357747 +Node: POSIX String Comparison361262 +Ref: POSIX String Comparison-Footnote-1362334 +Node: Boolean Ops362472 +Ref: Boolean Ops-Footnote-1366951 +Node: Conditional Exp367042 +Node: Function Calls368769 +Node: Precedence372649 +Node: Locales376317 +Node: Expressions Summary377948 +Node: Patterns and Actions380522 +Node: Pattern Overview381642 +Node: Regexp Patterns383321 +Node: Expression Patterns383864 +Node: Ranges387644 +Node: BEGIN/END390750 +Node: Using BEGIN/END391512 +Ref: Using BEGIN/END-Footnote-1394249 +Node: I/O And BEGIN/END394355 +Node: BEGINFILE/ENDFILE396669 +Node: Empty399570 +Node: Using Shell Variables399887 +Node: Action Overview402163 +Node: Statements404490 +Node: If Statement406338 +Node: While Statement407836 +Node: Do Statement409864 +Node: For Statement411006 +Node: Switch Statement414161 +Node: Break Statement416549 +Node: Continue Statement418590 +Node: Next Statement420415 +Node: Nextfile Statement422795 +Node: Exit Statement425425 +Node: Built-in Variables427828 +Node: User-modified428961 +Ref: User-modified-Footnote-1436641 +Node: Auto-set436703 +Ref: Auto-set-Footnote-1450070 +Ref: Auto-set-Footnote-2450275 +Node: ARGC and ARGV450331 +Node: Pattern Action Summary454535 +Node: Arrays456962 +Node: Array Basics458291 +Node: Array Intro459135 +Ref: figure-array-elements461099 +Ref: Array Intro-Footnote-1463623 +Node: Reference to Elements463751 +Node: Assigning Elements466201 +Node: Array Example466692 +Node: Scanning an Array468450 +Node: Controlling Scanning471466 +Ref: Controlling Scanning-Footnote-1476655 +Node: Numeric Array Subscripts476971 +Node: Uninitialized Subscripts479156 +Node: Delete480773 +Ref: Delete-Footnote-1483517 +Node: Multidimensional483574 +Node: Multiscanning486669 +Node: Arrays of Arrays488258 +Node: Arrays Summary493019 +Node: Functions495124 +Node: Built-in495997 +Node: Calling Built-in497075 +Node: Numeric Functions499063 +Ref: Numeric Functions-Footnote-1503887 +Ref: Numeric Functions-Footnote-2504244 +Ref: Numeric Functions-Footnote-3504292 +Node: String Functions504561 +Ref: String Functions-Footnote-1528033 +Ref: String Functions-Footnote-2528162 +Ref: String Functions-Footnote-3528410 +Node: Gory Details528497 +Ref: table-sub-escapes530278 +Ref: table-sub-proposed531798 +Ref: table-posix-sub533162 +Ref: table-gensub-escapes534702 +Ref: Gory Details-Footnote-1535534 +Node: I/O Functions535685 +Ref: I/O Functions-Footnote-1542786 +Node: Time Functions542933 +Ref: Time Functions-Footnote-1553402 +Ref: Time Functions-Footnote-2553470 +Ref: Time Functions-Footnote-3553628 +Ref: Time Functions-Footnote-4553739 +Ref: Time Functions-Footnote-5553851 +Ref: Time Functions-Footnote-6554078 +Node: Bitwise Functions554344 +Ref: table-bitwise-ops554906 +Ref: Bitwise Functions-Footnote-1559214 +Node: Type Functions559383 +Node: I18N Functions560532 +Node: User-defined562177 +Node: Definition Syntax562981 +Ref: Definition Syntax-Footnote-1568387 +Node: Function Example568456 +Ref: Function Example-Footnote-1571373 +Node: Function Caveats571395 +Node: Calling A Function571913 +Node: Variable Scope572868 +Node: Pass By Value/Reference575856 +Node: Return Statement579366 +Node: Dynamic Typing582350 +Node: Indirect Calls583279 +Ref: Indirect Calls-Footnote-1594583 +Node: Functions Summary594711 +Node: Library Functions597410 +Ref: Library Functions-Footnote-1601028 +Ref: Library Functions-Footnote-2601171 +Node: Library Names601342 +Ref: Library Names-Footnote-1604802 +Ref: Library Names-Footnote-2605022 +Node: General Functions605108 +Node: Strtonum Function606211 +Node: Assert Function609231 +Node: Round Function612555 +Node: Cliff Random Function614096 +Node: Ordinal Functions615112 +Ref: Ordinal Functions-Footnote-1618177 +Ref: Ordinal Functions-Footnote-2618429 +Node: Join Function618640 +Ref: Join Function-Footnote-1620411 +Node: Getlocaltime Function620611 +Node: Readfile Function624352 +Node: Shell Quoting626322 +Node: Data File Management627723 +Node: Filetrans Function628355 +Node: Rewind Function632414 +Node: File Checking633799 +Ref: File Checking-Footnote-1635127 +Node: Empty Files635328 +Node: Ignoring Assigns637307 +Node: Getopt Function638858 +Ref: Getopt Function-Footnote-1650318 +Node: Passwd Functions650521 +Ref: Passwd Functions-Footnote-1659372 +Node: Group Functions659460 +Ref: Group Functions-Footnote-1667363 +Node: Walking Arrays667576 +Node: Library Functions Summary669179 +Node: Library Exercises670580 +Node: Sample Programs671860 +Node: Running Examples672630 +Node: Clones673358 +Node: Cut Program674582 +Node: Egrep Program684312 +Ref: Egrep Program-Footnote-1691816 +Node: Id Program691926 +Node: Split Program695570 +Ref: Split Program-Footnote-1699016 +Node: Tee Program699144 +Node: Uniq Program701931 +Node: Wc Program709352 +Ref: Wc Program-Footnote-1713600 +Node: Miscellaneous Programs713692 +Node: Dupword Program714905 +Node: Alarm Program716936 +Node: Translate Program721740 +Ref: Translate Program-Footnote-1726304 +Node: Labels Program726574 +Ref: Labels Program-Footnote-1729923 +Node: Word Sorting730007 +Node: History Sorting734077 +Node: Extract Program735913 +Node: Simple Sed743445 +Node: Igawk Program746507 +Ref: Igawk Program-Footnote-1760833 +Ref: Igawk Program-Footnote-2761034 +Ref: Igawk Program-Footnote-3761156 +Node: Anagram Program761271 +Node: Signature Program764333 +Node: Programs Summary765580 +Node: Programs Exercises766773 +Ref: Programs Exercises-Footnote-1770904 +Node: Advanced Features770995 +Node: Nondecimal Data772943 +Node: Array Sorting774533 +Node: Controlling Array Traversal775230 +Ref: Controlling Array Traversal-Footnote-1783561 +Node: Array Sorting Functions783679 +Ref: Array Sorting Functions-Footnote-1787571 +Node: Two-way I/O787765 +Ref: Two-way I/O-Footnote-1792709 +Ref: Two-way I/O-Footnote-2792895 +Node: TCP/IP Networking792977 +Node: Profiling795849 +Node: Advanced Features Summary803402 +Node: Internationalization805335 +Node: I18N and L10N806815 +Node: Explaining gettext807501 +Ref: Explaining gettext-Footnote-1812530 +Ref: Explaining gettext-Footnote-2812714 +Node: Programmer i18n812879 +Ref: Programmer i18n-Footnote-1817745 +Node: Translator i18n817794 +Node: String Extraction818588 +Ref: String Extraction-Footnote-1819719 +Node: Printf Ordering819805 +Ref: Printf Ordering-Footnote-1822591 +Node: I18N Portability822655 +Ref: I18N Portability-Footnote-1825104 +Node: I18N Example825167 +Ref: I18N Example-Footnote-1827967 +Node: Gawk I18N828039 +Node: I18N Summary828677 +Node: Debugger830016 +Node: Debugging831038 +Node: Debugging Concepts831479 +Node: Debugging Terms833336 +Node: Awk Debugging835911 +Node: Sample Debugging Session836803 +Node: Debugger Invocation837323 +Node: Finding The Bug838707 +Node: List of Debugger Commands845182 +Node: Breakpoint Control846514 +Node: Debugger Execution Control850206 +Node: Viewing And Changing Data853570 +Node: Execution Stack856935 +Node: Debugger Info858573 +Node: Miscellaneous Debugger Commands862590 +Node: Readline Support867782 +Node: Limitations868674 +Node: Debugging Summary870771 +Node: Arbitrary Precision Arithmetic871939 +Node: Computer Arithmetic873355 +Ref: table-numeric-ranges876956 +Ref: Computer Arithmetic-Footnote-1877815 +Node: Math Definitions877872 +Ref: table-ieee-formats881159 +Ref: Math Definitions-Footnote-1881763 +Node: MPFR features881868 +Node: FP Math Caution883539 +Ref: FP Math Caution-Footnote-1884589 +Node: Inexactness of computations884958 +Node: Inexact representation885906 +Node: Comparing FP Values887261 +Node: Errors accumulate888334 +Node: Getting Accuracy889767 +Node: Try To Round892426 +Node: Setting precision893325 +Ref: table-predefined-precision-strings894009 +Node: Setting the rounding mode895803 +Ref: table-gawk-rounding-modes896167 +Ref: Setting the rounding mode-Footnote-1899621 +Node: Arbitrary Precision Integers899800 +Ref: Arbitrary Precision Integers-Footnote-1904704 +Node: POSIX Floating Point Problems904853 +Ref: POSIX Floating Point Problems-Footnote-1908729 +Node: Floating point summary908767 +Node: Dynamic Extensions910959 +Node: Extension Intro912511 +Node: Plugin License913777 +Node: Extension Mechanism Outline914574 +Ref: figure-load-extension915002 +Ref: figure-register-new-function916482 +Ref: figure-call-new-function917486 +Node: Extension API Description919472 +Node: Extension API Functions Introduction920922 +Node: General Data Types925758 +Ref: General Data Types-Footnote-1931445 +Node: Memory Allocation Functions931744 +Ref: Memory Allocation Functions-Footnote-1934574 +Node: Constructor Functions934670 +Node: Registration Functions936404 +Node: Extension Functions937089 +Node: Exit Callback Functions939385 +Node: Extension Version String940633 +Node: Input Parsers941283 +Node: Output Wrappers951098 +Node: Two-way processors955614 +Node: Printing Messages957818 +Ref: Printing Messages-Footnote-1958895 +Node: Updating `ERRNO'959047 +Node: Requesting Values959787 +Ref: table-value-types-returned960515 +Node: Accessing Parameters961473 +Node: Symbol Table Access962704 +Node: Symbol table by name963218 +Node: Symbol table by cookie965198 +Ref: Symbol table by cookie-Footnote-1969337 +Node: Cached values969400 +Ref: Cached values-Footnote-1972904 +Node: Array Manipulation972995 +Ref: Array Manipulation-Footnote-1974093 +Node: Array Data Types974132 +Ref: Array Data Types-Footnote-1976789 +Node: Array Functions976881 +Node: Flattening Arrays980735 +Node: Creating Arrays987622 +Node: Extension API Variables992389 +Node: Extension Versioning993025 +Node: Extension API Informational Variables994926 +Node: Extension API Boilerplate996014 +Node: Finding Extensions999830 +Node: Extension Example1000390 +Node: Internal File Description1001162 +Node: Internal File Ops1005229 +Ref: Internal File Ops-Footnote-11016887 +Node: Using Internal File Ops1017027 +Ref: Using Internal File Ops-Footnote-11019410 +Node: Extension Samples1019683 +Node: Extension Sample File Functions1021207 +Node: Extension Sample Fnmatch1028809 +Node: Extension Sample Fork1030291 +Node: Extension Sample Inplace1031504 +Node: Extension Sample Ord1033179 +Node: Extension Sample Readdir1034015 +Ref: table-readdir-file-types1034871 +Node: Extension Sample Revout1035682 +Node: Extension Sample Rev2way1036273 +Node: Extension Sample Read write array1037014 +Node: Extension Sample Readfile1038953 +Node: Extension Sample Time1040048 +Node: Extension Sample API Tests1041397 +Node: gawkextlib1041888 +Node: Extension summary1044538 +Node: Extension Exercises1048220 +Node: Language History1048942 +Node: V7/SVR3.11050599 +Node: SVR41052780 +Node: POSIX1054225 +Node: BTL1055614 +Node: POSIX/GNU1056348 +Node: Feature History1061977 +Node: Common Extensions1075068 +Node: Ranges and Locales1076392 +Ref: Ranges and Locales-Footnote-11081031 +Ref: Ranges and Locales-Footnote-21081058 +Ref: Ranges and Locales-Footnote-31081292 +Node: Contributors1081513 +Node: History summary1087053 +Node: Installation1088422 +Node: Gawk Distribution1089378 +Node: Getting1089862 +Node: Extracting1090686 +Node: Distribution contents1092328 +Node: Unix Installation1098098 +Node: Quick Installation1098715 +Node: Additional Configuration Options1101146 +Node: Configuration Philosophy1102886 +Node: Non-Unix Installation1105237 +Node: PC Installation1105695 +Node: PC Binary Installation1107021 +Node: PC Compiling1108869 +Ref: PC Compiling-Footnote-11111890 +Node: PC Testing1111995 +Node: PC Using1113171 +Node: Cygwin1117286 +Node: MSYS1118109 +Node: VMS Installation1118607 +Node: VMS Compilation1119399 +Ref: VMS Compilation-Footnote-11120621 +Node: VMS Dynamic Extensions1120679 +Node: VMS Installation Details1122363 +Node: VMS Running1124615 +Node: VMS GNV1127456 +Node: VMS Old Gawk1128190 +Node: Bugs1128660 +Node: Other Versions1132564 +Node: Installation summary1138777 +Node: Notes1139833 +Node: Compatibility Mode1140698 +Node: Additions1141480 +Node: Accessing The Source1142405 +Node: Adding Code1143841 +Node: New Ports1150013 +Node: Derived Files1154495 +Ref: Derived Files-Footnote-11159970 +Ref: Derived Files-Footnote-21160004 +Ref: Derived Files-Footnote-31160600 +Node: Future Extensions1160714 +Node: Implementation Limitations1161320 +Node: Extension Design1162568 +Node: Old Extension Problems1163722 +Ref: Old Extension Problems-Footnote-11165239 +Node: Extension New Mechanism Goals1165296 +Ref: Extension New Mechanism Goals-Footnote-11168656 +Node: Extension Other Design Decisions1168845 +Node: Extension Future Growth1170953 +Node: Old Extension Mechanism1171789 +Node: Notes summary1173551 +Node: Basic Concepts1174737 +Node: Basic High Level1175418 +Ref: figure-general-flow1175690 +Ref: figure-process-flow1176289 +Ref: Basic High Level-Footnote-11179518 +Node: Basic Data Typing1179703 +Node: Glossary1183031 +Node: Copying1208189 +Node: GNU Free Documentation License1245745 +Node: Index1270881 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 52c526a4..20087fa7 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -37,11 +37,13 @@ @ifnotdocbook @set BULLET @bullet{} @set MINUS @minus{} +@set NUL @sc{nul} @end ifnotdocbook @ifdocbook @set BULLET @set MINUS +@set NUL NUL @end ifdocbook @set xref-automatic-section-title @@ -51,11 +53,16 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH August, 2014 +@set UPDATE-MONTH September, 2014 @set VERSION 4.1 -@set PATCHLEVEL 1 +@set PATCHLEVEL 2 +@ifset FOR_PRINT +@set TITLE Effective AWK Programming +@end ifset +@ifclear FOR_PRINT @set TITLE GAWK: Effective AWK Programming +@end ifclear @set SUBTITLE A User's Guide for GNU Awk @set EDITION 4.1 @@ -165,6 +172,19 @@ @end macro @end ifdocbook +@c hack for docbook, where comma shouldn't always follow an @ref{} +@ifdocbook +@macro DBREF{text} +@ref{\text\} +@end macro +@end ifdocbook + +@ifnotdocbook +@macro DBREF{text} +@ref{\text\}, +@end macro +@end ifnotdocbook + @ifclear FOR_PRINT @set FN file name @set FFN File Name @@ -526,10 +546,10 @@ particular records in a file and perform operations upon them. * Escape Sequences:: How to write nonprinting characters. * Regexp Operators:: Regular Expression Operators. * Bracket Expressions:: What can go between @samp{[...]}. -* GNU Regexp Operators:: Operators specific to GNU software. -* Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* GNU Regexp Operators:: Operators specific to GNU software. +* Case-sensitivity:: How to do case-insensitive matching. * Regexp Summary:: Regular expressions summary. * Records:: Controlling how data is split into records. @@ -545,8 +565,8 @@ particular records in a file and perform operations upon them. * Regexp Field Splitting:: Using regexps as the field separator. * Single Character Fields:: Making each character a separate field. -* Command Line Field Separator:: Setting @code{FS} from the - command line. +* Command Line Field Separator:: Setting @code{FS} from the command + line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -590,17 +610,19 @@ particular records in a file and perform operations upon them. * Printf Examples:: Several examples. * Redirection:: How to redirect output to multiple files and pipes. +* Special FD:: Special files for I/O. * Special Files:: File name interpretation in @command{gawk}. @command{gawk} allows access to inherited file descriptors. -* Special FD:: Special files for I/O. +* Other Inherited Files:: Accessing other open files with + @command{gawk}. * Special Network:: Special files for network communications. * Special Caveats:: Things to watch out for. * Close Files And Pipes:: Closing Input and Output Files and Pipes. * Output Summary:: Output summary. -* Output exercises:: Exercises. +* Output Exercises:: Exercises. * Values:: Constants, Variables, and Regular Expressions. * Constants:: String, numeric and regexp constants. @@ -686,7 +708,7 @@ particular records in a file and perform operations upon them. record. * Nextfile Statement:: Stop processing the current file. * Exit Statement:: Stop execution of @command{awk}. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * User-modified:: Built-in variables that you change to control @command{awk}. * Auto-set:: Built-in variables where @command{awk} @@ -706,12 +728,12 @@ particular records in a file and perform operations upon them. elements. * Controlling Scanning:: Controlling the order in which arrays are scanned. -* Delete:: The @code{delete} statement removes an - element from an array. * Numeric Array Subscripts:: How to use numbers as subscripts in @command{awk}. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. +* Delete:: The @code{delete} statement removes an + element from an array. * Multidimensional:: Emulating multidimensional arrays in @command{awk}. * Multiscanning:: Scanning multidimensional arrays. @@ -770,6 +792,8 @@ particular records in a file and perform operations upon them. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the + shell. * Data File Management:: Functions for managing command-line data files. * Filetrans Function:: A function for handling data file @@ -787,7 +811,7 @@ particular records in a file and perform operations upon them. information. * Walking Arrays:: A function to walk arrays of arrays. * Library Functions Summary:: Summary of library functions. -* Library exercises:: Exercises. +* Library Exercises:: Exercises. * Running Examples:: How to run these examples. * Clones:: Clones of common utilities. * Cut Program:: The @command{cut} utility. @@ -884,7 +908,6 @@ particular records in a file and perform operations upon them. * Extension API Description:: A full description of the API. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @@ -897,6 +920,7 @@ particular records in a file and perform operations upon them. * Two-way processors:: Registering a two-way processor. * Printing Messages:: Functions for printing messages. * Updating @code{ERRNO}:: Functions for updating @code{ERRNO}. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -935,9 +959,9 @@ particular records in a file and perform operations upon them. processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to @code{gettimeofday()} and @code{sleep()}. +* Extension Sample API Tests:: Tests for the API. * gawkextlib:: The @code{gawkextlib} project. * Extension summary:: Extension summary. * Extension Exercises:: Exercises. @@ -1073,7 +1097,7 @@ 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 input and then perform an action---often reduced complex or tedious -data manipulations to few lines of code. I was excited to try my +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 @@ -1207,7 +1231,7 @@ March, 2001 <affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation> <affiliation><jobtitle>ISRAEL</jobtitle></affiliation> </author> - <date>June, 2014</date> + <date>December, 2014</date> </prefaceinfo> @end docbook @@ -1220,8 +1244,7 @@ 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 -(@pxref{Options}), it is fully -compatible with +it is fully compatible with the POSIX@footnote{The 2008 POSIX standard is accessible online at @w{@url{http://www.opengroup.org/onlinepubs/9699919799/}.}} specification of the @command{awk} language @@ -1229,7 +1252,7 @@ and with the Unix version of @command{awk} maintained by Brian Kernighan. This means that all properly written @command{awk} programs should work with @command{gawk}. -Thus, we usually don't distinguish between @command{gawk} and other +So most of the time, we don't distinguish between @command{gawk} and other @command{awk} implementations. @cindex @command{awk}, POSIX and, See Also POSIX @command{awk} @@ -1238,7 +1261,7 @@ Thus, we usually don't distinguish between @command{gawk} and other @cindex @command{gawk}, @command{awk} and @cindex @command{awk}, @command{gawk} and @cindex @command{awk}, uses for -Using @command{awk} allows you to: +Using @command{awk} you can: @itemize @value{BULLET} @item @@ -1276,15 +1299,15 @@ Sort data Perform simple network communications @item -Profile and debug @command{awk} programs. +Profile and debug @command{awk} programs @item -Extend the language with functions written in C or C++. +Extend the language with functions written in C or C++ @end itemize This @value{DOCUMENT} teaches you about the @command{awk} language and how you can use it effectively. You should already be familiar with basic -system commands, such as @command{cat} and @command{ls},@footnote{These commands +system commands, such as @command{cat} and @command{ls},@footnote{These utilities are available on POSIX-compliant systems, as well as on traditional Unix-based systems. If you are using some other operating system, you still need to be familiar with the ideas of I/O redirection and pipes.} as well as basic shell @@ -1306,10 +1329,9 @@ Microsoft Windows @ifclear FOR_PRINT (all versions) and OS/2 PCs, @end ifclear -and OpenVMS. -(Some other, obsolete systems to which @command{gawk} was once ported -are no longer supported and the code for those systems -has been removed.) +and OpenVMS.@footnote{Some other, obsolete systems to which @command{gawk} +was once ported are no longer supported and the code for those systems +has been removed.} @menu * History:: The history of @command{gawk} and @@ -1386,13 +1408,13 @@ The version in System V Release 4 (1989) added some new features and cleaned up the behavior in some of the ``dark corners'' of the language. The specification for @command{awk} in the POSIX Command Language and Utilities standard further clarified the language. -Both the @command{gawk} designers and the original Bell Laboratories @command{awk} -designers provided feedback for the POSIX specification. +Both the @command{gawk} designers and the original @command{awk} designers at Bell Laboratories +provided feedback for the POSIX specification. @cindex Rubin, Paul @cindex Fenlason, Jay @cindex Trueman, David -Paul Rubin wrote the GNU implementation, @command{gawk}, in 1986. +Paul Rubin wrote @command{gawk} in 1986. Jay Fenlason completed it, with advice from Richard Stallman. John Woods contributed parts of the code as well. In 1988 and 1989, David Trueman, with help from me, thoroughly reworked @command{gawk} for compatibility @@ -1415,7 +1437,7 @@ an @command{awk}-level debugger. This version became available as @command{gawk} @value{PVERSION} 4.0, in 2011. @xref{Contributors}, -for a complete list of those who made important contributions to @command{gawk}. +for a full list of those who made important contributions to @command{gawk}. @node Names @unnumberedsec A Rose by Any Other Name @@ -1424,29 +1446,27 @@ for a complete 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}'' (@command{nawk}). +is often referred to as ``new @command{awk}''. +By analogy, the original version of @command{awk} is +referred to as ``old @command{awk}.'' -@cindex @command{awk}, versions of -@cindex @command{nawk} utility -@cindex @command{oawk} utility -For some time after new @command{awk} was introduced, there were -systems with multiple versions of @command{awk}. Some systems had -an @command{awk} utility that implemented the original version of the -@command{awk} language and a @command{nawk} utility for the new version. -Others had an @command{oawk} version for the ``old @command{awk}'' -language and plain @command{awk} for the new one. Still others only -had one version, which is usually the new one. - -Today, only Solaris systems still use an old @command{awk} for the -default @command{awk} utility. (A more modern @command{awk} lives in -@file{/usr/xpg6/bin} on these systems.) All other modern systems use -some version of new @command{awk}.@footnote{Many of these systems use -@command{gawk} for their @command{awk} implementation!} - -It is likely that you already have some version of new @command{awk} on -your system, which is what you should use when running your programs. -(Of course, if you're reading this @value{DOCUMENT}, chances are good -that you have @command{gawk}!) +Today, on most systems, when you run the @command{awk} utility, +you get some version of new @command{awk}.@footnote{Only +Solaris systems still use an old @command{awk} for the +default @command{awk} utility. A more modern @command{awk} lives in +@file{/usr/xpg6/bin} on these systems.} If your system's standard +@command{awk} is the old one, you will see something like this +if you try the test program: + +@example +$ @kbd{awk 1 /dev/null} +@error{} awk: syntax error near line 1 +@error{} awk: bailing out near line 1 +@end example + +@noindent +In this case, you should find a version of new @command{awk}, +or just install @command{gawk}! Throughout this @value{DOCUMENT}, whenever we refer to a language feature that should be available in any complete implementation of POSIX @command{awk}, @@ -1483,8 +1503,8 @@ entry ``differences in @command{awk} and @command{gawk}.''} @ifset FOR_PRINT implementations. @end ifset -Finally, any @command{gawk} features that are not in -the POSIX standard for @command{awk} are noted. +Finally, it notes any @command{gawk} features that are not in +the POSIX standard for @command{awk}. @ifnotinfo This @value{DOCUMENT} has the difficult task of being both a tutorial and a reference. @@ -1497,11 +1517,13 @@ There are sidebars scattered throughout the @value{DOCUMENT}. They add a more complete explanation of points that are relevant, but not likely to be of interest on first reading. +@ifclear FOR_PRINT All appear in the index, under the heading ``sidebar.'' +@end ifclear 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 currently being described. +program that illustrates the concept being described. While this @value{DOCUMENT} is aimed principally at people who have not been exposed @@ -1549,7 +1571,7 @@ for getting most things done in a program. @ref{Patterns and Actions}, describes how to write patterns for matching records, actions for -doing something when a record is matched, and the built-in variables +doing something when a record is matched, and the predefined variables @command{awk} and @command{gawk} use. @ref{Arrays}, @@ -1559,9 +1581,9 @@ sorting arrays in @command{gawk}. It also describes how @command{gawk} provides arrays of arrays. @ref{Functions}, -describes the built-in functions @command{awk} and -@command{gawk} provide, as well as how to define -your own 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. 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. @@ -1580,21 +1602,21 @@ Part III focuses on features specific to @command{gawk}. It contains the following chapters: @ref{Advanced Features}, -describes a number of @command{gawk}-specific advanced features. +describes a number of advanced features. Of particular note -are the abilities to have two-way communications with another process, +are the abilities to control the order of array traversal, +have two-way communications with another process, perform TCP/IP networking, and profile your @command{awk} programs. @ref{Internationalization}, -describes special features in @command{gawk} for translating program +describes special features for translating program messages into different languages at runtime. -@ref{Debugger}, describes the @command{awk} debugger. +@ref{Debugger}, describes the @command{gawk} debugger. @ref{Arbitrary Precision Arithmetic}, -describes advanced arithmetic facilities provided by -@command{gawk}. +describes advanced arithmetic facilities. @ref{Dynamic Extensions}, describes how to add new variables and functions to @command{gawk} by writing extensions in C or C++. @@ -1634,9 +1656,10 @@ printed edition. You may find them online, as follows: @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, as -well as how to contribute new code to @command{gawk}, -and some possible future directions for @command{gawk} development. +describes how to disable @command{gawk}'s extensions, how to contribute +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. @uref{http://www.gnu.org/software/gawk/manual/html_node/Basic-Concepts.html, The appendix on basic concepts} @@ -1652,6 +1675,9 @@ try looking them up here. @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}. + +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 @@ -1773,9 +1799,10 @@ the picture of a flashlight in the margin, as shown here. They also appear in the index under the heading ``dark corner.'' @end ifclear -As noted by the opening quote, though, any coverage of dark corners is, -by definition, incomplete. +But, as noted by the opening quote, any coverage of dark +corners is by definition incomplete. +@cindex c.e., See common extensions Extensions to the standard @command{awk} language that are supported by more than one @command{awk} implementation are marked @ifclear FOR_PRINT @@ -1847,9 +1874,7 @@ available for download from the Internet. @ifnotinfo The @value{DOCUMENT} you are reading is actually free---at least, the information in it is free to anyone. The machine-readable -source code for the @value{DOCUMENT} comes with @command{gawk}; anyone -may take this @value{DOCUMENT} to a copying machine and make as many -copies as they like. +source code for the @value{DOCUMENT} comes with @command{gawk}. @ifclear FOR_PRINT (Take a moment to check the Free Documentation License in @ref{GNU Free Documentation License}.) @@ -1857,7 +1882,7 @@ License in @ref{GNU Free Documentation License}.) @end ifnotinfo @cindex Close, Diane -The @value{DOCUMENT} itself has gone through a number of previous editions. +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. Diane Close and Richard Stallman improved it, yielding a @@ -1873,15 +1898,14 @@ The FSF published the first two editions under the title @cite{The GNU Awk User's Guide}. @ifset FOR_PRINT SSC published two editions of the @value{DOCUMENT} under the -title @cite{Effective awk Programming}, and in O'Reilly published +title @cite{Effective awk Programming}, and O'Reilly published the third edition in 2001. @end ifset This edition maintains the basic structure of the previous editions. -For FSF edition 4.0, the content has been thoroughly reviewed -and updated. All references to @command{gawk} versions prior to 4.0 have been -removed. -Of significant note for this edition was @ref{Debugger}. +For FSF edition 4.0, the content was thoroughly reviewed and updated. All +references to @command{gawk} versions prior to 4.0 were removed. +Of significant note for that edition was @ref{Debugger}. For FSF edition @ifclear FOR_PRINT @@ -1895,8 +1919,7 @@ the content has been reorganized into parts, and the major new additions are @ref{Arbitrary Precision Arithmetic}, and @ref{Dynamic Extensions}. -This @value{DOCUMENT} will undoubtedly continue to evolve. An electronic -version comes with the @command{gawk} distribution from the FSF. If you +This @value{DOCUMENT} will undoubtedly continue to evolve. If you find an error in this @value{DOCUMENT}, please report it! @xref{Bugs}, for information on submitting problem reports electronically. @@ -1905,7 +1928,7 @@ for information on submitting problem reports electronically. @unnumberedsec How to Stay Current It may be you have a version of @command{gawk} which is newer than the -one described in this @value{DOCUMENT}. To find out what has changed, +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 each release. @@ -2077,15 +2100,24 @@ Andrew Schorr, Corinna Vinschen, and Eli Zaretskii (in alphabetical order) -make up the current -@command{gawk} ``crack portability team.'' Without their hard work and -help, @command{gawk} would not be nearly the fine program it is today. It -has been and continues to be a pleasure working with this team of fine -people. +make up the current @command{gawk} ``crack portability team.'' Without +their hard work and help, @command{gawk} would not be nearly the robust, +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. +@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. +@end ifset + +Thanks to Michael Brennan for the Foreword. + +@cindex Duman, Patrice +@cindex Berry, Karl Thanks to Patrice Dumas for the new @command{makeinfo} program. Thanks to Karl Berry who continues to work to keep the Texinfo markup language sane. @@ -2127,7 +2159,7 @@ take advantage of those opportunities. Arnold Robbins @* Nof Ayalon @* ISRAEL @* -May, 2014 +December, 2014 @end iftex @ifnotinfo @@ -2343,27 +2375,22 @@ For example, on OS/2, it is @kbd{Ctrl-z}.) As an example, the following program prints a friendly piece of advice (from Douglas Adams's @cite{The Hitchhiker's Guide to the Galaxy}), to keep you from worrying about the complexities of computer -programming (@code{BEGIN} is a feature we haven't discussed yet): +programming: @example -$ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} +$ @kbd{awk 'BEGIN @{ print "Don\47t Panic!" @}'} @print{} Don't Panic! @end example -@cindex shell quoting, double quote -@cindex double quote (@code{"}) in shell commands -@cindex @code{"} (double quote) in shell commands -@cindex @code{\} (backslash) in shell commands -@cindex backslash (@code{\}) in shell commands -This program does not read any input. The @samp{\} before each of the -inner double quotes is necessary because of the shell's quoting -rules---in particular because it mixes both single quotes and -double quotes.@footnote{Although we generally recommend the use of single -quotes around the program text, double quotes are needed here in order to -put the single quote into the message.} +@command{awk} executes statements associated with @code{BEGIN} before +reading any input. If there are no other statements in your program, +as is the case here, @command{awk} just stops, instead of trying to read +input it doesn't know how to process. +The @samp{\47} is a magic way (explained later) of getting a single quote into +the program, without having to engage in ugly shell quoting tricks. @quotation NOTE -As a side note, if you use Bash as your shell, you should execute the +If you use Bash as your shell, you should execute the command @samp{set +H} before running this program interactively, to disable the C shell-style command history, which treats @samp{!} as a special character. We recommend putting this command into your personal @@ -2393,7 +2420,7 @@ $ @kbd{awk '@{ print @}'} @cindex @command{awk} programs, running @cindex @command{awk} programs, lengthy @cindex files, @command{awk} programs in -Sometimes your @command{awk} programs can be very long. In this case, it is +Sometimes @command{awk} programs are very long. In these cases, it is more convenient to put the program into a separate file. In order to tell @command{awk} to use that file for its program, you type: @@ -2423,7 +2450,7 @@ awk -f advice does the same thing as this one: @example -awk "BEGIN @{ print \"Don't Panic!\" @}" +awk 'BEGIN @{ print "Don\47t Panic!" @}' @end example @cindex quoting in @command{gawk} command lines @@ -2435,6 +2462,8 @@ specify with @option{-f}, because most @value{FN}s don't contain any of the shel special characters. Notice that in @file{advice}, the @command{awk} program did not have single quotes around it. The quotes are only needed for programs that are provided on the @command{awk} command line. +(Also, placing the program in a file allows us to use a literal single quote in the program +text, instead of the magic @samp{\47}.) @c STARTOFRANGE sq1x @cindex single quote (@code{'}) in @command{gawk} command lines @@ -2467,16 +2496,7 @@ BEGIN @{ print "Don't Panic!" @} @noindent After making this file executable (with the @command{chmod} utility), simply type @samp{advice} -at the shell and the system arranges to run @command{awk}@footnote{The -line beginning with @samp{#!} lists the full @value{FN} of an interpreter -to run and a single optional initial command-line argument to pass to that -interpreter. The operating system then runs the interpreter with the given -argument and the full argument list of the executed program. The first argument -in the list is the full @value{FN} of the @command{awk} program. -The rest of the -argument list contains either options to @command{awk}, or @value{DF}s, -or both. Note that on many systems @command{awk} may be found in -@file{/usr/bin} instead of in @file{/bin}. Caveat Emptor.} as if you had +at the shell and the system arranges to run @command{awk} as if you had typed @samp{awk -f advice}: @example @@ -2494,14 +2514,32 @@ Self-contained @command{awk} scripts are useful when you want to write a program that users can invoke without their having to know that the program is written in @command{awk}. -@cindex sidebar, Portability Issues with @samp{#!} +@cindex sidebar, Understanding @samp{#!} @ifdocbook @docbook -<sidebar><title>Portability Issues with @samp{#!}</title> +<sidebar><title>Understanding @samp{#!}</title> @end docbook @cindex portability, @code{#!} (executable scripts) +@command{awk} is an @dfn{interpreted} language. This means that the +@command{awk} utility reads your program and then processes your data +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. + +The line beginning with @samp{#!} lists the full @value{FN} of an +interpreter to run and a single optional initial command-line argument +to pass to that interpreter. The operating system then runs the +interpreter with the given argument and the full argument list of the +executed program. The first argument in the list is the full @value{FN} +of the @command{awk} program. The rest of the argument list contains +either options to @command{awk}, or @value{DF}s, or both. (Note that on +many systems @command{awk} may be found in @file{/usr/bin} instead of +in @file{/bin}.) + Some systems limit the length of the interpreter name to 32 characters. Often, this can be dealt with by using a symbolic link. @@ -2513,8 +2551,7 @@ of some sort from @command{awk}. @cindex @code{ARGC}/@code{ARGV} variables, portability and @cindex portability, @code{ARGV} variable -Finally, -the value of @code{ARGV[0]} +Finally, the value of @code{ARGV[0]} (@pxref{Built-in Variables}) varies depending upon your operating system. Some systems put @samp{awk} there, some put the full pathname @@ -2530,11 +2567,29 @@ to provide your script name. @ifnotdocbook @cartouche -@center @b{Portability Issues with @samp{#!}} +@center @b{Understanding @samp{#!}} @cindex portability, @code{#!} (executable scripts) +@command{awk} is an @dfn{interpreted} language. This means that the +@command{awk} utility reads your program and then processes your data +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. + +The line beginning with @samp{#!} lists the full @value{FN} of an +interpreter to run and a single optional initial command-line argument +to pass to that interpreter. The operating system then runs the +interpreter with the given argument and the full argument list of the +executed program. The first argument in the list is the full @value{FN} +of the @command{awk} program. The rest of the argument list contains +either options to @command{awk}, or @value{DF}s, or both. (Note that on +many systems @command{awk} may be found in @file{/usr/bin} instead of +in @file{/bin}.) + Some systems limit the length of the interpreter name to 32 characters. Often, this can be dealt with by using a symbolic link. @@ -2546,8 +2601,7 @@ of some sort from @command{awk}. @cindex @code{ARGC}/@code{ARGV} variables, portability and @cindex portability, @code{ARGV} variable -Finally, -the value of @code{ARGV[0]} +Finally, the value of @code{ARGV[0]} (@pxref{Built-in Variables}) varies depending upon your operating system. Some systems put @samp{awk} there, some put the full pathname @@ -2713,8 +2767,14 @@ Thus, the example seen @ifnotinfo previously @end ifnotinfo -in @ref{Read Terminal}, -is applicable: +in @ref{Read Terminal}: + +@example +awk 'BEGIN @{ print "Don\47t Panic!" @}' +@end example + +@noindent +could instead be written this way: @example $ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} @@ -2744,7 +2804,7 @@ awk -F"" '@var{program}' @var{files} # wrong! @end example @noindent -In the second case, @command{awk} will attempt to use the text of the program +In the second case, @command{awk} attempts to use the text of the program as the value of @code{FS}, and the first @value{FN} as the text of the program! This results in syntax errors at best, and confusing behavior at worst. @end itemize @@ -2809,6 +2869,9 @@ $ awk -v sq="'" 'BEGIN @{ print "Here is a single quote <" sq ">" @}' @print{} Here is a single quote <'> @end example +(Here, the two string constants and the value of @code{sq} are concatenated +into a single string which is printed by @code{print}.) + If you really need both single and double quotes in your @command{awk} program, it is probably best to move it into a separate file, where the shell won't be part of the picture, and you can say what you mean. @@ -2872,7 +2935,7 @@ The second @value{DF}, called @file{inventory-shipped}, contains information about monthly shipments. In both files, each line is considered to be one @dfn{record}. -In the @value{DF} @file{mail-list}, each record contains the name of a person, +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 with the author of the list. The columns are aligned using spaces. @@ -2910,6 +2973,7 @@ of green crates shipped, the number of red boxes shipped, the number of orange bags shipped, and the number of blue packages shipped, respectively. There are 16 entries, covering the 12 months of last year and the first four months of the current year. +An empty line separates the data for the two years. @example @c file eg/data/inventory-shipped @@ -3005,22 +3069,25 @@ you can come up with different ways to do the same things shown here: @itemize @value{BULLET} @item -Print the length of the longest input line: +Print every line that is longer than 80 characters: @example -awk '@{ if (length($0) > max) max = length($0) @} - END @{ print max @}' data +awk 'length($0) > 80' data @end example +The sole rule has a relational expression as its pattern and it has no +action---so it uses the default action, printing the record. + @item -Print every line that is longer than 80 characters: +Print the length of the longest input line: @example -awk 'length($0) > 80' data +awk '@{ if (length($0) > max) max = length($0) @} + END @{ print max @}' data @end example -The sole rule has a relational expression as its pattern and it has no -action---so it uses the default action, printing the record. +The code associated with @code{END} executes after all +input has been read; it's the other side of the coin to @code{BEGIN}. @cindex @command{expand} utility @item @@ -3028,10 +3095,10 @@ Print the length of the longest line in @file{data}: @example expand data | awk '@{ if (x < length($0)) x = length($0) @} - END @{ print "maximum line length is " x @}' + END @{ print "maximum line length is " x @}' @end example -This example differs slightly from the first example in this list: +This example differs slightly from the previous one: 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. @@ -3060,7 +3127,7 @@ Print the total number of bytes used by @var{files}: @example ls -l @var{files} | awk '@{ x += $5 @} - END @{ print "total bytes: " x @}' + END @{ print "total bytes: " x @}' @end example @item @@ -3104,7 +3171,7 @@ the program would print the odd-numbered lines. @cindex @command{awk} programs The @command{awk} utility reads the input files one line at a -time. For each line, @command{awk} tries the patterns of each of the rules. +time. For each line, @command{awk} tries the patterns of each rule. If several patterns match, then several actions execute in the order in which they appear in the @command{awk} program. If no patterns match, then no actions run. @@ -3112,7 +3179,7 @@ no actions run. After processing all the rules that match the line (and perhaps there are none), @command{awk} reads the next line. (However, @pxref{Next Statement}, -and also @pxref{Nextfile Statement}). +and also @pxref{Nextfile Statement}.) This continues until the program reaches the end of the file. For example, the following @command{awk} program contains two rules: @@ -3161,8 +3228,8 @@ features that haven't been covered yet, so don't worry if you don't understand all the details: @example -LC_ALL=C ls -l | awk '$6 == "Nov" @{ sum += $5 @} - END @{ print sum @}' +ls -l | awk '$6 == "Nov" @{ sum += $5 @} + END @{ print sum @}' @end example @cindex @command{ls} utility @@ -3186,13 +3253,12 @@ the file was last modified. Its output looks like this: @noindent @cindex line continuations, with C shell The first field contains read-write permissions, the second field contains -the number of links to the file, and the third field identifies the owner of -the file. The fourth field identifies the group of the file. -The fifth field contains the size of the file in bytes. The +the number of links to the file, and the third field identifies the file's owner. +The fourth field identifies the file's group. +The fifth field contains the file's size in bytes. The sixth, seventh, and eighth fields contain the month, day, and time, respectively, that the file was last modified. Finally, the ninth field -contains the @value{FN}.@footnote{The @samp{LC_ALL=C} is -needed to produce this traditional-style output from @command{ls}.} +contains the @value{FN}. @c @cindex automatic initialization @cindex initialization, automatic @@ -3380,7 +3446,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 +systematically in @ref{Built-in Variables}, and in @ref{Built-in}. @node When @@ -3415,9 +3481,7 @@ eight-bit microprocessors, 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. Even BWK @command{awk} -has fewer predefined limits, and those -that it has are much larger than they used to be. +of such complexity, modern versions are more capable. @cindex @command{awk} programs, complex If you find yourself writing @command{awk} scripts of more than, say, @@ -3431,11 +3495,16 @@ and Perl.} @node Intro Summary @section Summary +@c FIXME: Review this chapter for summary of builtin functions called. @itemize @value{BULLET} @item Programs in @command{awk} consist of @var{pattern}-@var{action} pairs. @item +An @var{action} without a @var{pattern} always runs. The default +@var{action} for a pattern without one is @samp{@{ print $0 @}}. + +@item Use either @samp{awk '@var{program}' @var{files}} or @@ -3593,13 +3662,13 @@ The @option{-v} option can only set one variable, but it can be used more than once, setting another variable each time, like this: @samp{awk @w{-v foo=1} @w{-v bar=2} @dots{}}. -@cindex built-in variables, @code{-v} option@comma{} setting with -@cindex variables, built-in, @code{-v} option@comma{} setting with +@cindex predefined variables, @code{-v} option@comma{} setting with +@cindex variables, predefined @code{-v} option@comma{} setting with @quotation CAUTION Using @option{-v} to set the values of the built-in variables may lead to surprising results. @command{awk} will reset the values of those variables as it needs to, possibly ignoring any -predefined value you may have given. +initial value you may have given. @end quotation @item -W @var{gawk-opt} @@ -3682,7 +3751,7 @@ Print the short version of the General Public License and then exit. @cindex variables, global, printing list of Print a sorted list of global variables, their types, and final values to @var{file}. If no @var{file} is provided, print this -list to the file named @file{awkvars.out} in the current directory. +list to a file named @file{awkvars.out} in the current directory. No space is allowed between the @option{-d} and @var{file}, if @var{file} is supplied. @@ -3778,7 +3847,7 @@ that @command{gawk} accepts and then exit. @cindex @option{-i} option @cindex @option{--include} option @cindex @command{awk} programs, location of -Read @command{awk} source library from @var{source-file}. This option +Read an @command{awk} source library from @var{source-file}. This option is completely equivalent to using the @code{@@include} directive inside your program. This option is very similar to the @option{-f} option, but there are two important differences. First, when @option{-i} is @@ -3802,7 +3871,7 @@ environment variable. The correct library suffix for your platform will be supplied by default, so it need not be specified in the extension name. The extension initialization routine should be named @code{dl_load()}. An alternative is to use the @code{@@load} keyword inside the program to load -a shared library. This feature is described in detail in @ref{Dynamic Extensions}. +a shared library. This advanced feature is described in detail in @ref{Dynamic Extensions}. @item @option{-L}[@var{value}] @itemx @option{--lint}[@code{=}@var{value}] @@ -3851,6 +3920,8 @@ values in input data @quotation CAUTION This option can severely break old programs. Use with care. + +This option may disappear in a future version of @command{gawk}. @end quotation @item @option{-N} @@ -4014,6 +4085,7 @@ 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. +The @option{-i} option is similar in this regard. (As mentioned in @ref{Definition Syntax}, function names must be unique.) @@ -4087,15 +4159,18 @@ Any additional arguments on the command line are normally treated as input files to be processed in the order specified. However, an argument that has the form @code{@var{var}=@var{value}}, assigns the value @var{value} to the variable @var{var}---it does not specify a -file at all. -(See -@ref{Assignment Options}.) +file at all. (See @ref{Assignment Options}.) In the following example, +@var{count=1} is a variable assignment, not a @value{FN}: + +@example +awk -f program.awk file1 count=1 file2 +@end example @cindex @command{gawk}, @code{ARGIND} variable in @cindex @code{ARGIND} variable, command-line arguments @cindex @code{ARGV} array, indexing into @cindex @code{ARGC}/@code{ARGV} variables, command-line arguments -All these arguments are made available to your @command{awk} program in the +All the command-line arguments are made available to your @command{awk} program in the @code{ARGV} array (@pxref{Built-in Variables}). Command-line options and the program text (if present) are omitted from @code{ARGV}. All other arguments, including variable assignments, are @@ -4103,6 +4178,11 @@ included. As each element of @code{ARGV} is processed, @command{gawk} sets the variable @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. +Changing @code{ARGC} and @code{ARGV} in your @command{awk} program lets +you control how @command{awk} processes the input files; this is described +in more detail in @ref{ARGC and ARGV}. + @cindex input files, variable assignments and @cindex variable assignments and input files The distinction between @value{FN} arguments and variable-assignment @@ -4221,15 +4301,15 @@ separated by colons@footnote{Semicolons on MS-Windows and MS-DOS.}. @command{ga @samp{.:/usr/local/share/awk}.@footnote{Your version of @command{gawk} may use a different directory; it will depend upon how @command{gawk} was built and installed. The actual -directory is the value of @samp{$(datadir)} generated when +directory is the value of @code{$(datadir)} generated when @command{gawk} was configured. You probably don't need to worry about this, though.} The search path feature is particularly helpful for building libraries of useful @command{awk} functions. The library files can be placed in a standard directory in the default path and then specified on -the command line with a short @value{FN}. Otherwise, the full @value{FN} -would have to be typed for each file. +the command line with a short @value{FN}. Otherwise, you would have to +type the full @value{FN} for each file. By using the @option{-i} option, or the @option{-e} and @option{-f} options, your command-line @command{awk} programs can use facilities in @command{awk} library files @@ -4238,25 +4318,23 @@ Path searching is not done if @command{gawk} is in compatibility mode. This is true for both @option{--traditional} and @option{--posix}. @xref{Options}. -If the source code is not found after the initial search, the path is searched +If the source code file is not found after the initial search, the path is searched again after adding the default @samp{.awk} suffix to the @value{FN}. -@quotation NOTE -@c 4/2014: -@c using @samp{.} to get quotes, since @file{} no longer supplies them. -To include -the current directory in the path, either place -@samp{.} explicitly in the path or write a null entry in the -path. (A null entry is indicated by starting or ending the path with a -colon or by placing two colons next to each other [@samp{::}].) -This path search mechanism is similar +@command{gawk}'s path search mechanism is similar to the shell's. (See @uref{http://www.gnu.org/software/bash/manual/, -@cite{The Bourne-Again SHell manual}.}) +@cite{The Bourne-Again SHell manual}}.) +It treats a null entry in the path as indicating the current +directory. +(A null entry is indicated by starting or ending the path with a +colon or by placing two colons next to each other [@samp{::}].) -However, @command{gawk} always looks in the current directory @emph{before} -searching @env{AWKPATH}, so there is no real reason to include -the current directory in the search path. +@quotation NOTE +@command{gawk} always looks in the current directory @emph{before} +searching @env{AWKPATH}. Thus, while you can include the current directory +in the search path, either explicitly or with a null entry, there is no +real reason to do so. @c Prior to 4.0, gawk searched the current directory after the @c path search, but it's not worth documenting it. @end quotation @@ -4297,16 +4375,6 @@ behavior, but they are more specialized. Those in the following list are meant to be used by regular users. @table @env -@item POSIXLY_CORRECT -Causes @command{gawk} to switch to POSIX compatibility -mode, disabling all traditional and GNU extensions. -@xref{Options}. - -@item GAWK_SOCK_RETRIES -Controls the number of times @command{gawk} attempts to -retry a two-way TCP/IP (socket) connection before giving up. -@xref{TCP/IP Networking}. - @item GAWK_MSEC_SLEEP Specifies the interval between connection retries, in milliseconds. On systems that do not support @@ -4317,6 +4385,16 @@ the value is rounded up to an integral number of seconds. Specifies the time, in milliseconds, for @command{gawk} to wait for input before returning with an error. @xref{Read Timeout}. + +@item GAWK_SOCK_RETRIES +Controls the number of times @command{gawk} attempts to +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 +mode, disabling all traditional and GNU extensions. +@xref{Options}. @end table The environment variables in the following list are meant @@ -4331,7 +4409,7 @@ file as the size of the memory buffer to allocate for I/O. Otherwise, the value should be a number, and @command{gawk} uses that number as the size of the buffer to allocate. (When this variable is not set, @command{gawk} uses the smaller of the file's size and the ``default'' -blocksize, which is usually the filesystems I/O blocksize.) +blocksize, which is usually the filesystem's I/O blocksize.) @item AWK_HASH If this variable exists with a value of @samp{gst}, @command{gawk} @@ -4346,10 +4424,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 source file -name and line number from which warning and/or fatal messages +If this variable exists, @command{gawk} includes the file +name 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 can be multiple places which produce the +message, since there are multiple places which produce the same warning or error message. @item GAWK_NO_DFA @@ -4365,11 +4444,11 @@ This specifies the amount by which @command{gawk} should grow its internal evaluation stack, when needed. @item INT_CHAIN_MAX -The average number of items @command{gawk} will maintain on a +The intended maximum number of items @command{gawk} will maintain on a hash chain for managing arrays indexed by integers. @item STR_CHAIN_MAX -The average number of items @command{gawk} will maintain on a +The intended maximum number of items @command{gawk} will maintain on a hash chain for managing arrays indexed by strings. @item TIDYMEM @@ -4404,6 +4483,9 @@ to @code{EXIT_FAILURE}. This @value{SECTION} describes a feature that is specific to @command{gawk}. +@cindex @code{@@include} directive +@cindex file inclusion, @code{@@include} directive +@cindex including files, @code{@@include} directive The @code{@@include} keyword can be used to read external @command{awk} source files. This gives you the ability to split large @command{awk} source files into smaller, more manageable pieces, and also lets you reuse common @command{awk} @@ -4439,8 +4521,8 @@ produces the following result: @example $ @kbd{gawk -f test2} -@print{} This is file test1. -@print{} This is file test2. +@print{} This is script test1. +@print{} This is script test2. @end example @code{gawk} runs the @file{test2} script which includes @file{test1} @@ -4470,9 +4552,9 @@ following results: @example $ @kbd{gawk -f test3} -@print{} This is file test1. -@print{} This is file test2. -@print{} This is file test3. +@print{} This is script test1. +@print{} This is script test2. +@print{} This is script test3. @end example The @value{FN} can, of course, be a pathname. For example: @@ -4523,6 +4605,9 @@ and this also applies to files named with @code{@@include}. This @value{SECTION} describes a feature that is specific to @command{gawk}. +@cindex @code{@@load} directive +@cindex loading extensions, @code{@@load} directive +@cindex extensions, loading, @code{@@load} directive 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 @@ -4556,6 +4641,7 @@ that requires access to an extension. @ref{Dynamic Extensions}, describes how to write extensions (in C or C++) that can be loaded with either @code{@@load} or the @option{-l} option. +It also describes the @code{ordchr} extension. @node Obsolete @section Obsolete Options and/or Features @@ -4624,15 +4710,15 @@ awk '@{ sum += $1 @} END @{ print sum @}' @end example @command{gawk} actually supports this but it is purposely undocumented -because it is considered bad style. The correct way to write such a program -is either +because it is bad style. The correct way to write such a program +is either: @example awk '@{ sum += $1 @} ; END @{ print sum @}' @end example @noindent -or +or: @example awk '@{ sum += $1 @} @@ -4640,8 +4726,7 @@ awk '@{ sum += $1 @} @end example @noindent -@xref{Statements/Lines}, for a fuller -explanation. +@xref{Statements/Lines}, for a fuller explanation. You can insert newlines after the @samp{;} in @code{for} loops. This seems to have been a long-undocumented feature in Unix @command{awk}. @@ -4681,7 +4766,8 @@ affects how @command{awk} processes input. @item You can use a single minus sign (@samp{-}) to refer to standard input -on the command line. +on the command line. @command{gawk} also lets you use the special +@value{FN} @file{/dev/stdin}. @item @command{gawk} pays attention to a number of environment variables. @@ -4724,7 +4810,7 @@ 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 -the three characters @samp{foo} @emph{anywhere} in the record. Other +the three adjacent characters @samp{foo} @emph{anywhere} in the record. Other kinds of regexps let you specify more complicated classes of strings. @ifnotinfo @@ -4738,10 +4824,10 @@ regular expressions work, we present more complicated instances. * Escape Sequences:: How to write nonprinting characters. * Regexp Operators:: Regular Expression Operators. * Bracket Expressions:: What can go between @samp{[...]}. -* GNU Regexp Operators:: Operators specific to GNU software. -* Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* GNU Regexp Operators:: Operators specific to GNU software. +* Case-sensitivity:: How to do case-insensitive matching. * Regexp Summary:: Regular expressions summary. @end menu @@ -4870,7 +4956,7 @@ such as TAB or newline. While there is nothing to stop you from entering most unprintable characters directly in a string constant or regexp constant, they may look ugly. -The following table lists +The following list presents all the escape sequences used in @command{awk} and what they represent. Unless noted otherwise, all these escape sequences apply to both string constants and regexp constants: @@ -4952,8 +5038,11 @@ However, using more than two hexadecimal digits produces @item \/ A literal slash (necessary for regexp constants only). This sequence is used when you want to write a regexp -constant that contains a slash. Because the regexp is delimited by -slashes, you need to escape the slash that is part of the pattern, +constant that contains a slash +(such as @code{/.*:\/home\/[[:alnum:]]+:.*/}; the @samp{[[:alnum:]]} +notation is discussed shortly, 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. @cindex @code{\} (backslash), @code{\"} escape sequence @@ -4961,8 +5050,10 @@ in order to tell @command{awk} to keep processing the rest of the regexp. @item \" A literal double quote (necessary for string constants only). This sequence is used when you want to write a string -constant that contains a double quote. Because the string is delimited by -double quotes, you need to escape the quote that is part of the string, +constant that contains a double quote +(such as @code{"He said \"hi!\" to her."}). +Because the string is delimited by +double quotes, you need to escape any quote that is part of the string, in order to tell @command{awk} to keep processing the rest of the string. @end table @@ -4981,13 +5072,13 @@ characters @samp{a+b}. @cindex @code{\} (backslash), in escape sequences @cindex portability For complete portability, do not use a backslash before any character not -shown in the previous list. +shown in the previous list and that is not an operator. To summarize: @itemize @value{BULLET} @item -The escape sequences in the table above are always processed first, +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. @@ -5154,13 +5245,13 @@ The escape sequences described @ifnotinfo earlier @end ifnotinfo -in @ref{Escape Sequences}, +in @DBREF{Escape Sequences} are valid inside a regexp. They are introduced by a @samp{\} and are recognized and converted into corresponding real characters as the very first step in processing regexps. Here is a list of metacharacters. All characters that are not escape -sequences and that are not listed in the table stand for themselves: +sequences and that are not listed in the following stand for themselves: @c Use @asis so the docbook comes out ok. Sigh. @table @asis @@ -5217,10 +5308,10 @@ with @samp{A}. @cindex POSIX @command{awk}, period (@code{.})@comma{} using In strict POSIX mode (@pxref{Options}), -@samp{.} does not match the @sc{nul} +@samp{.} does not match the @value{NUL} character, which is a character with all bits equal to zero. -Otherwise, @sc{nul} is just another character. Other versions of @command{awk} -may not be able to match the @sc{nul} character. +Otherwise, @value{NUL} is just another character. Other versions of @command{awk} +may not be able to match the @value{NUL} character. @cindex @code{[]} (square brackets), regexp operator @cindex square brackets (@code{[]}), regexp operator @@ -5251,12 +5342,11 @@ or @samp{k}. @cindex vertical bar (@code{|}) @item @code{|} This is the @dfn{alternation operator} and it is used to specify -alternatives. -The @samp{|} has the lowest precedence of all the regular -expression operators. -For example, @samp{^P|[[:digit:]]} -matches any string that matches either @samp{^P} or @samp{[[:digit:]]}. This -means it matches any string that starts with @samp{P} or contains a digit. +alternatives. The @samp{|} has the lowest precedence of all the regular +expression operators. For example, @samp{^P|[aeiouy]} matches any string +that matches either @samp{^P} or @samp{[aeiouy]}. This means it matches +any string that starts with @samp{P} or contains (anywhere within it) +a lowercase English vowel. The alternation applies to the largest possible regexps on either side. @@ -5280,14 +5370,15 @@ applies the @samp{*} symbol to the preceding @samp{h} and looks for matches of one @samp{p} followed by any number of @samp{h}s. This also matches just @samp{p} if no @samp{h}s are present. -The @samp{*} repeats the @emph{smallest} possible preceding expression. -(Use parentheses if you want to repeat a larger expression.) It finds -as many repetitions as possible. For example, -@samp{awk '/\(c[ad][ad]*r x\)/ @{ print @}' sample} -prints every record in @file{sample} containing a string of the form -@samp{(car x)}, @samp{(cdr x)}, @samp{(cadr x)}, and so on. -Notice the escaping of the parentheses by preceding them -with backslashes. +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. + +Second, @samp{*} finds as many repetitions as possible. If the text +to be matched is @samp{phhhhhhhhhhhhhhooey}, @samp{ph*} matches all of +the @samp{h}s. @cindex @code{+} (plus sign), regexp operator @cindex plus sign (@code{+}), regexp operator @@ -5296,12 +5387,6 @@ This symbol is similar to @samp{*}, except that the preceding expression must be matched at least once. This means that @samp{wh+y} would match @samp{why} and @samp{whhy}, but not @samp{wy}, whereas @samp{wh*y} would match all three. -The following is a simpler -way of writing the last @samp{*} example: - -@example -awk '/\(c[ad]+r x\)/ @{ print @}' sample -@end example @cindex @code{?} (question mark), regexp operator @cindex question mark (@code{?}), regexp operator @@ -5396,7 +5481,7 @@ Within a bracket expression, a @dfn{range expression} consists of two characters separated by a hyphen. It matches any single character that sorts between the two characters, based upon the system's native character set. For example, @samp{[0-9]} is equivalent to @samp{[0123456789]}. -(See @ref{Ranges and Locales}, for an explanation of how the POSIX +(See @DBREF{Ranges and Locales} for an explanation of how the POSIX standard and @command{gawk} have changed over time. This is mainly of historical interest.) @@ -5415,12 +5500,15 @@ bracket expression, put a @samp{\} in front of it. For example: @noindent matches either @samp{d} or @samp{]}. +Additionally, if you place @samp{]} right after the opening +@samp{[}, the closing bracket is treated as one of the +characters to be matched. @cindex POSIX @command{awk}, bracket expressions and @cindex Extended Regular Expressions (EREs) @cindex EREs (Extended Regular Expressions) @cindex @command{egrep} utility -This treatment of @samp{\} in bracket expressions +The treatment of @samp{\} in bracket expressions is compatible with other @command{awk} implementations and is also mandated by POSIX. The regular expressions in @command{awk} are a superset @@ -5526,6 +5614,204 @@ they do not recognize collating symbols or equivalence classes. @c maybe one day ... @c ENDOFRANGE charlist +@node Leftmost Longest +@section How Much Text Matches? + +@cindex regular expressions, leftmost longest match +@c @cindex matching, leftmost longest +Consider the following: + +@example +echo aaaabcd | awk '@{ sub(/a+/, "<A>"); print @}' +@end example + +This example uses the @code{sub()} function to make a change to the input +record. (@code{sub()} replaces the first instance of any text matched +by the first argument with the string provided as the second argument; +@pxref{String Functions}). Here, the regexp @code{/a+/} indicates ``one +or more @samp{a} characters,'' and the replacement text is @samp{<A>}. + +The input contains four @samp{a} characters. +@command{awk} (and POSIX) regular expressions always match +the leftmost, @emph{longest} sequence of input characters that can +match. Thus, all four @samp{a} characters are +replaced with @samp{<A>} in this example: + +@example +$ @kbd{echo aaaabcd | awk '@{ sub(/a+/, "<A>"); print @}'} +@print{} <A>bcd +@end example + +For simple match/no-match tests, this is not so important. But when doing +text matching and substitutions with the @code{match()}, @code{sub()}, @code{gsub()}, +and @code{gensub()} functions, it is very important. +@ifinfo +@xref{String Functions}, +for more information on these functions. +@end ifinfo +Understanding this principle is also important for regexp-based record +and field splitting (@pxref{Records}, +and also @pxref{Field Separators}). + +@node Computed Regexps +@section Using Dynamic Regexps + +@c STARTOFRANGE dregexp +@cindex regular expressions, computed +@c STARTOFRANGE regexpd +@cindex regular expressions, dynamic +@cindex @code{~} (tilde), @code{~} operator +@cindex tilde (@code{~}), @code{~} operator +@cindex @code{!} (exclamation point), @code{!~} operator +@cindex exclamation point (@code{!}), @code{!~} operator +@c @cindex operators, @code{~} +@c @cindex operators, @code{!~} +The righthand side of a @samp{~} or @samp{!~} operator need not be a +regexp constant (i.e., a string of characters between slashes). It may +be any expression. The expression is evaluated and converted to a string +if necessary; the contents of the string are then used as the +regexp. A regexp computed in this way is called a @dfn{dynamic +regexp} or a @dfn{computed regexp}: + +@example +BEGIN @{ digits_regexp = "[[:digit:]]+" @} +$0 ~ digits_regexp @{ print @} +@end example + +@noindent +This sets @code{digits_regexp} to a regexp that describes one or more digits, +and tests whether the input record matches this regexp. + +@quotation NOTE +When using the @samp{~} and @samp{!~} +operators, there is a difference between a regexp constant +enclosed in slashes and a string constant enclosed in double quotes. +If you are going to use a string constant, you have to understand that +the string is, in essence, scanned @emph{twice}: the first time when +@command{awk} reads your program, and the second time when it goes to +match the string on the lefthand side of the operator with the pattern +on the right. This is true of any string-valued expression (such as +@code{digits_regexp}, shown previously), not just string constants. +@end quotation + +@cindex regexp constants, slashes vs.@: quotes +@cindex @code{\} (backslash), in regexp constants +@cindex backslash (@code{\}), in regexp constants +@cindex @code{"} (double quote), in regexp constants +@cindex double quote (@code{"}), in regexp constants +What difference does it make if the string is +scanned twice? The answer has to do with escape sequences, and particularly +with backslashes. To get a backslash into a regular expression inside a +string, you have to type two backslashes. + +For example, @code{/\*/} is a regexp constant for a literal @samp{*}. +Only one backslash is needed. To do the same thing with a string, +you have to type @code{"\\*"}. The first backslash escapes the +second one so that the string actually contains the +two characters @samp{\} and @samp{*}. + +@cindex troubleshooting, regexp constants vs.@: string constants +@cindex regexp constants, vs.@: string constants +@cindex string constants, vs.@: regexp constants +Given that you can use both regexp and string constants to describe +regular expressions, which should you use? The answer is ``regexp +constants,'' for several reasons: + +@itemize @value{BULLET} +@item +String constants are more complicated to write and +more difficult to read. Using regexp constants makes your programs +less error-prone. Not understanding the difference between the two +kinds of constants is a common source of errors. + +@item +It is more efficient to use regexp constants. @command{awk} can note +that you have supplied a regexp and store it internally in a form that +makes pattern matching more efficient. When using a string constant, +@command{awk} must first convert the string into this internal form and +then perform the pattern matching. + +@item +Using regexp constants is better form; it shows clearly that you +intend a regexp match. +@end itemize + +@cindex sidebar, Using @code{\n} in Bracket Expressions of Dynamic Regexps +@ifdocbook +@docbook +<sidebar><title>Using @code{\n} in Bracket Expressions of Dynamic Regexps</title> +@end docbook + +@cindex regular expressions, dynamic, with embedded newlines +@cindex newlines, in dynamic regexps + +Some older versions of @command{awk} do not allow the newline +character to be used inside a bracket expression for a dynamic regexp: + +@example +$ @kbd{awk '$0 ~ "[ \t\n]"'} +@error{} awk: newline in character class [ +@error{} ]... +@error{} source line number 1 +@error{} context is +@error{} $0 ~ "[ >>> \t\n]" <<< +@end example + +@cindex newlines, in regexp constants +But a newline in a regexp constant works with no problem: + +@example +$ @kbd{awk '$0 ~ /[ \t\n]/'} +@kbd{here is a sample line} +@print{} here is a sample line +@kbd{Ctrl-d} +@end example + +@command{gawk} does not have this problem, and it isn't likely to +occur often in practice, but it's worth noting for future reference. + +@docbook +</sidebar> +@end docbook +@end ifdocbook + +@ifnotdocbook +@cartouche +@center @b{Using @code{\n} in Bracket Expressions of Dynamic Regexps} + + +@cindex regular expressions, dynamic, with embedded newlines +@cindex newlines, in dynamic regexps + +Some older versions of @command{awk} do not allow the newline +character to be used inside a bracket expression for a dynamic regexp: + +@example +$ @kbd{awk '$0 ~ "[ \t\n]"'} +@error{} awk: newline in character class [ +@error{} ]... +@error{} source line number 1 +@error{} context is +@error{} $0 ~ "[ >>> \t\n]" <<< +@end example + +@cindex newlines, in regexp constants +But a newline in a regexp constant works with no problem: + +@example +$ @kbd{awk '$0 ~ /[ \t\n]/'} +@kbd{here is a sample line} +@print{} here is a sample line +@kbd{Ctrl-d} +@end example + +@command{gawk} does not have this problem, and it isn't likely to +occur often in practice, but it's worth noting for future reference. +@end cartouche +@end ifnotdocbook +@c ENDOFRANGE dregexp +@c ENDOFRANGE regexpd + @node GNU Regexp Operators @section @command{gawk}-Specific Regexp Operators @@ -5689,7 +5975,7 @@ are allowed. Traditional Unix @command{awk} regexps are matched. 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} does support them. +as BWK @command{awk} supports them. Characters described by octal and hexadecimal escape sequences are treated literally, even if they represent regexp metacharacters. @@ -5801,204 +6087,6 @@ Case is always significant in compatibility mode. @c ENDOFRANGE csregexp @c ENDOFRANGE regexpcs -@node Leftmost Longest -@section How Much Text Matches? - -@cindex regular expressions, leftmost longest match -@c @cindex matching, leftmost longest -Consider the following: - -@example -echo aaaabcd | awk '@{ sub(/a+/, "<A>"); print @}' -@end example - -This example uses the @code{sub()} function (which we haven't discussed yet; -@pxref{String Functions}) -to make a change to the input record. Here, the regexp @code{/a+/} -indicates ``one or more @samp{a} characters,'' and the replacement -text is @samp{<A>}. - -The input contains four @samp{a} characters. -@command{awk} (and POSIX) regular expressions always match -the leftmost, @emph{longest} sequence of input characters that can -match. Thus, all four @samp{a} characters are -replaced with @samp{<A>} in this example: - -@example -$ @kbd{echo aaaabcd | awk '@{ sub(/a+/, "<A>"); print @}'} -@print{} <A>bcd -@end example - -For simple match/no-match tests, this is not so important. But when doing -text matching and substitutions with the @code{match()}, @code{sub()}, @code{gsub()}, -and @code{gensub()} functions, it is very important. -@ifinfo -@xref{String Functions}, -for more information on these functions. -@end ifinfo -Understanding this principle is also important for regexp-based record -and field splitting (@pxref{Records}, -and also @pxref{Field Separators}). - -@node Computed Regexps -@section Using Dynamic Regexps - -@c STARTOFRANGE dregexp -@cindex regular expressions, computed -@c STARTOFRANGE regexpd -@cindex regular expressions, dynamic -@cindex @code{~} (tilde), @code{~} operator -@cindex tilde (@code{~}), @code{~} operator -@cindex @code{!} (exclamation point), @code{!~} operator -@cindex exclamation point (@code{!}), @code{!~} operator -@c @cindex operators, @code{~} -@c @cindex operators, @code{!~} -The righthand side of a @samp{~} or @samp{!~} operator need not be a -regexp constant (i.e., a string of characters between slashes). It may -be any expression. The expression is evaluated and converted to a string -if necessary; the contents of the string are then used as the -regexp. A regexp computed in this way is called a @dfn{dynamic -regexp} or a @dfn{computed regexp}: - -@example -BEGIN @{ digits_regexp = "[[:digit:]]+" @} -$0 ~ digits_regexp @{ print @} -@end example - -@noindent -This sets @code{digits_regexp} to a regexp that describes one or more digits, -and tests whether the input record matches this regexp. - -@quotation NOTE -When using the @samp{~} and @samp{!~} -operators, there is a difference between a regexp constant -enclosed in slashes and a string constant enclosed in double quotes. -If you are going to use a string constant, you have to understand that -the string is, in essence, scanned @emph{twice}: the first time when -@command{awk} reads your program, and the second time when it goes to -match the string on the lefthand side of the operator with the pattern -on the right. This is true of any string-valued expression (such as -@code{digits_regexp}, shown previously), not just string constants. -@end quotation - -@cindex regexp constants, slashes vs.@: quotes -@cindex @code{\} (backslash), in regexp constants -@cindex backslash (@code{\}), in regexp constants -@cindex @code{"} (double quote), in regexp constants -@cindex double quote (@code{"}), in regexp constants -What difference does it make if the string is -scanned twice? The answer has to do with escape sequences, and particularly -with backslashes. To get a backslash into a regular expression inside a -string, you have to type two backslashes. - -For example, @code{/\*/} is a regexp constant for a literal @samp{*}. -Only one backslash is needed. To do the same thing with a string, -you have to type @code{"\\*"}. The first backslash escapes the -second one so that the string actually contains the -two characters @samp{\} and @samp{*}. - -@cindex troubleshooting, regexp constants vs.@: string constants -@cindex regexp constants, vs.@: string constants -@cindex string constants, vs.@: regexp constants -Given that you can use both regexp and string constants to describe -regular expressions, which should you use? The answer is ``regexp -constants,'' for several reasons: - -@itemize @value{BULLET} -@item -String constants are more complicated to write and -more difficult to read. Using regexp constants makes your programs -less error-prone. Not understanding the difference between the two -kinds of constants is a common source of errors. - -@item -It is more efficient to use regexp constants. @command{awk} can note -that you have supplied a regexp and store it internally in a form that -makes pattern matching more efficient. When using a string constant, -@command{awk} must first convert the string into this internal form and -then perform the pattern matching. - -@item -Using regexp constants is better form; it shows clearly that you -intend a regexp match. -@end itemize - -@cindex sidebar, Using @code{\n} in Bracket Expressions of Dynamic Regexps -@ifdocbook -@docbook -<sidebar><title>Using @code{\n} in Bracket Expressions of Dynamic Regexps</title> -@end docbook - -@cindex regular expressions, dynamic, with embedded newlines -@cindex newlines, in dynamic regexps - -Some versions of @command{awk} do not allow the newline -character to be used inside a bracket expression for a dynamic regexp: - -@example -$ @kbd{awk '$0 ~ "[ \t\n]"'} -@error{} awk: newline in character class [ -@error{} ]... -@error{} source line number 1 -@error{} context is -@error{} >>> <<< -@end example - -@cindex newlines, in regexp constants -But a newline in a regexp constant works with no problem: - -@example -$ @kbd{awk '$0 ~ /[ \t\n]/'} -@kbd{here is a sample line} -@print{} here is a sample line -@kbd{Ctrl-d} -@end example - -@command{gawk} does not have this problem, and it isn't likely to -occur often in practice, but it's worth noting for future reference. - -@docbook -</sidebar> -@end docbook -@end ifdocbook - -@ifnotdocbook -@cartouche -@center @b{Using @code{\n} in Bracket Expressions of Dynamic Regexps} - - -@cindex regular expressions, dynamic, with embedded newlines -@cindex newlines, in dynamic regexps - -Some versions of @command{awk} do not allow the newline -character to be used inside a bracket expression for a dynamic regexp: - -@example -$ @kbd{awk '$0 ~ "[ \t\n]"'} -@error{} awk: newline in character class [ -@error{} ]... -@error{} source line number 1 -@error{} context is -@error{} >>> <<< -@end example - -@cindex newlines, in regexp constants -But a newline in a regexp constant works with no problem: - -@example -$ @kbd{awk '$0 ~ /[ \t\n]/'} -@kbd{here is a sample line} -@print{} here is a sample line -@kbd{Ctrl-d} -@end example - -@command{gawk} does not have this problem, and it isn't likely to -occur often in practice, but it's worth noting for future reference. -@end cartouche -@end ifnotdocbook -@c ENDOFRANGE dregexp -@c ENDOFRANGE regexpd - @node Regexp Summary @section Summary @@ -6028,20 +6116,20 @@ Within bracket expressions, POSIX character classes let you specify certain groups of characters in a locale-independent fashion. @item -@command{gawk}'s @code{IGNORECASE} variable lets you control the -case sensitivity of regexp matching. In other @command{awk} -versions, use @code{tolower()} or @code{toupper()}. - -@item Regular expressions match the leftmost longest text in the string being matched. This matters for cases where you need to know the extent of 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 +Matching expressions may use dynamic regexps, that is, string values treated as regular expressions. +@item +@command{gawk}'s @code{IGNORECASE} variable lets you control the +case sensitivity of regexp matching. In other @command{awk} +versions, use @code{tolower()} or @code{toupper()}. + @end itemize @c ENDOFRANGE regexp @@ -6060,7 +6148,7 @@ standard input (by default, this is the keyboard, but often it is a pipe from an command) or from files whose names you specify on the @command{awk} command line. If you specify input files, @command{awk} reads them in order, processing all the data from one before going on to the next. -The name of the current input file can be found in the built-in variable +The name of the current input file can be found in the predefined variable @code{FILENAME} (@pxref{Built-in Variables}). @@ -6106,16 +6194,13 @@ used with it do not have to be named on the @command{awk} command line @cindex records, splitting input into @cindex @code{NR} variable @cindex @code{FNR} variable -The @command{awk} utility divides the input for your @command{awk} -program into records and fields. -@command{awk} keeps track of the number of records that have -been read -so far -from the current input file. This value is stored in a -built-in variable called @code{FNR}. It is reset to zero when a new -file is started. Another built-in 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. +@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. +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. @menu * awk split records:: How standard @command{awk} splits records. @@ -6131,7 +6216,7 @@ Records are separated by a character called the @dfn{record separator}. By default, the record separator is the newline character. This is why records are, by default, single lines. A different character can be used for the record separator by -assigning the character to the built-in variable @code{RS}. +assigning the character to the predefined variable @code{RS}. @cindex newlines, as record separators @cindex @code{RS} variable @@ -6242,7 +6327,8 @@ Using an unusual character such as @samp{/} is more likely to produce correct behavior in the majority of cases, but there are no guarantees. The moral is: Know Your Data. -There is one unusual case, that occurs when @command{gawk} is +When using regular characters as the record separator, +there is one unusual case that occurs when @command{gawk} is being fully POSIX-compliant (@pxref{Options}). Then, the following (extreme) pipeline prints a surprising @samp{1}: @@ -6331,7 +6417,7 @@ $ @kbd{echo record 1 AAAA record 2 BBBB record 3 |} @noindent The square brackets delineate the contents of @code{RT}, letting you -see the leading and trailing whitespace. The final value of @code{RT} +see the leading and trailing whitespace. The final value of @code{RT} is a newline. @xref{Simple Sed}, for a more useful example of @code{RS} as a regexp and @code{RT}. @@ -6350,7 +6436,7 @@ metacharacters match the beginning and end of a @emph{string}, and not 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 in it. +that happens to contain newline characters. It is thus best to avoid anchor characters in the value of @code{RS}. @end quotation @@ -6360,7 +6446,7 @@ variable are @command{gawk} extensions; they are not available in compatibility mode (@pxref{Options}). In compatibility mode, only the first character of the value of -@code{RS} is used to determine the end of the record. +@code{RS} determines the end of the record. @cindex sidebar, @code{RS = "\0"} Is Not Portable @ifdocbook @@ -6375,7 +6461,7 @@ a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary input files. -You might think that for text files, the @sc{nul} character, which +You might think that for text files, the @value{NUL} character, which consists of a character with all bits equal to zero, is a good value to use for @code{RS} in this case: @@ -6384,27 +6470,28 @@ BEGIN @{ RS = "\0" @} # whole file becomes one record? @end example @cindex differences in @command{awk} and @command{gawk}, strings, storing -@command{gawk} in fact accepts this, and uses the @sc{nul} +@command{gawk} in fact accepts this, and uses the @value{NUL} character for the record separator. This works for certain special files, such as @file{/proc/environ} on -GNU/Linux systems, where the @sc{nul} character is in fact the record separator. +GNU/Linux systems, where the @value{NUL} character is in fact the record separator. However, this usage is @emph{not} portable to most other @command{awk} implementations. @cindex dark corner, strings, storing Almost all other @command{awk} implementations@footnote{At least that we know about.} store strings internally as C-style strings. C strings use the -@sc{nul} character as the string terminator. In effect, this means that +@value{NUL} character as the string terminator. In effect, this means that @samp{RS = "\0"} is the same as @samp{RS = ""}. @value{DARKCORNER} -It happens that recent versions of @command{mawk} can use the @sc{nul} +It happens that recent versions of @command{mawk} can use the @value{NUL} character as a record separator. However, this is a special case: -@command{mawk} does not allow embedded @sc{nul} characters in strings. +@command{mawk} does not allow embedded @value{NUL} characters in strings. +(This may change in a future version of @command{mawk}.) @cindex records, treating files as @cindex treating files, as single records -@xref{Readfile Function}, for an interesting, portable way to read +@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. @@ -6425,7 +6512,7 @@ a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary input files. -You might think that for text files, the @sc{nul} character, which +You might think that for text files, the @value{NUL} character, which consists of a character with all bits equal to zero, is a good value to use for @code{RS} in this case: @@ -6434,27 +6521,28 @@ BEGIN @{ RS = "\0" @} # whole file becomes one record? @end example @cindex differences in @command{awk} and @command{gawk}, strings, storing -@command{gawk} in fact accepts this, and uses the @sc{nul} +@command{gawk} in fact accepts this, and uses the @value{NUL} character for the record separator. This works for certain special files, such as @file{/proc/environ} on -GNU/Linux systems, where the @sc{nul} character is in fact the record separator. +GNU/Linux systems, where the @value{NUL} character is in fact the record separator. However, this usage is @emph{not} portable to most other @command{awk} implementations. @cindex dark corner, strings, storing Almost all other @command{awk} implementations@footnote{At least that we know about.} store strings internally as C-style strings. C strings use the -@sc{nul} character as the string terminator. In effect, this means that +@value{NUL} character as the string terminator. In effect, this means that @samp{RS = "\0"} is the same as @samp{RS = ""}. @value{DARKCORNER} -It happens that recent versions of @command{mawk} can use the @sc{nul} +It happens that recent versions of @command{mawk} can use the @value{NUL} character as a record separator. However, this is a special case: -@command{mawk} does not allow embedded @sc{nul} characters in strings. +@command{mawk} does not allow embedded @value{NUL} characters in strings. +(This may change in a future version of @command{mawk}.) @cindex records, treating files as @cindex treating files, as single records -@xref{Readfile Function}, for an interesting, portable way to read +@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. @end cartouche @@ -6514,7 +6602,7 @@ field. @cindex @code{NF} variable @cindex fields, number of -@code{NF} is a built-in variable whose value is the number of fields +@code{NF} is a predefined variable whose value is the number of fields in the current record. @command{awk} automatically updates the value of @code{NF} each time it reads a record. No matter how many fields there are, the last field in a record can be represented by @code{$NF}. @@ -6536,15 +6624,11 @@ $ @kbd{awk '$1 ~ /li/ @{ print $0 @}' mail-list} @noindent This example prints each record in the file @file{mail-list} whose first -field contains the string @samp{li}. The operator @samp{~} is called a -@dfn{matching operator} -(@pxref{Regexp Usage}); -it tests whether a string (here, the field @code{$1}) matches a given regular -expression. +field contains the string @samp{li}. -By contrast, the following example -looks for @samp{li} in @emph{the entire record} and prints the first -field and the last field for each matching input record: +By contrast, the following example looks for @samp{li} in @emph{the +entire record} and prints the first and last fields for each matching +input record: @example $ @kbd{awk '/li/ @{ print $1, $NF @}' mail-list} @@ -6607,7 +6691,7 @@ implementations may behave differently.) As mentioned in @ref{Fields}, @command{awk} stores the current record's number of fields in the built-in -variable @code{NF} (also @pxref{Built-in Variables}). The expression +variable @code{NF} (also @pxref{Built-in Variables}). Thus, the expression @code{$NF} is not a special feature---it is the direct consequence of evaluating @code{NF} and using its value as a field number. @@ -6667,8 +6751,8 @@ It is also possible to also assign contents to fields that are out of range. For example: @example -$ awk '@{ $6 = ($5 + $4 + $3 + $2) -> print $6 @}' inventory-shipped +$ @kbd{awk '@{ $6 = ($5 + $4 + $3 + $2)} +> @kbd{ print $6 @}' inventory-shipped} @print{} 168 @print{} 297 @print{} 301 @@ -6757,7 +6841,7 @@ Here is an example: @example $ echo a b c d e f | awk '@{ print "NF =", NF; -> NF = 3; print $0 @}' +> NF = 3; print $0 @}' @print{} NF = 6 @print{} a b c @end example @@ -6765,7 +6849,7 @@ $ echo a b c d e f | awk '@{ print "NF =", NF; @cindex portability, @code{NF} variable@comma{} decrementing @quotation CAUTION Some versions of @command{awk} don't -rebuild @code{$0} when @code{NF} is decremented. Caveat emptor. +rebuild @code{$0} when @code{NF} is decremented. @end quotation Finally, there are times when it is convenient to force @@ -6801,7 +6885,7 @@ record, exactly as it was read from the input. This includes any leading or trailing whitespace, and the exact whitespace (or other characters) that separate the fields. -It is a not-uncommon error to try to change the field separators +It is a common error to try to change the field separators 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. @@ -6826,7 +6910,7 @@ record, exactly as it was read from the input. This includes any leading or trailing whitespace, and the exact whitespace (or other characters) that separate the fields. -It is a not-uncommon error to try to change the field separators +It is a common error to try to change the field separators 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. @@ -6876,7 +6960,7 @@ is split into three fields: @samp{m}, @samp{@bullet{}g}, and Note the leading spaces in the values of the second and third fields. @cindex troubleshooting, @command{awk} uses @code{FS} not @code{IFS} -The field separator is represented by the built-in variable @code{FS}. +The field separator is represented by the predefined variable @code{FS}. Shell programmers take note: @command{awk} does @emph{not} use the name @code{IFS} that is used by the POSIX-compliant shells (such as the Unix Bourne shell, @command{sh}, or Bash). @@ -7030,9 +7114,10 @@ $ @kbd{echo ' a b c d' | awk '@{ print; $2 = $2; print @}'} The first @code{print} statement prints the record as it was read, with leading whitespace intact. The assignment to @code{$2} rebuilds @code{$0} by concatenating @code{$1} through @code{$NF} together, -separated by the value of @code{OFS}. Because the leading whitespace -was ignored when finding @code{$1}, it is not part of the new @code{$0}. -Finally, the last @code{print} statement prints the new @code{$0}. +separated by the value of @code{OFS} (which is a space by default). +Because the leading whitespace was ignored when finding @code{$1}, +it is not part of the new @code{$0}. Finally, the last @code{print} +statement prints the new @code{$0}. @cindex @code{FS}, containing @code{^} @cindex @code{^} (caret), in @code{FS} @@ -7054,7 +7139,7 @@ also works this way. For example: @example $ @kbd{echo 'xxAA xxBxx C' |} > @kbd{gawk -F '(^x+)|( +)' '@{ for (i = 1; i <= NF; i++)} -> @kbd{printf "-->%s<--\n", $i @}'} +> @kbd{ printf "-->%s<--\n", $i @}'} @print{} --><-- @print{} -->AA<-- @print{} -->xxBxx<-- @@ -7117,15 +7202,10 @@ awk -F, '@var{program}' @var{input-files} @noindent sets @code{FS} to the @samp{,} character. Notice that the option uses an uppercase @samp{F} instead of a lowercase @samp{f}. The latter -option (@option{-f}) specifies a file -containing an @command{awk} program. Case is significant in command-line -options: -the @option{-F} and @option{-f} options have nothing to do with each other. -You can use both options at the same time to set the @code{FS} variable -@emph{and} get an @command{awk} program from a file. +option (@option{-f}) specifies a file containing an @command{awk} program. The value used for the argument to @option{-F} is processed in exactly the -same way as assignments to the built-in variable @code{FS}. +same way as assignments to the predefined variable @code{FS}. Any special characters in the field separator must be escaped appropriately. For example, to use a @samp{\} as the field separator on the command line, you would have to type: @@ -7236,7 +7316,7 @@ to @code{FS} (the backslash is stripped). This creates a regexp meaning If instead you want fields to be separated by a literal period followed by any single character, use @samp{FS = "\\.."}. -The following table summarizes how fields are split, based on the value +The following list summarizes how fields are split, based on the value of @code{FS} (@samp{==} means ``is equal to''): @table @code @@ -7257,8 +7337,7 @@ 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 @command{gawk} extension; it is not specified by the -POSIX standard.) +(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 @@ -7805,7 +7884,7 @@ BEGIN @{ RS = "" ; FS = "\n" @} Running the program produces the following output: @example -$ awk -f addrs.awk addresses +$ @kbd{awk -f addrs.awk addresses} @print{} Name is: Jane Doe @print{} Address is: 123 Main Street @print{} City and State are: Anywhere, SE 12345-6789 @@ -7817,12 +7896,9 @@ $ awk -f addrs.awk addresses @dots{} @end example -@xref{Labels Program}, for a more realistic -program that deals with address lists. -The following -table -summarizes how records are split, based on the -value of +@xref{Labels Program}, for a more realistic program that deals with +address lists. The following list summarizes how records are split, +based on the value of @ifinfo @code{RS}. (@samp{==} means ``is equal to.'') @@ -7857,8 +7933,8 @@ POSIX standard.) @cindex @command{gawk}, @code{RT} variable in @cindex @code{RT} variable -In all cases, @command{gawk} sets @code{RT} to the input text that matched the -value specified by @code{RS}. +If not in compatibility mode (@pxref{Options}), @command{gawk} sets +@code{RT} to the input text that matched the value specified by @code{RS}. But if the input file ended without any text that matches @code{RS}, then @command{gawk} sets @code{RT} to the null string. @c ENDOFRANGE recm @@ -7904,7 +7980,7 @@ and have a good knowledge of how @command{awk} works. @cindex @code{getline} command, return values @cindex @option{--sandbox} option, input redirection with @code{getline} -The @code{getline} command returns one if it finds a record and zero if +The @code{getline} command returns 1 if it finds a record and 0 if it encounters the end of the file. If there is some error in getting a record, such as a file that cannot be opened, then @code{getline} returns @minus{}1. In this case, @command{gawk} sets the variable @@ -7944,32 +8020,56 @@ finished processing the current record, but want to do some special processing on the next record @emph{right now}. For example: @example +# Remove text between /* and */, inclusive @{ - if ((t = index($0, "/*")) != 0) @{ - # value of `tmp' will be "" if t is 1 - tmp = substr($0, 1, t - 1) - u = index(substr($0, t + 2), "*/") - offset = t + 2 - while (u == 0) @{ - if (getline <= 0) @{ - m = "unexpected EOF or error" - m = (m ": " ERRNO) - print m > "/dev/stderr" + if ((i = index($0, "/*")) != 0) @{ + out = substr($0, 1, i - 1) # leading part of the string + rest = substr($0, i + 2) # ... */ ... + j = index(rest, "*/") # is */ in trailing part? + if (j > 0) @{ + rest = substr(rest, j + 2) # remove comment + @} else @{ + while (j == 0) @{ + # get more text + if (getline <= 0) @{ + print("unexpected EOF or error:", ERRNO) > "/dev/stderr" exit - @} - u = index($0, "*/") - offset = 0 - @} - # substr() expression will be "" if */ - # occurred at end of line - $0 = tmp substr($0, offset + u + 2) - @} - print $0 + @} + # build up the line using string concatenation + rest = rest $0 + j = index(rest, "*/") # is */ in trailing part? + if (j != 0) @{ + rest = substr(rest, j + 2) + break + @} + @} + @} + # build up the output line using string concatenation + $0 = out rest + @} + print $0 @} @end example +@c 8/2014: Here is some sample input: +@ignore +mon/*comment*/key +rab/*commen +t*/bit +horse /*comment*/more text +part 1 /*comment*/part 2 /*comment*/part 3 +no comment +@end ignore + This @command{awk} program deletes C-style comments (@samp{/* @dots{} -*/}) from the input. By replacing the @samp{print $0} with other +*/}) from the input. +It uses a number of features we haven't covered yet, including +string concatenation +(@pxref{Concatenation}) +and the @code{index()} and @code{substr()} built-in +functions +(@pxref{String Functions}). +By replacing the @samp{print $0} with other statements, you could perform more complicated processing on the decommented input, such as searching for matches of a regular expression. (This program has a subtle problem---it does not work if one @@ -8091,7 +8191,7 @@ from the file @var{file}, and put it in the variable @var{var}. As above, @var{file} is a string-valued expression that specifies the file from which to read. -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. The only variable changed is @var{var}.@footnote{This is not quite true. @code{RT} could be changed if @code{RS} is a regular expression.} @@ -8201,7 +8301,7 @@ bletch @end example @noindent -Notice that this program ran the command @command{who} and printed the previous result. +Notice that this program ran the command @command{who} and printed the result. (If you try this program yourself, you will of course get different results, depending upon who is logged in on your system.) @@ -8226,7 +8326,7 @@ Unfortunately, @command{gawk} has not been consistent in its treatment of a construct like @samp{@w{"echo "} "date" | getline}. Most versions, including the current version, treat it at as @samp{@w{("echo "} "date") | getline}. -(This how BWK @command{awk} behaves.) +(This is also how BWK @command{awk} behaves.) Some versions changed and treated it as @samp{@w{"echo "} ("date" | getline)}. (This is how @command{mawk} behaves.) @@ -8253,8 +8353,8 @@ BEGIN @{ @} @end example -In this version of @code{getline}, none of the built-in variables are -changed and the record is not split into fields. +In this version of @code{getline}, none of the predefined variables are +changed and the record is not split into fields. However, @code{RT} is set. @ifinfo @c Thanks to Paul Eggert for initial wording here @@ -8315,7 +8415,7 @@ When you use @samp{@var{command} |& getline @var{var}}, the output from the coprocess @var{command} is sent through a two-way pipe to @code{getline} and into the variable @var{var}. -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. The only variable changed is @var{var}. However, @code{RT} is set. @@ -8362,7 +8462,7 @@ causes @command{awk} to set the value of @code{FILENAME}. Normally, @code{FILENAME} does not have a value inside @code{BEGIN} rules, because you have not yet started to process the command-line @value{DF}s. @value{DARKCORNER} -(@xref{BEGIN/END}, +(See @ref{BEGIN/END}; also @pxref{Auto-set}.) @item @@ -8376,7 +8476,7 @@ probably by accident, and you should reconsider what it is you're trying to accomplish. @item -@ref{Getline Summary}, presents a table summarizing the +@DBREF{Getline Summary} presents a table summarizing the @code{getline} variants and which variables they can affect. It is worth noting that those variants which do not use redirection can cause @code{FILENAME} to be updated if they cause @@ -8409,7 +8509,7 @@ end of file is encountered, before the element in @code{a} is assigned? @command{gawk} treats @code{getline} like a function call, and evaluates the expression @samp{a[++c]} before attempting to read from @file{f}. However, some versions of @command{awk} only evaluate the expression once they -know that there is a string value to be assigned. Caveat Emptor. +know that there is a string value to be assigned. @end itemize @node Getline Summary @@ -8418,22 +8518,22 @@ know that there is a string value to be assigned. Caveat Emptor. @ref{table-getline-variants} summarizes the eight variants of @code{getline}, -listing which built-in variables are set by each one, +listing which predefined variables are set by each one, and whether the variant is standard or a @command{gawk} extension. -Note: for each variant, @command{gawk} sets the @code{RT} built-in variable. +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} @multitable @columnfractions .33 .38 .27 -@headitem Variant @tab Effect @tab Standard / Extension -@item @code{getline} @tab Sets @code{$0}, @code{NF}, @code{FNR}, @code{NR}, and @code{RT} @tab Standard -@item @code{getline} @var{var} @tab Sets @var{var}, @code{FNR}, @code{NR}, and @code{RT} @tab Standard -@item @code{getline <} @var{file} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab Standard -@item @code{getline @var{var} < @var{file}} @tab Sets @var{var} and @code{RT} @tab Standard -@item @var{command} @code{| getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab Standard -@item @var{command} @code{| getline} @var{var} @tab Sets @var{var} and @code{RT} @tab Standard -@item @var{command} @code{|& getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab Extension -@item @var{command} @code{|& getline} @var{var} @tab Sets @var{var} and @code{RT} @tab Extension +@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} +@item @code{getline} @var{var} @tab Sets @var{var}, @code{FNR}, @code{NR}, and @code{RT} @tab @command{awk} +@item @code{getline <} @var{file} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab @command{awk} +@item @code{getline @var{var} < @var{file}} @tab Sets @var{var} and @code{RT} @tab @command{awk} +@item @var{command} @code{| getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab @command{awk} +@item @var{command} @code{| getline} @var{var} @tab Sets @var{var} and @code{RT} @tab @command{awk} +@item @var{command} @code{|& getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab @command{gawk} +@item @var{command} @code{|& getline} @var{var} @tab Sets @var{var} and @code{RT} @tab @command{gawk} @end multitable @end float @c ENDOFRANGE getl @@ -8450,7 +8550,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 -in the @code{PROCINFO} (@pxref{Auto-set}) array: +in the @code{PROCINFO} array (@pxref{Auto-set}): @example PROCINFO["input_name", "READ_TIMEOUT"] = @var{timeout in milliseconds} @@ -8482,7 +8582,7 @@ while ((getline < "/dev/stdin") > 0) @command{gawk} terminates the read operation if input does not arrive after waiting for the timeout period, returns failure -and sets the @code{ERRNO} variable to an appropriate string value. +and sets @code{ERRNO} to an appropriate string value. A negative or zero value for the timeout is the same as specifying no timeout at all. @@ -8589,6 +8689,10 @@ The possibilities are as follows: @end multitable @item +@code{FNR} indicates how many records have been read from the current input file; +@code{NR} indicates how many records have been read in total. + +@item @command{gawk} sets @code{RT} to the text matched by @code{RS}. @item @@ -8599,7 +8703,7 @@ fields there are. The default way to split fields is between whitespace characters. @item -Fields may be referenced using a variable, as in @samp{$NF}. Fields +Fields may be referenced using a variable, as in @code{$NF}. Fields may also be assigned values, which causes the value of @code{$0} to be recomputed when it is later referenced. Assigning to a field with a number greater than @code{NF} creates the field and rebuilds the record, using @@ -8609,16 +8713,17 @@ thing. Decrementing @code{NF} throws away fields and rebuilds the record. @item Field splitting is more complicated than record splitting. -@multitable @columnfractions .40 .40 .20 +@multitable @columnfractions .40 .45 .15 @headitem Field separator value @tab Fields are split @dots{} @tab @command{awk} / @command{gawk} @item @code{FS == " "} @tab On runs of whitespace @tab @command{awk} @item @code{FS == @var{any single character}} @tab On that character @tab @command{awk} @item @code{FS == @var{regexp}} @tab On text matching the regexp @tab @command{awk} @item @code{FS == ""} @tab Each individual character is a separate field @tab @command{gawk} @item @code{FIELDWIDTHS == @var{list of columns}} @tab Based on character position @tab @command{gawk} -@item @code{FPAT == @var{regexp}} @tab On text around text matching the regexp @tab @command{gawk} +@item @code{FPAT == @var{regexp}} @tab On the text surrounding text matching the regexp @tab @command{gawk} @end multitable +@item Using @samp{FS = "\n"} causes the entire record to be a single field (assuming that newlines separate records). @@ -8627,11 +8732,11 @@ Using @samp{FS = "\n"} causes the entire record to be a single field This can also be done using command-line variable assignment. @item -@code{PROCINFO["FS"]} can be used to see how fields are being split. +Use @code{PROCINFO["FS"]} to see how fields are being split. @item Use @code{getline} in its various forms to read additional records, -from the default input stream, from a file, or from a pipe or co-process. +from the default input stream, from a file, or from a pipe or coprocess. @item Use @code{PROCINFO[@var{file}, "READ_TIMEOUT"]} to cause reads to timeout @@ -8643,6 +8748,7 @@ Directories on the command line are fatal for standard @command{awk}; @end itemize +@c EXCLUDE START @node Input Exercises @section Exercises @@ -8659,9 +8765,10 @@ including abstentions, for each item. comments (@samp{/* @dots{} */}) from the input. That program does not work if one comment ends on one line and another one starts later on the same line. -Write a program that does handle multiple comments on the line. +That can be fixed by making one simple change. What is it? @end enumerate +@c EXCLUDE END @node Printing @chapter Printing Output @@ -8698,18 +8805,19 @@ and discusses the @code{close()} built-in function. * Printf:: The @code{printf} statement. * Redirection:: How to redirect output to multiple files and pipes. +* Special FD:: Special files for I/O. * Special Files:: File name interpretation in @command{gawk}. @command{gawk} allows access to inherited file descriptors. * Close Files And Pipes:: Closing Input and Output Files and Pipes. * Output Summary:: Output summary. -* Output exercises:: Exercises. +* Output Exercises:: Exercises. @end menu @node Print @section The @code{print} Statement -The @code{print} statement is used for producing output with simple, standardized +Use the @code{print} statement to produce output with simple, standardized formatting. You specify only the strings or numbers to print, in a list separated by commas. They are output, separated by single spaces, followed by a newline. The statement looks like this: @@ -8733,7 +8841,7 @@ expression. Numeric values are converted to strings and then printed. @cindex text, printing The simple statement @samp{print} with no items is equivalent to @samp{print $0}: it prints the entire current record. To print a blank -line, use @samp{print ""}, where @code{""} is the empty string. +line, use @samp{print ""}. To print a fixed piece of text, use a string constant, such as @w{@code{"Don't Panic"}}, as one item. If you forget to use the double-quote characters, your text is taken as an @command{awk} @@ -8741,8 +8849,8 @@ expression, and you will probably get an error. Keep in mind that a space is printed between any two items. Note that the @code{print} statement is a statement and not an -expression---you can't use it the pattern part of a pattern-action -statement, for example. +expression---you can't use it in the pattern part of a +@var{pattern}-@var{action} statement, for example. @node Print Examples @section @code{print} Statement Examples @@ -8753,9 +8861,22 @@ newline, the newline is output along with the rest of the string. A single @code{print} statement can make any number of lines this way. @cindex newlines, printing -The following is an example of printing a string that contains embedded newlines +The following is an example of printing a string that contains embedded +@ifinfo +newlines +(the @samp{\n} is an escape sequence, used to represent the newline +character; @pxref{Escape Sequences}): +@end ifinfo +@ifhtml +newlines (the @samp{\n} is an escape sequence, used to represent the newline character; @pxref{Escape Sequences}): +@end ifhtml +@ifnotinfo +@ifnothtml +newlines: +@end ifnothtml +@end ifnotinfo @example $ @kbd{awk 'BEGIN @{ print "line one\nline two\nline three" @}'} @@ -8859,7 +8980,7 @@ of items 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 @dfn{output field separator} by setting the -built-in variable @code{OFS}. The initial value of this variable +predefined variable @code{OFS}. The initial value of this variable is the string @w{@code{" "}}---that is, a single space. The output from an entire @code{print} statement is called an @@ -8935,13 +9056,13 @@ more fully in @cindexawkfunc{sprintf} @cindex @code{OFMT} variable @cindex output, format specifier@comma{} @code{OFMT} -The built-in variable @code{OFMT} contains the default format specification +The predefined variable @code{OFMT} contains the format specification that @code{print} uses with @code{sprintf()} when it wants to convert a number to a string for printing. The default value of @code{OFMT} is @code{"%.6g"}. The way @code{print} prints numbers can be changed -by supplying different format specifications -as the value of @code{OFMT}, as shown in the following example: +by supplying a different format specification +for the value of @code{OFMT}, as shown in the following example: @example $ @kbd{awk 'BEGIN @{} @@ -8971,9 +9092,7 @@ With @code{printf} you can specify the width to use for each item, as well as various formatting choices for numbers (such as what output base to use, whether to print an exponent, whether to print a sign, and how many digits to print -after the decimal point). You do this by supplying a string, called -the @dfn{format string}, that controls how and where to print the other -arguments. +after the decimal point). @menu * Basic Printf:: Syntax of the @code{printf} statement. @@ -8993,10 +9112,10 @@ printf @var{format}, @var{item1}, @var{item2}, @dots{} @end example @noindent -The entire list of arguments may optionally be enclosed in parentheses. 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}). +As print @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}). @cindex format specifiers The difference between @code{printf} and @code{print} is the @var{format} @@ -9019,10 +9138,10 @@ on @code{printf} statements. For example: @example $ @kbd{awk 'BEGIN @{} > @kbd{ORS = "\nOUCH!\n"; OFS = "+"} -> @kbd{msg = "Dont Panic!"} +> @kbd{msg = "Don\47t Panic!"} > @kbd{printf "%s\n", msg} > @kbd{@}'} -@print{} Dont Panic! +@print{} Don't Panic! @end example @noindent @@ -9044,7 +9163,7 @@ the field width. Here is a list of the format-control letters: @c @asis for docbook to come out right @table @asis @item @code{%c} -Print a number as an ASCII character; thus, @samp{printf "%c", +Print a number as a character; thus, @samp{printf "%c", 65} outputs the letter @samp{A}. The output for a string value is the first character of the string. @@ -9070,7 +9189,7 @@ a single byte (0--255). @item @code{%d}, @code{%i} Print a decimal integer. The two control letters are equivalent. -(The @samp{%i} specification is for compatibility with ISO C.) +(The @code{%i} specification is for compatibility with ISO C.) @item @code{%e}, @code{%E} Print a number in scientific (exponential) notation; @@ -9085,7 +9204,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}.) -@samp{%E} uses @samp{E} instead of @samp{e} in the output. +@code{%E} uses @samp{E} instead of @samp{e} in the output. @item @code{%f} Print a number in floating-point notation. @@ -9111,16 +9230,16 @@ The special ``not a number'' value formats as @samp{-nan} or @samp{nan} (@pxref{Math Definitions}). @item @code{%F} -Like @samp{%f} but the infinity and ``not a number'' values are spelled +Like @code{%f} but the infinity and ``not a number'' values are spelled using uppercase letters. -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. +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. @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, @samp{%G} uses @samp{E} instead of @samp{e}. +scientific notation, @code{%G} uses @samp{E} instead of @samp{e}. @item @code{%o} Print an unsigned octal integer @@ -9136,7 +9255,7 @@ are floating-point; it is provided primarily for compatibility with C.) @item @code{%x}, @code{%X} Print an unsigned hexadecimal integer; -@samp{%X} uses the letters @samp{A} through @samp{F} +@code{%X} uses the letters @samp{A} through @samp{F} instead of @samp{a} through @samp{f} (@pxref{Nondecimal-numbers}). @@ -9151,7 +9270,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 @samp{%g} format specifier. If @option{--lint} is provided on the +the @code{%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. @@ -9167,7 +9286,7 @@ values or do something else entirely. A format specification can also include @dfn{modifiers} that can control how much of the item's value is printed, as well as how much space it gets. The modifiers come between the @samp{%} and the format-control letter. -We will use the bullet symbol ``@bullet{}'' in the following examples to +We use the bullet symbol ``@bullet{}'' in the following examples to represent spaces in the output. Here are the possible modifiers, in the order in which they may appear: @@ -9198,7 +9317,7 @@ It is in fact a @command{gawk} extension, intended for use in translating messages at runtime. @xref{Printf Ordering}, which describes how and why to use positional specifiers. -For now, we will not use them. +For now, we ignore them. @item - The minus sign, used before the width modifier (see later on in @@ -9226,15 +9345,15 @@ to format is positive. The @samp{+} overrides the space modifier. @item # Use an ``alternate 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 +For @code{%o}, supply a leading zero. +For @code{%x} and @code{%X}, supply a leading @code{0x} or @samp{0X} for a nonzero result. -For @samp{%e}, @samp{%E}, @samp{%f}, and @samp{%F}, the result always +For @code{%e}, @code{%E}, @code{%f}, and @code{%F}, the result always contains a decimal point. -For @samp{%g} and @samp{%G}, trailing zeros are not removed from the result. +For @code{%g} and @code{%G}, trailing zeros are not removed from the result. @item 0 -A leading @samp{0} (zero) acts as a flag that indicates that output should be +A leading @samp{0} (zero) acts as a flag indicating that output should be padded with zeros instead of spaces. This applies only to the numeric output formats. This flag only has an effect when the field width is wider than the @@ -9420,7 +9539,7 @@ the @command{awk} program: @example awk 'BEGIN @{ print "Name Number" print "---- ------" @} - @{ printf "%-10s %s\n", $1, $2 @}' mail-list + @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example The above example mixes @code{print} and @code{printf} statements in @@ -9430,7 +9549,7 @@ same results: @example awk 'BEGIN @{ printf "%-10s %s\n", "Name", "Number" printf "%-10s %s\n", "----", "------" @} - @{ printf "%-10s %s\n", $1, $2 @}' mail-list + @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example @noindent @@ -9445,7 +9564,7 @@ emphasized by storing it in a variable, like this: awk 'BEGIN @{ format = "%-10s %s\n" printf format, "Name", "Number" printf format, "----", "------" @} - @{ printf format, $1, $2 @}' mail-list + @{ printf format, $1, $2 @}' mail-list @end example @c ENDOFRANGE printfs @@ -9466,7 +9585,7 @@ This is called @dfn{redirection}. @quotation NOTE When @option{--sandbox} is specified (@pxref{Options}), -redirecting output to files and pipes is disabled. +redirecting output to files, pipes and coprocesses is disabled. @end quotation A redirection appears after the @code{print} or @code{printf} statement. @@ -9563,17 +9682,11 @@ in an @command{awk} script run periodically for system maintenance: @example report = "mail bug-system" -print "Awk script failed:", $0 | report -m = ("at record number " FNR " of " FILENAME) -print m | report +print("Awk script failed:", $0) | report +print("at record number", FNR, "of", FILENAME) | report close(report) @end example -The message is built using string concatenation and saved in the variable -@code{m}. It's then sent down the pipeline to the @command{mail} program. -(The parentheses group the items to concatenate---see -@ref{Concatenation}.) - 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}, @@ -9680,6 +9793,9 @@ 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 +command lines to be fed to the shell. + @docbook </sidebar> @end docbook @@ -9711,28 +9827,16 @@ uppercase characters converted to lowercase 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 +command lines to be fed to the shell. @end cartouche @end ifnotdocbook @c ENDOFRANGE outre @c ENDOFRANGE reout -@node Special Files -@section Special @value{FFN}s in @command{gawk} -@c STARTOFRANGE gfn -@cindex @command{gawk}, file names in - -@command{gawk} provides a number of special @value{FN}s that it interprets -internally. These @value{FN}s provide access to standard file descriptors -and TCP/IP networking. - -@menu -* Special FD:: Special files for I/O. -* Special Network:: Special files for network communications. -* Special Caveats:: Things to watch out for. -@end menu - @node Special FD -@subsection Special Files for Standard Descriptors +@section Special Files for Standard Pre-Opened Data Streams @cindex standard input @cindex input, standard @cindex standard output @@ -9743,9 +9847,12 @@ and TCP/IP networking. @cindex files, descriptors, See file descriptors Running programs conventionally have three input and output streams -already available to them for reading and writing. These are known as -the @dfn{standard input}, @dfn{standard output}, and @dfn{standard error -output}. These streams are, by default, connected to your keyboard and screen, but +already available to them for reading and writing. These are known +as the @dfn{standard input}, @dfn{standard output}, and @dfn{standard +error output}. These open streams (and any other open file or pipe) +are often referred to by the technical term @dfn{file descriptors}. + +These streams are, by default, connected to your keyboard and screen, but they are often redirected with the shell, via the @samp{<}, @samp{<<}, @samp{>}, @samp{>>}, @samp{>&}, and @samp{|} operators. Standard error is typically used for writing error messages; the reason there are two separate @@ -9754,7 +9861,7 @@ redirected separately. @cindex differences in @command{awk} and @command{gawk}, error messages @cindex error handling -In other implementations of @command{awk}, the only way to write an error +In traditional implementations of @command{awk}, the only way to write an error message to standard error in an @command{awk} program is as follows: @example @@ -9780,19 +9887,19 @@ that is connected to your keyboard and screen. It represents the ``terminal,''@footnote{The ``tty'' in @file{/dev/tty} stands for ``Teletype,'' a serial terminal.} which on modern systems is a keyboard and screen, not a serial console.) -This usually has the same effect but not always: although the +This generally has the same effect but not always: although the standard error stream is usually the screen, it can be redirected; when that happens, writing to the screen is not correct. In fact, if @command{awk} is run from a background job, it may not have a terminal at all. Then opening @file{/dev/tty} fails. -@command{gawk} provides special @value{FN}s for accessing the three standard -streams. @value{COMMONEXT} It also provides syntax for accessing -any other inherited open files. If the @value{FN} matches -one of these special names when @command{gawk} redirects input or output, -then it directly uses the stream that the @value{FN} stands for. -These special @value{FN}s work for all operating systems that @command{gawk} +@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 +the descriptor that the @value{FN} stands for. These special +@value{FN}s work for all operating systems that @command{gawk} has been ported to, not just those that are POSIX-compliant: @cindex common extensions, @code{/dev/stdin} special file @@ -9814,19 +9921,10 @@ The standard output (file descriptor 1). @item /dev/stderr The standard error output (file descriptor 2). - -@item /dev/fd/@var{N} -The file associated with file descriptor @var{N}. Such a file must -be opened by the program initiating the @command{awk} execution (typically -the shell). Unless special pains are taken in the shell from which -@command{gawk} is invoked, only descriptors 0, 1, and 2 are available. @end table -The @value{FN}s @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} -are aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and @file{/dev/fd/2}, -respectively. However, they are more self-explanatory. -The proper way to write an error message in a @command{gawk} program -is to use @file{/dev/stderr}, like this: +With these facilities, +the proper way to write an error message then becomes: @example print "Serious error detected!" > "/dev/stderr" @@ -9838,14 +9936,51 @@ Like any other redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results. -Finally, using the @code{close()} function on a @value{FN} of the +@command{gawk} does not treat these @value{FN}s as special when +in POSIX compatibility mode. However, since BWK @command{awk} +supports them, @command{gawk} does support them even when +invoked with the @option{--traditional} option (@pxref{Options}). + +@node Special Files +@section Special @value{FFN}s in @command{gawk} +@c STARTOFRANGE gfn +@cindex @command{gawk}, file names in + +Besides access to standard input, stanard 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. + +@menu +* Other Inherited Files:: Accessing other open files with + @command{gawk}. +* Special Network:: Special files for network communications. +* Special Caveats:: Things to watch out for. +@end menu + +@node Other Inherited Files +@subsection Accessing Other Open Files With @command{gawk} + +Besides the @code{/dev/stdin}, @code{/dev/stdout}, and @code{/dev/stderr} +special @value{FN}s mentioned earlier, @command{gawk} provides syntax +for accessing any other inherited open file: + +@table @file +@item /dev/fd/@var{N} +The file associated with file descriptor @var{N}. Such a file must +be opened by the program initiating the @command{awk} execution (typically +the shell). Unless special pains are taken in the shell from which +@command{gawk} is invoked, only descriptors 0, 1, and 2 are available. +@end table + +The @value{FN}s @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} +are essentially aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and +@file{/dev/fd/2}, respectively. However, those names are more self-explanatory. + +Note that using @code{close()} on a @value{FN} of the form @code{"/dev/fd/@var{N}"}, for file descriptor numbers above two, does actually close the given file descriptor. -The @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} -special files are also recognized internally by several other -versions of @command{awk}. - @node Special Network @subsection Special Files for Network Communications @cindex networks, support for @@ -9874,15 +10009,20 @@ Full discussion is delayed until @node Special Caveats @subsection Special @value{FFN} Caveats -Here is a list of things to bear in mind when using the +Here are some things to bear in mind when using the special @value{FN}s that @command{gawk} provides: @itemize @value{BULLET} @cindex compatibility mode (@command{gawk}), file names @cindex file names, in compatibility mode @item -Recognition of these special @value{FN}s is disabled if @command{gawk} is in -compatibility mode (@pxref{Options}). +Recognition of the @value{FN}s for the three standard pre-opened +files is disabled only in POSIX mode. + +@item +Recognition of the other special @value{FN}s is disabled if @command{gawk} is in +compatibility mode (either @option{--traditional} or @option{--posix}; +@pxref{Options}). @item @command{gawk} @emph{always} @@ -10052,7 +10192,8 @@ to a string indicating the error. Note also that @samp{close(FILENAME)} has no ``magic'' effects on the implicit loop that reads through the files named on the command line. It is, more likely, a close of a file that was never opened with a -redirection, so @command{awk} silently does nothing. +redirection, so @command{awk} silently does nothing, except return +a negative value. @cindex @code{|} (vertical bar), @code{|&} operator (I/O), pipes@comma{} closing When using the @samp{|&} operator to communicate with a coprocess, @@ -10064,10 +10205,10 @@ the first argument is the name of the command or special file used to start the coprocess. The second argument should be a string, with either of the values @code{"to"} or @code{"from"}. Case does not matter. -As this is an advanced feature, a more complete discussion is +As this is an advanced feature, discussion is delayed until @ref{Two-way I/O}, -which discusses it in more detail and gives an example. +which describes it in more detail and gives an example. @cindex sidebar, Using @code{close()}'s Return Value @ifdocbook @@ -10098,7 +10239,7 @@ retval = close(command) # syntax error in many Unix awks The return value is @minus{}1 if the argument names something that was never opened with a redirection, or if there is a system problem closing the file or process. -In these cases, @command{gawk} sets the built-in variable +In these cases, @command{gawk} sets the predefined variable @code{ERRNO} to a string describing the problem. In @command{gawk}, @@ -10154,7 +10295,7 @@ retval = close(command) # syntax error in many Unix awks The return value is @minus{}1 if the argument names something that was never opened with a redirection, or if there is a system problem closing the file or process. -In these cases, @command{gawk} sets the built-in variable +In these cases, @command{gawk} sets the predefined variable @code{ERRNO} to a string describing the problem. In @command{gawk}, @@ -10201,20 +10342,21 @@ that modify the behavior of the format control letters. @item Output from both @code{print} and @code{printf} may be redirected to -files, pipes, and co-processes. +files, pipes, and coprocesses. @item @command{gawk} provides special file names for access to standard input, output and error, and for network communications. @item -Use @code{close()} to close open file, pipe and co-process redirections. -For co-processes, it is possible to close only one direction of the +Use @code{close()} to close open file, pipe and coprocess redirections. +For coprocesses, it is possible to close only one direction of the communications. @end itemize -@node Output exercises +@c EXCLUDE START +@node Output Exercises @section Exercises @enumerate @@ -10243,6 +10385,7 @@ BEGIN @{ print "Serious error detected!" > /dev/stderr @} @end example @end enumerate +@c EXCLUDE END @c ENDOFRANGE prnt @@ -10341,7 +10484,7 @@ double-quotation marks. For example: @cindex strings, length limitations represents the string whose contents are @samp{parrot}. Strings in @command{gawk} can be of any length, and they can contain any of the possible -eight-bit ASCII characters including ASCII @sc{nul} (character code zero). +eight-bit ASCII characters including ASCII @value{NUL} (character code zero). Other @command{awk} implementations may have difficulty with some character codes. @@ -10486,7 +10629,8 @@ A regexp constant is a regular expression description enclosed in slashes, such as @code{@w{/^beginning and end$/}}. Most regexps used in @command{awk} programs are constant, but the @samp{~} and @samp{!~} matching operators can also match computed or dynamic regexps -(which are just ordinary strings or variables that contain a regexp). +(which are typically just ordinary strings or variables that contain a regexp, +but could be a more complex expression). @c ENDOFRANGE cnst @node Using Constant Regexps @@ -10520,7 +10664,7 @@ if (/barfly/ || /camelot/) @noindent are exactly equivalent. One rather bizarre consequence of this rule is that the following -Boolean expression is valid, but does not do what the user probably +Boolean expression is valid, but does not do what its author probably intended: @example @@ -10566,10 +10710,9 @@ Modern implementations of @command{awk}, including @command{gawk}, allow the third argument of @code{split()} to be a regexp constant, but some older implementations do not. @value{DARKCORNER} -This can lead to confusion when attempting to use regexp constants -as arguments to user-defined functions -(@pxref{User-defined}). -For example: +Because some built-in functions accept regexp constants as arguments, +it can be confusing when attempting to use regexp constants as arguments +to user-defined functions (@pxref{User-defined}). For example: @example function mysub(pat, repl, str, global) @@ -10624,7 +10767,11 @@ on the @command{awk} command line. Variables let you give names to values and refer to them later. Variables have already been used in many of the examples. The name of a variable must be a sequence of letters, digits, or underscores, and it may not begin -with a digit. Case is significant in variable names; @code{a} and @code{A} +with a digit. +Here, a @dfn{letter} is any one of the 52 upper- and lowercase +English letters. Other characters that may be defined as letters +in non-English locales are not valid in variable names. +Case is significant in variable names; @code{a} and @code{A} are distinct variables. A variable name is a valid expression by itself; it represents the @@ -10633,24 +10780,24 @@ 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{patsplit()} -and @code{split()} functions can change the contents of their +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}. @cindex variables, built-in @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 built-in variables. -These built-in variables can be used and assigned just like all other +record). @xref{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 built-in variables' names are entirely uppercase. +@command{awk}. All predefined variables' names are entirely uppercase. Variables in @command{awk} can be assigned either numeric or string values. The kind of value a variable holds can change over the life of a program. By default, variables are initialized to the empty string, which is zero if converted to a number. There is no need to explicitly -``initialize'' a variable in @command{awk}, +initialize a variable in @command{awk}, which is what you would do in C and in most other traditional languages. @node Assignment Options @@ -10770,7 +10917,7 @@ Strings that can't be interpreted as valid numbers convert to zero. @cindex @code{CONVFMT} variable The exact manner in which numbers are converted into strings is controlled -by the @command{awk} built-in variable @code{CONVFMT} (@pxref{Built-in Variables}). +by the @command{awk} predefined variable @code{CONVFMT} (@pxref{Built-in Variables}). Numbers are converted using the @code{sprintf()} function with @code{CONVFMT} as the format specifier @@ -10887,8 +11034,8 @@ $ @kbd{echo 4,321 | LC_ALL=en_DK.utf-8 gawk '@{ print $1 + 1 @}'} @noindent The @code{en_DK.utf-8} locale is for English in Denmark, where the comma acts as the decimal point separator. In the normal @code{"C"} locale, @command{gawk} -treats @samp{4,321} as @samp{4}, while in the Danish locale, it's treated -as the full number, 4.321. +treats @samp{4,321} as 4, while in the Danish locale, it's treated +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 @@ -11444,7 +11591,7 @@ awk '/[=]=/' /dev/null @end example @command{gawk} does not have this problem; BWK @command{awk} -and @command{mawk} also do not (@pxref{Other Versions}). +and @command{mawk} also do not. @docbook </sidebar> @@ -11490,7 +11637,7 @@ awk '/[=]=/' /dev/null @end example @command{gawk} does not have this problem; BWK @command{awk} -and @command{mawk} also do not (@pxref{Other Versions}). +and @command{mawk} also do not. @end cartouche @end ifnotdocbook @c ENDOFRANGE exas @@ -11802,7 +11949,7 @@ attribute. @item Fields, @code{getline} input, @code{FILENAME}, @code{ARGV} elements, @code{ENVIRON} elements, and the elements of an array created by -@code{patsplit()}, @code{split()} and @code{match()} 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. @@ -11957,22 +12104,23 @@ Thus, the six-character input string @w{@samp{ +3.14}} receives the The following examples print @samp{1} when the comparison between the two different constants is true, @samp{0} otherwise: +@c 22.9.2014: Tested with mawk and BWK awk, got same results. @example -$ @kbd{echo ' +3.14' | gawk '@{ print $0 == " +3.14" @}'} @ii{True} +$ @kbd{echo ' +3.14' | awk '@{ print($0 == " +3.14") @}'} @ii{True} @print{} 1 -$ @kbd{echo ' +3.14' | gawk '@{ print $0 == "+3.14" @}'} @ii{False} +$ @kbd{echo ' +3.14' | awk '@{ print($0 == "+3.14") @}'} @ii{False} @print{} 0 -$ @kbd{echo ' +3.14' | gawk '@{ print $0 == "3.14" @}'} @ii{False} +$ @kbd{echo ' +3.14' | awk '@{ print($0 == "3.14") @}'} @ii{False} @print{} 0 -$ @kbd{echo ' +3.14' | gawk '@{ print $0 == 3.14 @}'} @ii{True} +$ @kbd{echo ' +3.14' | awk '@{ print($0 == 3.14) @}'} @ii{True} @print{} 1 -$ @kbd{echo ' +3.14' | gawk '@{ print $1 == " +3.14" @}'} @ii{False} +$ @kbd{echo ' +3.14' | awk '@{ print($1 == " +3.14") @}'} @ii{False} @print{} 0 -$ @kbd{echo ' +3.14' | gawk '@{ print $1 == "+3.14" @}'} @ii{True} +$ @kbd{echo ' +3.14' | awk '@{ print($1 == "+3.14") @}'} @ii{True} @print{} 1 -$ @kbd{echo ' +3.14' | gawk '@{ print $1 == "3.14" @}'} @ii{False} +$ @kbd{echo ' +3.14' | awk '@{ print($1 == "3.14") @}'} @ii{False} @print{} 0 -$ @kbd{echo ' +3.14' | gawk '@{ print $1 == 3.14 @}'} @ii{True} +$ @kbd{echo ' +3.14' | awk '@{ print($1 == 3.14) @}'} @ii{True} @print{} 1 @end example @@ -12046,9 +12194,8 @@ part of the test always succeeds. Because the operators are so similar, this kind of error is very difficult to spot when scanning the source code. -@cindex @command{gawk}, comparison operators and -The following table of expressions illustrates the kind of comparison -@command{gawk} performs, as well as what the result of the comparison is: +The following list of expressions illustrates the kinds of comparisons +@command{awk} performs, as well as what the result of each comparison is: @table @code @item 1.5 <= 2.0 @@ -12121,7 +12268,7 @@ dynamic regexp (@pxref{Regexp Usage}; also @cindex @command{awk}, regexp constants and @cindex regexp constants -In modern implementations of @command{awk}, a constant regular +A constant regular expression in slashes by itself is also an expression. The regexp @code{/@var{regexp}/} is an abbreviation for the following comparison expression: @@ -12141,7 +12288,7 @@ where this is discussed in more detail. The POSIX standard says that string comparison is performed based on the locale's @dfn{collating order}. This is the order in which characters sort, as defined by the locale (for more discussion, -@pxref{Ranges and Locales}). This order is usually very different +@pxref{Locales}). This order is usually very different from the results obtained when doing straight character-by-character comparison.@footnote{Technically, string comparison is supposed to behave the same way as if the strings are compared with the C @@ -12221,7 +12368,7 @@ no substring @samp{foo} in the record. True if at least one of @var{boolean1} or @var{boolean2} is true. For example, the following statement prints all records in the input that contain @emph{either} @samp{edu} or -@samp{li} or both: +@samp{li}: @example if ($0 ~ /edu/ || $0 ~ /li/) print @@ -12230,6 +12377,9 @@ if ($0 ~ /edu/ || $0 ~ /li/) print The subexpression @var{boolean2} is evaluated only if @var{boolean1} is false. This can make a difference when @var{boolean2} contains expressions that have side effects. +(Thus, this test never really distinguishes records that contain both +@samp{edu} and @samp{li}---as soon as @samp{edu} is matched, +the full test succeeds.) @item ! @var{boolean} True if @var{boolean} is false. For example, @@ -12239,7 +12389,7 @@ variable is not defined: @example BEGIN @{ if (! ("HOME" in ENVIRON)) - print "no home!" @} + print "no home!" @} @end example (The @code{in} operator is described in @@ -12258,7 +12408,7 @@ is ``short-circuited'' if the result can be determined part way through its evaluation. @cindex line continuations -Statements that use @samp{&&} or @samp{||} can be continued simply +Statements that end with @samp{&&} or @samp{||} can be continued simply by putting a newline after them. But you cannot put a newline in front of either of these operators without using backslash continuation (@pxref{Statements/Lines}). @@ -12277,7 +12427,7 @@ program is one way to print lines in between special bracketing lines: @example $1 == "START" @{ interested = ! interested; next @} -interested == 1 @{ print @} +interested @{ print @} $1 == "END" @{ interested = ! interested; next @} @end example @@ -12297,6 +12447,16 @@ bogus input data, but the point is to illustrate the use of `!', so we'll leave well enough alone. @end ignore +Most commonly, the @samp{!} operator is used in the conditions of +@code{if} and @code{while} statements, where it often makes more +sense to phrase the logic in the negative: + +@example +if (! @var{some condition} || @var{some other condition}) @{ + @var{@dots{} do whatever processing @dots{}} +@} +@end example + @cindex @code{next} statement @quotation NOTE The @code{next} statement is discussed in @@ -12528,7 +12688,7 @@ expression because the first @samp{$} has higher precedence than the @samp{++}; to avoid the problem the expression can be rewritten as @samp{$($0++)--}. -This table presents @command{awk}'s operators, in order of highest +This list presents @command{awk}'s operators, in order of highest to lowest precedence: @c @asis for docbook to come out right @@ -12685,8 +12845,8 @@ system about the local character set and language. The ISO C standard defines a default @code{"C"} locale, which is an environment that is typical of what many C programmers are used to. -Once upon a time, the locale setting used to affect regexp matching -(@pxref{Ranges and Locales}), but this is no longer true. +Once upon a time, the locale setting used to affect regexp matching, +but this is no longer true (@pxref{Ranges and Locales}). Locales can affect record splitting. For the normal case of @samp{RS = "\n"}, the locale is largely irrelevant. For other single-character @@ -12698,7 +12858,7 @@ 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 @samp{%x} +Europe, however, it is abbreviated ``4.9.15.'' Thus, the @code{%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}. @@ -12740,7 +12900,8 @@ Locales can influence the conversions. @item @command{awk} provides the usual arithmetic operators (addition, subtraction, multiplication, division, modulus), and unary plus and minus. -It also provides comparison operators, boolean operators, and regexp +It also provides comparison operators, boolean operators, array membership +testing, and regexp matching operators. String concatenation is accomplished by placing two expressions next to each other; there is no explicit operator. The three-operand @samp{?:} operator provides an ``if-else'' test within @@ -12755,7 +12916,7 @@ In @command{awk}, a value is considered to be true if it is non-zero @emph{or} non-null. Otherwise, the value is false. @item -A value's type is set upon each assignment and may change over its +A variable's type is set upon each assignment and may change over its lifetime. The type determines how it behaves in comparisons (string or numeric). @@ -12787,7 +12948,7 @@ program, and occasionally the format for data read as input. As you have already seen, each @command{awk} statement consists of a pattern with an associated action. This @value{CHAPTER} describes how you build patterns and actions, what kinds of things you can do within -actions, and @command{awk}'s built-in variables. +actions, and @command{awk}'s predefined variables. The pattern-action rules and the statements available for use within actions form the core of @command{awk} programming. @@ -12802,7 +12963,7 @@ building something useful. * Action Overview:: What goes into an action. * Statements:: Describes the various control statements in detail. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * Pattern Action Summary:: Patterns and Actions summary. @end menu @@ -12835,7 +12996,7 @@ is nonzero (if a number) or non-null (if a string). (@xref{Expression Patterns}.) @item @var{begpat}, @var{endpat} -A pair of patterns separated by a comma, specifying a range of records. +A pair of patterns separated by a comma, specifying a @dfn{range} of records. The range includes both the initial record that matches @var{begpat} and the final record that matches @var{endpat}. (@xref{Ranges}.) @@ -12917,7 +13078,7 @@ Contrast this with the following regular expression match, which accepts any record with a first field that contains @samp{li}: @example -$ @kbd{awk '$1 ~ /foo/ @{ print $2 @}' mail-list} +$ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @print{} 555-5553 @print{} 555-6699 @end example @@ -12925,8 +13086,8 @@ $ @kbd{awk '$1 ~ /foo/ @{ 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 @code{/li/} has the value one if @samp{li} -appears in the current input record. Thus, as a pattern, @code{/li/} +pattern. The expression @samp{/li/} has the value one if @samp{li} +appears in the current input record. Thus, as a pattern, @samp{/li/} matches any record containing @samp{li}. @cindex Boolean expressions, as patterns @@ -13108,7 +13269,7 @@ input is read. For example: @example $ @kbd{awk '} > @kbd{BEGIN @{ print "Analysis of \"li\"" @}} -> @kbd{/li/ @{ ++n @}} +> @kbd{/li/ @{ ++n @}} > @kbd{END @{ print "\"li\" appears in", n, "records." @}' mail-list} @print{} Analysis of "li" @print{} "li" appears in 4 records. @@ -13188,9 +13349,10 @@ The POSIX standard specifies that @code{NF} is available in an @code{END} rule. It contains the number of fields from the last input record. Most probably due to an oversight, the standard does not say that @code{$0} is also preserved, although logically one would think that it should be. -In fact, @command{gawk} does preserve the value of @code{$0} for use in -@code{END} rules. Be aware, however, that BWK @command{awk}, and possibly -other implementations, do not. +In fact, all of BWK @command{awk}, @command{mawk}, and @command{gawk} +preserve the value of @code{$0} for use in @code{END} rules. Be aware, +however, that some other implementations and many older versions +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: @@ -13285,8 +13447,8 @@ level of the @command{awk} program. @cindex @code{next} statement, @code{BEGINFILE}/@code{ENDFILE} patterns and The @code{next} statement (@pxref{Next Statement}) is not allowed inside -either a @code{BEGINFILE} or and @code{ENDFILE} rule. The @code{nextfile} -statement (@pxref{Nextfile Statement}) is allowed only inside a +either a @code{BEGINFILE} or an @code{ENDFILE} rule. The @code{nextfile} +statement is allowed only inside a @code{BEGINFILE} rule, but not inside an @code{ENDFILE} rule. @cindex @code{getline} statement, @code{BEGINFILE}/@code{ENDFILE} patterns and @@ -13350,7 +13512,7 @@ There are two ways to get the value of the shell variable into the body of the @command{awk} program. @cindex shells, quoting -The most common method is to use shell quoting to substitute +A common method is to use shell quoting to substitute the variable's value into the program inside the script. For example, consider the following program: @@ -13607,20 +13769,21 @@ If the @var{condition} is true, it executes the statement @var{body}. is not zero and not a null string.) @end ifinfo After @var{body} has been executed, -@var{condition} is tested again, and if it is still true, @var{body} is -executed again. This process repeats until the @var{condition} is no longer -true. If the @var{condition} is initially false, the body of the loop is -never executed and @command{awk} continues with the statement following +@var{condition} is tested again, and if it is still true, @var{body} +executes again. This process repeats until the @var{condition} is no longer +true. If the @var{condition} is initially false, the body of the loop +never executes and @command{awk} continues with the statement following the loop. This example prints the first three fields of each record, one per line: @example -awk '@{ - i = 1 - while (i <= 3) @{ - print $i - i++ - @} +awk ' +@{ + i = 1 + while (i <= 3) @{ + print $i + i++ + @} @}' inventory-shipped @end example @@ -13654,14 +13817,14 @@ do while (@var{condition}) @end example -Even if the @var{condition} is false at the start, the @var{body} is -executed at least once (and only once, unless executing @var{body} +Even if the @var{condition} is false at the start, the @var{body} +executes at least once (and only once, unless executing @var{body} makes @var{condition} true). Contrast this with the corresponding @code{while} statement: @example while (@var{condition}) - @var{body} + @var{body} @end example @noindent @@ -13671,11 +13834,11 @@ The following is an example of a @code{do} statement: @example @{ - i = 1 - do @{ - print $0 - i++ - @} while (i <= 10) + i = 1 + do @{ + print $0 + i++ + @} while (i <= 10) @} @end example @@ -13712,9 +13875,10 @@ compares it against the desired number of iterations. For example: @example -awk '@{ - for (i = 1; i <= 3; i++) - print $i +awk ' +@{ + for (i = 1; i <= 3; i++) + print $i @}' inventory-shipped @end example @@ -13742,7 +13906,7 @@ between 1 and 100: @example for (i = 1; i <= 100; i *= 2) - print i + print i @end example If there is nothing to be done, any of the three expressions in the @@ -14033,9 +14197,8 @@ the beginning, in the following manner: @example NF != 4 @{ - err = sprintf("%s:%d: skipped: NF != 4\n", FILENAME, FNR) - print err > "/dev/stderr" - next + printf("%s:%d: skipped: NF != 4\n", FILENAME, FNR) > "/dev/stderr" + next @} @end example @@ -14063,7 +14226,7 @@ The @code{next} statement is not allowed inside @code{BEGINFILE} and @cindex functions, user-defined, @code{next}/@code{nextfile} statements and According to the POSIX standard, the behavior is undefined if the @code{next} statement is used in a @code{BEGIN} or @code{END} rule. -@command{gawk} treats it as a syntax error. Although POSIX permits it, +@command{gawk} treats it as a syntax error. Although POSIX does not disallow it, most other @command{awk} implementations don't allow the @code{next} statement inside function bodies (@pxref{User-defined}). Just as with any other @code{next} statement, a @code{next} statement inside a function @@ -14089,7 +14252,8 @@ starts over with the first rule in the program. If the @code{nextfile} statement causes the end of the input to be reached, then the code in any @code{END} rules is executed. An exception to this is when @code{nextfile} is invoked during execution of any statement in an -@code{END} rule; In this case, it causes the program to stop immediately. @xref{BEGIN/END}. +@code{END} rule; in this case, it causes the program to stop immediately. +@xref{BEGIN/END}. The @code{nextfile} statement is useful when there are many @value{DF}s to process but it isn't necessary to process every record in every file. @@ -14099,13 +14263,10 @@ would have to continue scanning the unwanted records. The @code{nextfile} statement accomplishes this much more efficiently. In @command{gawk}, execution of @code{nextfile} causes additional things -to happen: -any @code{ENDFILE} rules are executed except in the case as -mentioned below, -@code{ARGIND} is incremented, -and -any @code{BEGINFILE} rules are executed. -(@code{ARGIND} hasn't been introduced yet. @xref{Built-in Variables}.) +to happen: any @code{ENDFILE} rules are executed if @command{gawk} is +not currently in an @code{END} or @code{BEGINFILE} rule, @code{ARGIND} is +incremented, and any @code{BEGINFILE} rules are executed. (@code{ARGIND} +hasn't been introduced yet. @xref{Built-in Variables}.) With @command{gawk}, @code{nextfile} is useful inside a @code{BEGINFILE} rule to skip over a file that would otherwise cause @command{gawk} @@ -14120,7 +14281,7 @@ opened with redirections. It is not related to the main processing that @quotation NOTE For many years, @code{nextfile} was a -@command{gawk} extension. As of 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 @@ -14129,8 +14290,8 @@ See @uref{http://austingroupbugs.net/view.php?id=607, the Austin Group website}. @cindex @code{nextfile} statement, user-defined functions and @cindex Brian Kernighan's @command{awk} @cindex @command{mawk} utility -The current version of BWK @command{awk}, and @command{mawk} (@pxref{Other -Versions}) also support @code{nextfile}. However, they don't allow the +The current version of BWK @command{awk}, and @command{mawk} +also support @code{nextfile}. However, they don't allow the @code{nextfile} statement inside function bodies (@pxref{User-defined}). @command{gawk} does; a @code{nextfile} inside a function body reads the next record and starts processing it with the first rule in the program, @@ -14162,8 +14323,8 @@ the program to stop immediately. An @code{exit} statement that is not part of a @code{BEGIN} or @code{END} rule stops the execution of any further automatic rules for the current record, skips reading any remaining input records, and executes the -@code{END} rule if there is one. -Any @code{ENDFILE} rules are also skipped; they are not executed. +@code{END} rule if there is one. @command{gawk} also skips +any @code{ENDFILE} rules; they do not execute. In such a case, if you don't want the @code{END} rule to do its job, set a variable @@ -14211,11 +14372,11 @@ results across different operating systems. @c ENDOFRANGE accs @node Built-in Variables -@section Built-in Variables +@section Predefined Variables @c STARTOFRANGE bvar -@cindex built-in variables +@cindex predefined variables @c STARTOFRANGE varb -@cindex variables, built-in +@cindex variables, predefined Most @command{awk} variables are available to use for your own purposes; they never change unless your program assigns values to @@ -14226,8 +14387,8 @@ to tell @command{awk} how to do certain things. Others are set automatically by @command{awk}, so that they carry information from the internal workings of @command{awk} to your program. -@cindex @command{gawk}, built-in variables and -This @value{SECTION} documents all of @command{gawk}'s built-in variables, +@cindex @command{gawk}, predefined variables and +This @value{SECTION} documents all of @command{gawk}'s predefined variables, most of which are also documented in the @value{CHAPTER}s describing their areas of activity. @@ -14242,7 +14403,7 @@ their areas of activity. @node User-modified @subsection Built-in Variables That Control @command{awk} @c STARTOFRANGE bvaru -@cindex built-in variables, user-modifiable +@cindex predefined variables, user-modifiable @c STARTOFRANGE nmbv @cindex user-modifiable variables @@ -14271,7 +14432,7 @@ respectively, should use binary I/O. A string value of @code{"rw"} or @code{"wr"} indicates that all files should use binary I/O. Any other string value is treated the same as @code{"rw"}, but causes @command{gawk} to generate a warning message. @code{BINMODE} is described in more -detail in @ref{PC Using}. @command{mawk} @pxref{Other Versions}), +detail in @ref{PC Using}. @command{mawk} (@pxref{Other Versions}), also supports this variable, but only using numeric values. @cindex @code{CONVFMT} variable @@ -14398,7 +14559,7 @@ printing with the @code{print} statement. It works by being passed as the first argument to the @code{sprintf()} function (@pxref{String Functions}). Its default value is @code{"%.6g"}. Earlier versions of @command{awk} -also used @code{OFMT} to specify the format for converting numbers to +used @code{OFMT} to specify the format for converting numbers to strings in general expressions; this is now done by @code{CONVFMT}. @cindex @code{sprintf()} function, @code{OFMT} variable and @@ -14479,9 +14640,9 @@ The default value of @code{TEXTDOMAIN} is @code{"messages"}. @subsection Built-in Variables That Convey Information @c STARTOFRANGE bvconi -@cindex built-in variables, conveying information +@cindex predefined variables, conveying information @c STARTOFRANGE vbconi -@cindex variables, built-in, conveying information +@cindex variables, predefined conveying information The following is an alphabetical list of variables that @command{awk} sets automatically on certain occasions in order to provide information to your program. @@ -14550,8 +14711,8 @@ successive instances of the same @value{FN} on the command line. @cindex file names, distinguishing While you can change the value of @code{ARGIND} within your @command{awk} -program, @command{gawk} automatically sets it to a new value when the -next file is opened. +program, @command{gawk} automatically sets it to a new value when it +opens the next file. @cindex @code{ENVIRON} array @cindex environment variables, in @code{ENVIRON} array @@ -14616,10 +14777,10 @@ can give @code{FILENAME} a value. @cindex @code{FNR} variable @item @code{FNR} -The current record number in the current file. @code{FNR} is -incremented each time a new record is read -(@pxref{Records}). It is reinitialized -to zero each time a new input file is started. +The current record number in the current file. @command{awk} increments +@code{FNR} each time it reads a new record (@pxref{Records}). +@command{awk} resets @code{FNR} to zero each time it starts a new +input file. @cindex @code{NF} variable @item @code{NF} @@ -14638,7 +14799,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 user-defined or 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} @@ -14651,7 +14812,7 @@ array causes a fatal error. Any attempt to assign to an element of The number of input records @command{awk} has processed since the beginning of the program's execution (@pxref{Records}). -@code{NR} is incremented each time a new record is read. +@command{awk} increments @code{NR} each time it reads a new record. @cindex @command{gawk}, @code{PROCINFO} array in @cindex @code{PROCINFO} array @@ -14679,16 +14840,22 @@ or @code{"FPAT"} if field matching with @code{FPAT} is in effect. @item PROCINFO["identifiers"] @cindex program identifiers -A subarray, indexed by the names of all identifiers used in the -text of the AWK program. For each identifier, the value of the element is one of the following: +A subarray, indexed by the names of all identifiers used in the text of +the AWK program. An @dfn{identifier} is simply the name of a variable +(be it scalar or array), built-in function, user-defined function, or +extension function. For each identifier, the value of the element is +one of the following: @table @code @item "array" The identifier is an array. +@item "builtin" +The identifier is a built-in function. + @item "extension" The identifier is an extension function loaded via -@code{@@load}. +@code{@@load} or @option{-l}. @item "scalar" The identifier is a scalar. @@ -14725,7 +14892,7 @@ The parent process ID of the current process. @item PROCINFO["sorted_in"] If this element exists in @code{PROCINFO}, its value controls the order in which array indices will be processed by -@samp{for (@var{index} in @var{array})} loops. +@samp{for (@var{indx} in @var{array})} loops. Since this is an advanced feature, we defer the full description until later; see @ref{Scanning an Array}. @@ -14746,7 +14913,7 @@ 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 numbers +if your version of @command{gawk} supports arbitrary precision arithmetic (@pxref{Arbitrary Precision Arithmetic}): @table @code @@ -14795,14 +14962,14 @@ The @code{PROCINFO} array has the following additional uses: @itemize @value{BULLET} @item -It may be used to cause coprocesses to communicate over pseudo-ttys -instead of through two-way pipes; this is discussed further in -@ref{Two-way I/O}. - -@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. + +@item +It may be used to cause coprocesses to communicate over pseudo-ttys +instead of through two-way pipes; this is discussed further in +@ref{Two-way I/O}. @end itemize @cindex @code{RLENGTH} variable @@ -14833,9 +15000,13 @@ the record separator. It is set every time a record is read. @cindex @code{SYMTAB} array @cindex differences in @command{awk} and @command{gawk}, @code{SYMTAB} variable @item @code{SYMTAB #} -An array whose indices are the names of all currently defined -global variables and arrays in the program. The array may be used -for indirect access to read or write the value of a variable: +An array whose indices are the names of all defined global variables and +arrays in the program. @code{SYMTAB} makes @command{gawk}'s symbol table +visible to the @command{awk} programmer. It is built as @command{gawk} +parses the program and is complete before the program starts to run. + +The array may be used for indirect access to read or write the value of +a variable: @example foo = 5 @@ -14968,7 +15139,7 @@ changed. @cindex arguments, command-line @cindex command line, arguments -@ref{Auto-set}, +@DBREF{Auto-set} presented the following program describing the information contained in @code{ARGC} and @code{ARGV}: @@ -15090,6 +15261,12 @@ following @option{-v} are passed on to the @command{awk} program. (@xref{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 +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}). + @node Pattern Action Summary @section Summary @@ -15124,7 +15301,7 @@ input and output statements, and deletion statements. The control statements in @command{awk} are @code{if}-@code{else}, @code{while}, @code{for}, and @code{do}-@code{while}. @command{gawk} adds the @code{switch} statement. There are two flavors of @code{for} -statement: one for for performing general looping, and the other iterating +statement: one for performing general looping, and the other for iterating through an array. @item @@ -15141,12 +15318,17 @@ The @code{exit} statement terminates your program. When executed from an action (or function body) it transfers control to the @code{END} statements. From an @code{END} statement body, it exits immediately. You may pass an optional numeric value to be used -at @command{awk}'s exit status. +as @command{awk}'s exit status. @item -Some built-in variables provide control over @command{awk}, mainly for I/O. +Some predefined variables provide control over @command{awk}, mainly for I/O. Other variables convey information from @command{awk} to your program. +@item +@code{ARGC} and @code{ARGV} make the command-line arguments available +to your program. Manipulating them from a @code{BEGIN} rule lets you +control how @command{awk} will process the provided @value{DF}s. + @end itemize @node Arrays @@ -15167,24 +15349,13 @@ The @value{CHAPTER} moves on to discuss @command{gawk}'s facility for sorting arrays, and ends with a brief description of @command{gawk}'s ability to support true arrays of arrays. -@cindex variables, names of -@cindex functions, names of -@cindex arrays, names of, and names of functions/variables -@cindex names, arrays/variables -@cindex namespace issues -@command{awk} maintains a single set -of names that may be used for naming variables, arrays, and functions -(@pxref{User-defined}). -Thus, you cannot have a variable and an array with the same name in the -same @command{awk} program. - @menu * Array Basics:: The basics of arrays. -* Delete:: The @code{delete} statement removes an element - from an array. * Numeric Array Subscripts:: How to use numbers as subscripts in @command{awk}. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. +* Delete:: The @code{delete} statement removes an element + from an array. * Multidimensional:: Emulating multidimensional arrays in @command{awk}. * Arrays of Arrays:: True multidimensional arrays. @@ -15230,7 +15401,7 @@ as a variable) in the same @command{awk} program. Arrays in @command{awk} superficially resemble arrays in other programming languages, but there are fundamental differences. In @command{awk}, it isn't necessary to specify the size of an array before starting to use it. -Additionally, any number or string in @command{awk}, not just consecutive integers, +Additionally, any number or string, not just consecutive integers, may be used as an array index. In most other languages, arrays must be @dfn{declared} before use, @@ -15343,7 +15514,10 @@ array element value: @end docbook @noindent -The pairs are shown in jumbled order because their order is irrelevant. +The pairs are shown in jumbled order because their order is +irrelevant.@footnote{The ordering will vary among @command{awk} +implementations, which typically use hash tables to store array elements +and values.} One advantage of associative arrays is that new pairs can be added at any time. For example, suppose a tenth element is added to the array @@ -15465,8 +15639,9 @@ English to French: Here we decided to translate the number one in both spelled-out and numeric form---thus illustrating that a single array can have both numbers and strings as indices. -(In fact, array subscripts are always strings; this is discussed -in more detail in +(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 @ref{Numeric Array Subscripts}.) Here, the number @code{1} isn't double-quoted, since @command{awk} automatically converts it to a string. @@ -15553,6 +15728,8 @@ 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 +function.) For example, this statement tests whether the array @code{frequencies} contains the index @samp{2}: @@ -15606,14 +15783,14 @@ begin with a number: @example @c file eg/misc/arraymax.awk @{ - if ($1 > max) - max = $1 - arr[$1] = $0 + if ($1 > max) + max = $1 + arr[$1] = $0 @} END @{ - for (x = 1; x <= max; x++) - print arr[x] + for (x = 1; x <= max; x++) + print arr[x] @} @c endfile @end example @@ -15653,9 +15830,9 @@ program's @code{END} rule, as follows: @example END @{ - for (x = 1; x <= max; x++) - if (x in arr) - print arr[x] + for (x = 1; x <= max; x++) + if (x in arr) + print arr[x] @} @end example @@ -15677,7 +15854,7 @@ an array: @example for (@var{var} in @var{array}) - @var{body} + @var{body} @end example @noindent @@ -15750,7 +15927,7 @@ BEGIN @{ @} @end example -Here is what happens when run with @command{gawk}: +Here is what happens when run with @command{gawk} (and @command{mawk}): @example $ @kbd{gawk -f loopcheck.awk} @@ -15868,7 +16045,8 @@ does not affect the loop. For example: @example -$ @kbd{gawk 'BEGIN @{} +$ @kbd{gawk '} +> @kbd{BEGIN @{} > @kbd{ a[4] = 4} > @kbd{ a[3] = 3} > @kbd{ for (i in a)} @@ -15876,7 +16054,8 @@ $ @kbd{gawk 'BEGIN @{} > @kbd{@}'} @print{} 4 4 @print{} 3 3 -$ @kbd{gawk 'BEGIN @{} +$ @kbd{gawk '} +> @kbd{BEGIN @{} > @kbd{ PROCINFO["sorted_in"] = "@@ind_str_asc"} > @kbd{ a[4] = 4} > @kbd{ a[3] = 3} @@ -15925,118 +16104,6 @@ the @code{delete} statement. In addition, @command{gawk} provides built-in functions for sorting arrays; see @ref{Array Sorting Functions}. -@node Delete -@section The @code{delete} Statement -@cindex @code{delete} statement -@cindex deleting elements in arrays -@cindex arrays, elements, deleting -@cindex elements in arrays, deleting - -To remove an individual element of an array, use the @code{delete} -statement: - -@example -delete @var{array}[@var{index-expression}] -@end example - -Once an array element has been deleted, any value the element once -had is no longer available. It is as if the element had never -been referred to or been given a value. -The following is an example of deleting elements in an array: - -@example -for (i in frequencies) - delete frequencies[i] -@end example - -@noindent -This example removes all the elements from the array @code{frequencies}. -Once an element is deleted, a subsequent @code{for} statement to scan the array -does not report that element and the @code{in} operator to check for -the presence of that element returns zero (i.e., false): - -@example -delete foo[4] -if (4 in foo) - print "This will never be printed" -@end example - -@cindex null strings, and deleting array elements -It is important to note that deleting an element is @emph{not} the -same as assigning it a null value (the empty string, @code{""}). -For example: - -@example -foo[4] = "" -if (4 in foo) - print "This is printed, even though foo[4] is empty" -@end example - -@cindex lint checking, array elements -It is not an error to delete an element that does not exist. -However, if @option{--lint} is provided on the command line -(@pxref{Options}), -@command{gawk} issues a warning message when an element that -is not in the array is deleted. - -@cindex common extensions, @code{delete} to delete entire arrays -@cindex extensions, common@comma{} @code{delete} to delete entire arrays -@cindex arrays, deleting entire contents -@cindex deleting entire arrays -@cindex @code{delete} @var{array} -@cindex differences in @command{awk} and @command{gawk}, array elements, deleting -All the elements of an array may be deleted with a single statement -by leaving off the subscript in the @code{delete} statement, -as follows: - - -@example -delete @var{array} -@end example - -Using this version of the @code{delete} statement is about three times -more efficient than the equivalent loop that deletes each element one -at a time. - -@cindex Brian Kernighan's @command{awk} -@quotation NOTE -For many years, -using @code{delete} without a subscript was a @command{gawk} extension. -As of September, 2012, it was accepted for -inclusion into the POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=544, -the Austin Group website}. This form of the @code{delete} statement is also supported -by BWK @command{awk} and @command{mawk}, as well as -by a number of other implementations (@pxref{Other Versions}). -@end quotation - -@cindex portability, deleting array elements -@cindex Brennan, Michael -The following statement provides a portable but nonobvious way to clear -out an array:@footnote{Thanks to Michael Brennan for pointing this out.} - -@example -split("", array) -@end example - -@cindex @code{split()} function, array elements@comma{} deleting -The @code{split()} function -(@pxref{String Functions}) -clears out the target array first. This call asks it to split -apart the null string. Because there is no data to split out, the -function simply clears the array and then returns. - -@quotation CAUTION -Deleting an array does not change its type; you cannot -delete an array and then use the array's name as a scalar -(i.e., a regular variable). For example, the following does not work: - -@example -a[1] = 3 -delete a -a = 3 -@end example -@end quotation - @node Numeric Array Subscripts @section Using Numbers to Subscript Arrays @@ -16048,7 +16115,7 @@ An important aspect to remember about arrays is that @emph{array subscripts are always strings}. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting (@pxref{Conversion}). -This means that the value of the built-in variable @code{CONVFMT} can +This means that the value of the predefined variable @code{CONVFMT} can affect how your program accesses elements of an array. For example: @example @@ -16077,7 +16144,7 @@ since @code{"12.15"} is different from @code{"12.153"}. @cindex integer array indices According to the rules for conversions (@pxref{Conversion}), integer -values are always converted to strings as integers, no matter what the +values always convert to strings as integers, no matter what the value of @code{CONVFMT} may happen to be. So the usual case of the following works: @@ -16100,7 +16167,7 @@ and all refer to the same element! As with many things in @command{awk}, the majority of the time -things work as one would expect them to. But it is useful to have a precise +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 effect on your programs. @@ -16121,7 +16188,7 @@ $ @kbd{echo 'line 1} > @kbd{line 2} > @kbd{line 3' | awk '@{ l[lines] = $0; ++lines @}} > @kbd{END @{} -> @kbd{for (i = lines-1; i >= 0; --i)} +> @kbd{for (i = lines - 1; i >= 0; i--)} > @kbd{print l[i]} > @kbd{@}'} @print{} line 3 @@ -16145,7 +16212,7 @@ The following version of the program works correctly: @example @{ l[lines++] = $0 @} END @{ - for (i = lines - 1; i >= 0; --i) + for (i = lines - 1; i >= 0; i--) print l[i] @} @end example @@ -16164,6 +16231,119 @@ Even though it is somewhat unusual, the null string if @option{--lint} is provided on the command line (@pxref{Options}). +@node Delete +@section The @code{delete} Statement +@cindex @code{delete} statement +@cindex deleting elements in arrays +@cindex arrays, elements, deleting +@cindex elements in arrays, deleting + +To remove an individual element of an array, use the @code{delete} +statement: + +@example +delete @var{array}[@var{index-expression}] +@end example + +Once an array element has been deleted, any value the element once +had is no longer available. It is as if the element had never +been referred to or been given a value. +The following is an example of deleting elements in an array: + +@example +for (i in frequencies) + delete frequencies[i] +@end example + +@noindent +This example removes all the elements from the array @code{frequencies}. +Once an element is deleted, a subsequent @code{for} statement to scan the array +does not report that element and the @code{in} operator to check for +the presence of that element returns zero (i.e., false): + +@example +delete foo[4] +if (4 in foo) + print "This will never be printed" +@end example + +@cindex null strings, and deleting array elements +It is important to note that deleting an element is @emph{not} the +same as assigning it a null value (the empty string, @code{""}). +For example: + +@example +foo[4] = "" +if (4 in foo) + print "This is printed, even though foo[4] is empty" +@end example + +@cindex lint checking, array elements +It is not an error to delete an element that does not exist. +However, if @option{--lint} is provided on the command line +(@pxref{Options}), +@command{gawk} issues a warning message when an element that +is not in the array is deleted. + +@cindex common extensions, @code{delete} to delete entire arrays +@cindex extensions, common@comma{} @code{delete} to delete entire arrays +@cindex arrays, deleting entire contents +@cindex deleting entire arrays +@cindex @code{delete} @var{array} +@cindex differences in @command{awk} and @command{gawk}, array elements, deleting +All the elements of an array may be deleted with a single statement +by leaving off the subscript in the @code{delete} statement, +as follows: + + +@example +delete @var{array} +@end example + +Using this version of the @code{delete} statement is about three times +more efficient than the equivalent loop that deletes each element one +at a time. + +This form of the @code{delete} statement is also supported +by BWK @command{awk} and @command{mawk}, as well as +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 +POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=544, +the Austin Group website}. +@end quotation + +@cindex portability, deleting array elements +@cindex Brennan, Michael +The following statement provides a portable but nonobvious way to clear +out an array:@footnote{Thanks to Michael Brennan for pointing this out.} + +@example +split("", array) +@end example + +@cindex @code{split()} function, array elements@comma{} deleting +The @code{split()} function +(@pxref{String Functions}) +clears out the target array first. This call asks it to split +apart the null string. Because there is no data to split out, the +function simply clears the array and then returns. + +@quotation CAUTION +Deleting all the elements from an array does not change its type; you cannot +clear an array and then use the array's name as a scalar +(i.e., a regular variable). For example, the following does not work: + +@example +a[1] = 3 +delete a +a = 3 +@end example +@end quotation + @node Multidimensional @section Multidimensional Arrays @@ -16175,7 +16355,7 @@ on the command line (@pxref{Options}). @cindex arrays, multidimensional 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 most +two-dimensional array requires two indices. The usual way (in many languages, including @command{awk}) to refer to an element of a two-dimensional array named @code{grid} is with @code{grid[@var{x},@var{y}]}. @@ -16350,8 +16530,9 @@ a[1][3][1, "name"] = "barney" Each subarray and the main array can be of different length. In fact, the elements of an array or its subarray do not all have to have the same type. This means that the main array and any of its subarrays can be -non-rectangular, or jagged in structure. One can assign a scalar value to -the index @code{4} of the main array @code{a}: +non-rectangular, or jagged in structure. You can assign a scalar value to +the index @code{4} of the main array @code{a}, even though @code{a[1]} +is itself an array and not a scalar: @example a[4] = "An element in a jagged array" @@ -16433,6 +16614,8 @@ for (i in array) @{ print array[i][j] @} @} + else + print array[i] @} @end example @@ -16717,8 +16900,9 @@ Often random integers are needed instead. Following is a user-defined function that can be used to obtain a random non-negative integer less than @var{n}: @example -function randint(n) @{ - return int(n * rand()) +function randint(n) +@{ + return int(n * rand()) @} @end example @@ -16738,8 +16922,7 @@ function roll(n) @{ return 1 + int(rand() * n) @} # Roll 3 six-sided dice and # print total number of points. @{ - printf("%d points\n", - roll(6)+roll(6)+roll(6)) + printf("%d points\n", roll(6) + roll(6) + roll(6)) @} @end example @@ -16828,7 +17011,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 in alphabetic order. +towards the end since 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 @@ -16872,6 +17055,7 @@ When comparing strings, @code{IGNORECASE} affects the sorting (@pxref{Array Sorting Functions}). If the @var{source} array contains subarrays as values (@pxref{Arrays of Arrays}), they will come last, after all scalar values. +Subarrays are @emph{not} recursively sorted. For example, if the contents of @code{a} are as follows: @@ -17008,7 +17192,10 @@ $ @kbd{awk 'BEGIN @{ print index("peanut", "an") @}'} @noindent If @var{find} is not found, @code{index()} returns zero. -It is a fatal error to use a regexp constant for @var{find}. +With BWK @command{awk} and @command{gawk}, +it is a fatal error to use a regexp constant for @var{find}. +Other implementations allow it, simply treating the regexp +constant as an expression meaning @samp{$0 ~ /regexp/}. @value{DARKCORNER}. @item @code{length(}[@var{string}]@code{)} @cindexawkfunc{length} @@ -17112,8 +17299,8 @@ for @code{match()}, the order is the same as for the @samp{~} operator: @cindex @code{RSTART} variable, @code{match()} function and @cindex @code{RLENGTH} variable, @code{match()} function and @cindex @code{match()} function, @code{RSTART}/@code{RLENGTH} variables -The @code{match()} function sets the built-in variable @code{RSTART} to -the index. It also sets the built-in variable @code{RLENGTH} to the +The @code{match()} function sets the predefined variable @code{RSTART} to +the index. It also sets the predefined variable @code{RLENGTH} to the length in characters of the matched substring. If no match is found, @code{RSTART} is set to zero, and @code{RLENGTH} to @minus{}1. @@ -17122,13 +17309,12 @@ For example: @example @c file eg/misc/findpat.awk @{ - if ($1 == "FIND") - regex = $2 - else @{ - where = match($0, regex) - if (where != 0) - print "Match of", regex, "found at", - where, "in", $0 + if ($1 == "FIND") + regex = $2 + else @{ + where = match($0, regex) + if (where != 0) + print "Match of", regex, "found at", where, "in", $0 @} @} @c endfile @@ -17224,7 +17410,7 @@ Any leading separator will be in @code{@var{seps}[0]}. The @code{patsplit()} function splits strings into pieces in a manner similar to the way input lines are split into fields using @code{FPAT} -(@pxref{Splitting By Content}. +(@pxref{Splitting By Content}). Before splitting the string, @code{patsplit()} deletes any previously existing elements in the arrays @var{array} and @var{seps}. @@ -17237,8 +17423,7 @@ and store the pieces in @var{array} and the separator strings in the @code{@var{array}[1]}, the second piece in @code{@var{array}[2]}, and so forth. The string value of the third argument, @var{fieldsep}, is a regexp describing where to split @var{string} (much as @code{FS} can -be a regexp describing where to split input records; -@pxref{Regexp Field Splitting}). +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}]} @@ -17533,6 +17718,59 @@ Nonalphabetic characters are left unchanged. For example, @code{toupper("MiXeD cAsE 123")} returns @code{"MIXED CASE 123"}. @end table +@cindex sidebar, Matching the Null String +@ifdocbook +@docbook +<sidebar><title>Matching the Null String</title> +@end docbook + +@cindex matching, null strings +@cindex null strings, matching +@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching +@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching + +In @command{awk}, the @samp{*} operator can match the null string. +This is particularly important for the @code{sub()}, @code{gsub()}, +and @code{gensub()} functions. For example: + +@example +$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'} +@print{} XaXbXcX +@end example + +@noindent +Although this makes a certain amount of sense, it can be surprising. + +@docbook +</sidebar> +@end docbook +@end ifdocbook + +@ifnotdocbook +@cartouche +@center @b{Matching the Null String} + + +@cindex matching, null strings +@cindex null strings, matching +@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching +@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching + +In @command{awk}, the @samp{*} operator can match the null string. +This is particularly important for the @code{sub()}, @code{gsub()}, +and @code{gensub()} functions. For example: + +@example +$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'} +@print{} XaXbXcX +@end example + +@noindent +Although this makes a certain amount of sense, it can be surprising. +@end cartouche +@end ifnotdocbook + + @node Gory Details @subsubsection More About @samp{\} and @samp{&} with @code{sub()}, @code{gsub()}, and @code{gensub()} @@ -17546,7 +17784,7 @@ Nonalphabetic characters are left unchanged. For example, @cindex ampersand (@code{&}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @quotation CAUTION -This section has been known to cause headaches. +This subsubsection has been reported to cause headaches. You might want to skip it upon first reading. @end quotation @@ -17837,58 +18075,6 @@ and the special cases for @code{sub()} and @code{gsub()}, we recommend the use of @command{gawk} and @code{gensub()} when you have to do substitutions. -@cindex sidebar, Matching the Null String -@ifdocbook -@docbook -<sidebar><title>Matching the Null String</title> -@end docbook - -@cindex matching, null strings -@cindex null strings, matching -@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching -@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching - -In @command{awk}, the @samp{*} operator can match the null string. -This is particularly important for the @code{sub()}, @code{gsub()}, -and @code{gensub()} functions. For example: - -@example -$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'} -@print{} XaXbXcX -@end example - -@noindent -Although this makes a certain amount of sense, it can be surprising. - -@docbook -</sidebar> -@end docbook -@end ifdocbook - -@ifnotdocbook -@cartouche -@center @b{Matching the Null String} - - -@cindex matching, null strings -@cindex null strings, matching -@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching -@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching - -In @command{awk}, the @samp{*} operator can match the null string. -This is particularly important for the @code{sub()}, @code{gsub()}, -and @code{gensub()} functions. For example: - -@example -$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'} -@print{} XaXbXcX -@end example - -@noindent -Although this makes a certain amount of sense, it can be surprising. -@end cartouche -@end ifnotdocbook - @node I/O Functions @subsection Input/Output Functions @cindex input/output functions @@ -17941,10 +18127,9 @@ buffers its output and the @code{fflush()} function forces @cindex extensions, common@comma{} @code{fflush()} function @cindex Brian Kernighan's @command{awk} -@code{fflush()} was added to BWK @command{awk} in -April of 1992. For two decades, it was not part of the POSIX standard. -As of December, 2012, it was accepted for inclusion into the POSIX -standard. +Brian Kernighan added @code{fflush()} to his @command{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 @uref{http://austingroupbugs.net/view.php?id=634, the Austin Group website}. POSIX standardizes @code{fflush()} as follows: If there @@ -18341,7 +18526,7 @@ is out of range, @code{mktime()} returns @minus{}1. @cindex @command{gawk}, @code{PROCINFO} array in @cindex @code{PROCINFO} array -@item @code{strftime(} [@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag}] ] ]@code{)} +@item @code{strftime(}[@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag}] ] ]@code{)} @c STARTOFRANGE strf @cindexgawkfunc{strftime} @cindex format time string @@ -18447,7 +18632,7 @@ of its ISO week number is 2013, even though its year is 2012. The full year of the ISO week number, as a decimal number. @item %h -Equivalent to @samp{%b}. +Equivalent to @code{%b}. @item %H The hour (24-hour clock) as a decimal number (00--23). @@ -18516,7 +18701,7 @@ The locale's ``appropriate'' date representation. @item %X The locale's ``appropriate'' time representation. -(This is @samp{%T} in the @code{"C"} locale.) +(This is @code{%T} in the @code{"C"} locale.) @item %y The year modulo 100 as a decimal number (00--99). @@ -18537,7 +18722,7 @@ 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 (@samp{%c}, @samp{%C}, +that use only the second letter (@code{%c}, @code{%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. @@ -18608,7 +18793,7 @@ the string. For example: @example $ date '+Today is %A, %B %d, %Y.' -@print{} Today is Monday, May 05, 2014. +@print{} Today is Monday, September 22, 2014. @end example Here is the @command{gawk} version of the @command{date} utility. @@ -18800,19 +18985,18 @@ For example, if you have a bit string @samp{10111001} and you shift it right by three bits, you end up with @samp{00010111}.@footnote{This example shows that 0's come in on the left side. For @command{gawk}, this is always true, but in some languages, it's possible to have the left side -fill with 1's. Caveat emptor.} +fill with 1's.} @c Purposely decided to use 0's and 1's here. 2/2001. -If you start over -again with @samp{10111001} and shift it left by three bits, you end up -with @samp{11001000}. -@command{gawk} provides built-in functions that implement the -bitwise operations just described. They are: +If you start over again with @samp{10111001} and shift it left by three +bits, you end up with @samp{11001000}. The following list describes +@command{gawk}'s built-in functions that implement the bitwise operations. +Optional parameters are enclosed in square brackets ([ ]): @cindex @command{gawk}, bitwise operations in @table @code @cindexgawkfunc{and} @cindex bitwise AND -@item @code{and(@var{v1}, @var{v2}} [@code{,} @dots{}]@code{)} +@item @code{and(}@var{v1}@code{,} @var{v2} [@code{,} @dots{}]@code{)} Return the bitwise AND of the arguments. There must be at least two. @cindexgawkfunc{compl} @@ -18827,7 +19011,7 @@ Return the value of @var{val}, shifted left by @var{count} bits. @cindexgawkfunc{or} @cindex bitwise OR -@item @code{or(@var{v1}, @var{v2}} [@code{,} @dots{}]@code{)} +@item @code{or(}@var{v1}@code{,} @var{v2} [@code{,} @dots{}]@code{)} Return the bitwise OR of the arguments. There must be at least two. @cindexgawkfunc{rshift} @@ -18837,7 +19021,7 @@ Return the value of @var{val}, shifted right by @var{count} bits. @cindexgawkfunc{xor} @cindex bitwise XOR -@item @code{xor(@var{v1}, @var{v2}} [@code{,} @dots{}]@code{)} +@item @code{xor(}@var{v1}@code{,} @var{v2} [@code{,} @dots{}]@code{)} Return the bitwise XOR of the arguments. There must be at least two. @end table @@ -18960,7 +19144,7 @@ results of the @code{compl()}, @code{lshift()}, and @code{rshift()} functions. @command{gawk} provides a single function that lets you distinguish an array from a scalar variable. This is necessary for writing code -that traverses every element of an array of arrays. +that traverses every element of an array of arrays (@pxref{Arrays of Arrays}). @table @code @@ -18976,12 +19160,14 @@ an array or not. The second is inside the body of a user-defined function (not discussed yet; @pxref{User-defined}), to test if a parameter is an array or not. -Note, however, that using @code{isarray()} at the global level to test +@quotation NOTE +Using @code{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 @command{gawk} works, if you pass the name of a variable that has not been previously used to @code{isarray()}, @command{gawk} -will end up turning it into a scalar. +ends up turning it into a scalar. +@end quotation @node I18N Functions @subsection String-Translation Functions @@ -19058,6 +19244,12 @@ them, i.e., to tell @command{awk} what they should do. @node Definition Syntax @subsection Function Definition Syntax +@quotation +@i{It's entirely fair to say that the @command{awk} syntax for local +variable definitions is appallingly awful.} +@author Brian Kernighan +@end quotation + @c STARTOFRANGE fdef @cindex functions, defining Definitions of functions can appear anywhere between the rules of an @@ -19084,6 +19276,8 @@ The definition of a function named @var{name} looks like this: Here, @var{name} is the name of the function to define. A valid function name is like a valid variable name: a sequence of letters, digits, and underscores that doesn't start with a digit. +Here too, only the 52 upper- and lowercase English letters may +be used in a function name. Within a single @command{awk} program, any particular name can only be used as a variable, array, or function. @@ -19095,9 +19289,9 @@ the call. A function cannot have two parameters with the same name, nor may it have a parameter with the same name as the function itself. In addition, according to the POSIX standard, function parameters -cannot have the same name as one of the special built-in variables +cannot have the same name as one of the special predefined variables (@pxref{Built-in Variables}). Not all versions of @command{awk} enforce -this restriction.) +this restriction. Local variables act like the empty string if referenced where a string value is required, and like zero if referenced where a numeric value @@ -19234,7 +19428,7 @@ extra whitespace signifies the start of the local variable list): function delarray(a, i) @{ for (i in a) - delete a[i] + delete a[i] @} @end example @@ -19245,7 +19439,7 @@ Instead of having to repeat this loop everywhere that you need to clear out an array, your program can just call @code{delarray}. (This guarantees portability. The use of @samp{delete @var{array}} to delete -the contents of an entire array is a recent@footnote{Late in 2012.} +the contents of an entire array is a relatively recent@footnote{Late in 2012.} addition to the POSIX standard.) The following is an example of a recursive function. It takes a string @@ -19275,7 +19469,7 @@ $ @kbd{echo "Don't Panic!" |} @print{} !cinaP t'noD @end example -The C @code{ctime()} function takes a timestamp and returns it in a string, +The C @code{ctime()} function takes a timestamp and returns it as a string, formatted in a well-known fashion. The following example uses the built-in @code{strftime()} function (@pxref{Time Functions}) @@ -19290,13 +19484,19 @@ to create an @command{awk} version of @code{ctime()}: function ctime(ts, format) @{ - format = PROCINFO["strftime"] + format = "%a %b %e %H:%M:%S %Z %Y" + if (ts == 0) ts = systime() # use current time as default return strftime(format, ts) @} @c endfile @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 +supposed to return the time formatted in a standard fashion, and user-level +code could have changed @code{PROCINFO["strftime"]}. @c ENDOFRANGE fdef @node Function Caveats @@ -19732,7 +19932,7 @@ being aware of them. @cindex pointers to functions @cindex differences in @command{awk} and @command{gawk}, indirect function calls -This section describes a @command{gawk}-specific extension. +This section describes an advanced, @command{gawk}-specific extension. Often, you may wish to defer the choice of function to call until runtime. For example, you may have different kinds of records, each of which @@ -19778,8 +19978,11 @@ To process the data, you might write initially: @noindent This style of programming works, but can be awkward. With @dfn{indirect} function calls, you tell @command{gawk} to use the @emph{value} of a -variable as the name of the function to call. +variable as the @emph{name} of the function to call. +@cindex @code{@@}-notation for indirect function calls +@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{@@} @@ -19837,7 +20040,6 @@ Otherwise they perform the expected computations and are not unusual. @example @c file eg/prog/indirectcall.awk # For each record, print the class name and the requested statistics - @{ class_name = $1 gsub(/_/, " ", class_name) # Replace _ with spaces @@ -19866,7 +20068,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 @samp{%s} as the format specifier so that we +(The @code{printf} format string uses @code{%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.) @@ -19943,7 +20145,7 @@ function quicksort(data, left, right, less_than, i, last) # quicksort_swap --- helper function for quicksort, should really be inline -function quicksort_swap(data, i, j, temp) +function quicksort_swap(data, i, j, temp) @{ temp = data[i] data[i] = data[j] @@ -20064,12 +20266,77 @@ $ @kbd{gawk -f quicksort.awk -f indirectcall.awk class_data2} @print{} rsort: <100.0 95.6 93.4 87.1> @end example +Another example where indirect functions calls are useful can be found in +processing arrays. @DBREF{Walking Arrays} presented a simple function +for ``walking'' an array of arrays. That function simply printed the +name and value of each scalar array element. However, it is easy to +generalize that function, by passing in the name of a function to call +when walking an array. The modified function looks like this: + +@example +@c file eg/lib/processarray.awk +function process_array(arr, name, process, do_arrays, i, new_name) +@{ + for (i in arr) @{ + new_name = (name "[" i "]") + if (isarray(arr[i])) @{ + if (do_arrays) + @@process(new_name, arr[i]) + process_array(arr[i], new_name, process, do_arrays) + @} else + @@process(new_name, arr[i]) + @} +@} +@c endfile +@end example + +The arguments are as follows: + +@table @code +@item arr +The array. + +@item name +The name of the array (a string). + +@item process +The name of the function to call. + +@item do_arrays +If this is true, the function can handle elements that are subarrays. +@end table + +If subarrays are to be processed, that is done before walking them further. + +When run with the following scaffolding, the function produces the same +results as does the earlier @code{walk_array()} function: + +@example +BEGIN @{ + a[1] = 1 + a[2][1] = 21 + a[2][2] = 22 + a[3] = 3 + a[4][1][1] = 411 + a[4][2] = 42 + + process_array(a, "a", "do_print", 0) +@} + +function do_print(name, element) +@{ + printf "%s = %s\n", name, element +@} +@end example + Remember that you must supply a leading @samp{@@} in front of an indirect function call. -Unfortunately, indirect function calls cannot be used with the built-in functions. However, -you can generally write ``wrapper'' functions which call the built-in ones, and those can -be called indirectly. (Other than, perhaps, the mathematical functions, there is not a lot -of reason to try to call the built-in functions indirectly.) +Starting with @value{PVERSION} 4.1.2 of @command{gawk}, indirect function +calls may also be used with built-in functions and with extension functions +(@pxref{Dynamic Extensions}). The only thing you cannot do is pass a regular +expression constant to a built-in function through an indirect function +call.@footnote{This may change in a future version; recheck the documentation that +comes with your version of @command{gawk} to see if it has.} @command{gawk} does its best to make indirect function calls efficient. For example, in the following case: @@ -20080,7 +20347,7 @@ for (i = 1; i <= n; i++) @end example @noindent -@code{gawk} will look up the actual function to call only once. +@code{gawk} looks up the actual function to call only once. @node Functions Summary @section Summary @@ -20092,10 +20359,11 @@ functions. @item POSIX @command{awk} provides three kinds of built-in functions: numeric, -string, and I/O. @command{gawk} provides functions that work with values -representing time, do bit manipulation, sort arrays, and internationalize -and localize programs. @command{gawk} also provides several extensions to -some of standard functions, typically in the form of additional arguments. +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. +@command{gawk} also provides several extensions to some of standard +functions, typically in the form of additional arguments. @item Functions accept zero or more arguments and return a value. The @@ -20120,6 +20388,8 @@ from the real parameters by extra whitespace. User-defined functions may call other user-defined (and built-in) functions and may call themselves recursively. Function parameters ``hide'' any global variables of the same names. +You cannot use the name of a reserved variable (such as @code{ARGC}) +as the name of a parameter in user-defined functions. @item Scalar values are passed to user-defined functions by value. Array @@ -20138,7 +20408,7 @@ either scalar or array. @item @command{gawk} provides indirect function calls using a special syntax. -By setting a variable to the name of a user-defined function, you can +By setting a variable to the name of a function, you can determine at runtime what function will be called at that point in the program. This is equivalent to function pointers in C and C++. @@ -20173,7 +20443,7 @@ It contains the following chapters: @c STARTOFRANGE fudlib @cindex functions, user-defined, library of -@ref{User-defined}, describes how to write +@DBREF{User-defined} describes how to write your own @command{awk} functions. Writing functions is important, because it allows you to encapsulate algorithms and program tasks in a single place. It simplifies programming, making program development more @@ -20206,7 +20476,7 @@ use these functions. The functions are presented here in a progression from simple to complex. @cindex Texinfo -@ref{Extract Program}, +@DBREF{Extract Program} presents a program that you can use to extract the source code for these example library functions and programs from the Texinfo source for this @value{DOCUMENT}. @@ -20270,7 +20540,7 @@ comparisons use only lowercase letters. * Group Functions:: Functions for getting group information. * Walking Arrays:: A function to walk arrays of arrays. * Library Functions Summary:: Summary of library functions. -* Library exercises:: Exercises. +* Library Exercises:: Exercises. @end menu @node Library Names @@ -20330,7 +20600,7 @@ example, @code{getopt()}'s @code{Opterr} and @code{Optind} variables (@pxref{Getopt Function}). The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the variable is -not one of @command{awk}'s built-in variables, such as @code{FS}. +not one of @command{awk}'s predefined variables, such as @code{FS}. @cindex @option{--dump-variables} option, using for library functions It is also important that @emph{all} variables in library @@ -20344,8 +20614,9 @@ are very difficult to track down: function lib_func(x, y, l1, l2) @{ @dots{} - @var{use variable} some_var # some_var should be local - @dots{} # but is not by oversight + # some_var should be local but by oversight is not + @var{use variable} some_var + @dots{} @} @end example @@ -20357,7 +20628,7 @@ A different convention, common in the Tcl community, is to use a single associative array to hold the values needed by the library function(s), or ``package.'' This significantly decreases the number of actual global names in use. For example, the functions described in -@ref{Passwd Functions}, +@DBREF{Passwd Functions} might have used array elements @code{@w{PW_data["inited"]}}, @code{@w{PW_data["total"]}}, @code{@w{PW_data["count"]}}, and @code{@w{PW_data["awklib"]}}, instead of @code{@w{_pw_inited}}, @code{@w{_pw_awklib}}, @code{@w{_pw_total}}, @@ -20386,6 +20657,7 @@ programming use. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the shell. @end menu @node Strtonum Function @@ -20418,8 +20690,9 @@ function mystrtonum(str, ret, n, i, k, c) ret = 0 for (i = 1; i <= n; i++) @{ c = substr(str, i, 1) - if ((k = index("01234567", c)) > 0) - k-- # adjust for 1-basing in awk + # index() returns 0 if c not in string, + # includes c == "0" + k = index("1234567", c) ret = ret * 8 + k @} @@ -20431,6 +20704,8 @@ function mystrtonum(str, ret, n, i, k, c) for (i = 1; i <= n; i++) @{ c = substr(str, i, 1) c = tolower(c) + # index() returns 0 if c not in string, + # includes c == "0" k = index("123456789abcdef", c) ret = ret * 16 + k @@ -20453,7 +20728,7 @@ function mystrtonum(str, ret, n, i, k, c) # a[5] = "123.45" # a[6] = "1.e3" # a[7] = "1.32" -# a[7] = "1.32E2" +# a[8] = "1.32E2" # # for (i = 1; i in a; i++) # print a[i], strtonum(a[i]), mystrtonum(a[i]) @@ -20464,9 +20739,12 @@ function mystrtonum(str, ret, n, i, k, c) The function first looks for C-style octal numbers (base 8). If the input string matches a regular expression describing octal numbers, then @code{mystrtonum()} loops through each character in the -string. It sets @code{k} to the index in @code{"01234567"} of the current -octal digit. Since the return value is one-based, the @samp{k--} -adjusts @code{k} so it can be used in computing the return value. +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 +only octal values are converted. Similar logic applies to the code that checks for and converts a hexadecimal value, which starts with @samp{0x} or @samp{0X}. @@ -20499,7 +20777,7 @@ that a condition or set of conditions is true. Before proceeding with a particular computation, you make a statement about what you believe to be the case. Such a statement is known as an @dfn{assertion}. The C language provides an @code{<assert.h>} header file -and corresponding @code{assert()} macro that the programmer can use to make +and corresponding @code{assert()} macro that a programmer can use to make assertions. If an assertion fails, the @code{assert()} macro arranges to print a diagnostic message describing the condition that should have been true but was not, and then it kills the program. In C, using @@ -20832,8 +21110,7 @@ function chr(c) @c endfile #### test code #### -# BEGIN \ -# @{ +# BEGIN @{ # for (;;) @{ # printf("enter a character: ") # if (getline var <= 0) @@ -20918,7 +21195,7 @@ more difficult than they really need to be.} @cindex timestamps, formatted @cindex time, managing The @code{systime()} and @code{strftime()} functions described in -@ref{Time Functions}, +@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 formats are not necessarily easy to remember or intuitively obvious when @@ -20970,7 +21247,7 @@ function getlocaltime(time, ret, now, i) now = systime() # return date(1)-style output - ret = strftime(PROCINFO["strftime"], now) + ret = strftime("%a %b %e %H:%M:%S %Z %Y", now) # clear out target array delete time @@ -21004,7 +21281,7 @@ function getlocaltime(time, ret, now, i) The string indices are easier to use and read than the various formats required by @code{strftime()}. The @code{alarm} program presented in -@ref{Alarm Program}, +@DBREF{Alarm Program} uses this function. A more general design for the @code{getlocaltime()} function would have allowed the user to supply an optional timestamp value to use instead @@ -21085,6 +21362,87 @@ if (length(contents) == 0) This tests the result to see if it is empty or not. An equivalent test would be @samp{contents == ""}. +@xref{Extension Sample Readfile}, for an extension function that +also reads an entire file into memory. + +@node Shell Quoting +@subsection Quoting Strings to Pass to The Shell + +@c included by permission +@ignore +Date: Sun, 27 Jul 2014 17:16:16 -0700 +Message-ID: <CAKuGj+iCF_obaCLDUX60aSAgbfocFVtguG39GyeoNxTFby5sqQ@mail.gmail.com> +Subject: Useful awk function +From: Mike Brennan <mike@madronabluff.com> +To: Arnold Robbins <arnold@skeeve.com> +@end ignore + +Michael Brennan offers the following programming pattern, +which he uses frequently: + +@example +#! /bin/sh + +awkp=' + @dots{} + ' + +@var{input_program} | awk "$awkp" | /bin/sh +@end example + +For example, a program of his named @command{flac-edit} has this form: + +@example +$ @kbd{flac-edit -song="Whoope! That's Great" file.flac} +@end example + +It generates the following output, which is to be piped to +the shell (@file{/bin/sh}): + +@example +chmod +w file.flac +metaflac --remove-tag=TITLE file.flac +LANG=en_US.88591 metaflac --set-tag=TITLE='Whoope! That'"'"'s Great' file.flac +chmod -w file.flac +@end example + +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{"\"'\""}. + +@example +@c file eg/lib/shellquote.awk +# shell_quote --- quote an argument for passing to the shell +@c endfile +@ignore +@c file eg/lib/shellquote.awk +# +# Michael Brennan +# brennan@@madronabluff.com +# September 2014 +@c endfile +@end ignore +@c file eg/lib/shellquote.awk + +function shell_quote(s, # parameter + SINGLE, QSINGLE, i, X, n, ret) # locals +@{ + if (s == "") + return "\"\"" + + SINGLE = "\x27" # single quote + QSINGLE = "\"\x27\"" + n = split(s, X, SINGLE) + + ret = SINGLE X[1] SINGLE + for (i = 2; i <= n; i++) + ret = ret QSINGLE SINGLE X[i] SINGLE + + return ret +@} +@c endfile +@end example + @node Data File Management @section @value{DDF} Management @@ -21142,15 +21500,14 @@ Besides solving the problem in only nine(!) lines of code, it does so @c # Arnold Robbins, arnold@@skeeve.com, Public Domain @c # January 1992 -FILENAME != _oldfilename \ -@{ +FILENAME != _oldfilename @{ if (_oldfilename != "") endfile(_oldfilename) _oldfilename = FILENAME beginfile(FILENAME) @} -END @{ endfile(FILENAME) @} +END @{ endfile(FILENAME) @} @end example This file must be loaded before the user's ``main'' program, so that the @@ -21203,11 +21560,11 @@ FNR == 1 @{ beginfile(FILENAME) @} -END @{ endfile(_filename_) @} +END @{ endfile(_filename_) @} @c endfile @end example -@ref{Wc Program}, +@DBREF{Wc Program} shows how this library function can be used and how it simplifies writing the main program. @@ -21302,24 +21659,12 @@ function rewind( i) @c endfile @end example -This code relies on the @code{ARGIND} variable -(@pxref{Auto-set}), -which is specific to @command{gawk}. -If you are not using -@command{gawk}, you can use ideas presented in -@ifnotinfo -the previous @value{SECTION} -@end ifnotinfo -@ifinfo -@ref{Filetrans Function}, -@end ifinfo -to either update @code{ARGIND} on your own -or modify this code as appropriate. - -The @code{rewind()} function 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!) +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!) @node File Checking @subsection Checking for Readable @value{DDF}s @@ -21352,7 +21697,7 @@ the following program to your @command{awk} program: BEGIN @{ for (i = 1; i < ARGC; i++) @{ - if (ARGV[i] ~ /^[[:alpha:]_][[:alnum:]_]*=.*/ \ + if (ARGV[i] ~ /^[a-zA-Z_][a-zA-Z0-9_]*=.*/ \ || ARGV[i] == "-" || ARGV[i] == "/dev/stdin") continue # assignment or standard input else if ((getline junk < ARGV[i]) < 0) # unreadable @@ -21370,6 +21715,11 @@ Removing the element from @code{ARGV} with @code{delete} skips the file (since it's no longer in the list). See also @ref{ARGC and ARGV}. +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 @@ -21466,7 +21816,7 @@ a library file does the trick: function disable_assigns(argc, argv, i) @{ for (i = 1; i < argc; i++) - if (argv[i] ~ /^[[:alpha:]_][[:alnum:]_]*=.*/) + if (argv[i] ~ /^[a-zA-Z_][a-zA-Z0-9_]*=.*/) argv[i] = ("./" argv[i]) @} @@ -21707,8 +22057,7 @@ it is not an option, and it ends option processing. Continuing on: i = index(options, thisopt) if (i == 0) @{ if (Opterr) - printf("%c -- invalid option\n", - thisopt) > "/dev/stderr" + printf("%c -- invalid option\n", thisopt) > "/dev/stderr" if (_opti >= length(argv[Optind])) @{ Optind++ _opti = 0 @@ -21839,12 +22188,18 @@ In both runs, the first @option{--} terminates the arguments to etc., as its own options. @quotation NOTE -After @code{getopt()} is through, it is the responsibility of the -user level code to clear out all the elements of @code{ARGV} from 1 +After @code{getopt()} is through, +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 +further options +(@pxref{Executable Scripts}, and @pxref{Options}). + Several of the sample programs presented in @ref{Sample Programs}, use @code{getopt()} to process their arguments. @@ -22089,13 +22444,14 @@ The @code{BEGIN} rule sets a private variable to the directory where routine, we have chosen to put it in @file{/usr/local/libexec/awk}; however, you might want it to be in a different directory on your system. -The function @code{_pw_init()} keeps three copies of the user information -in three associative arrays. The arrays are indexed by username +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()} needs to be called only once. +@cindex @code{PROCINFO} array, testing the field splitting @cindex @code{getline} command, @code{_pw_init()} function 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}. @@ -22103,13 +22459,8 @@ 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 from anywhere within a user's program, and the user may have his -or her -own way of splitting records and fields. - -@cindex @code{PROCINFO} array, testing the field splitting -The @code{using_fw} variable checks @code{PROCINFO["FS"]}, which -is @code{"FIELDWIDTHS"} if field splitting is being done with -@code{FIELDWIDTHS}. This makes it possible to restore the correct +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 @command{gawk}. It is false if using @code{FS} or @code{FPAT}, or on some other @command{awk} implementation. @@ -22211,7 +22562,7 @@ once. If you are worried about squeezing every last cycle out of your this is not necessary, since most @command{awk} programs are I/O-bound, and such a change would clutter up the code. -The @command{id} program in @ref{Id Program}, +The @command{id} program in @DBREF{Id Program} uses these functions. @c ENDOFRANGE libfudata @c ENDOFRANGE flibudata @@ -22237,7 +22588,7 @@ uses these functions. @cindex group file @cindex files, group Much of the discussion presented in -@ref{Passwd Functions}, +@DBREF{Passwd Functions} applies to the group database as well. Although there has traditionally been a well-known file (@file{/etc/group}) in a well-known format, the POSIX standard only provides a set of C library routines @@ -22390,8 +22741,7 @@ There are several, modeled after the C library functions of the same names: @c line break on _gr_init for smallbook @c file eg/lib/groupawk.in -BEGIN \ -@{ +BEGIN @{ # Change to suit your system _gr_awklib = "/usr/local/libexec/awk/" @} @@ -22424,8 +22774,7 @@ function _gr_init( oldfs, oldrs, olddol0, grcat, n = split($4, a, "[ \t]*,[ \t]*") for (i = 1; i <= n; i++) if (a[i] in _gr_groupsbyuser) - _gr_groupsbyuser[a[i]] = \ - _gr_groupsbyuser[a[i]] " " $1 + _gr_groupsbyuser[a[i]] = gr_groupsbyuser[a[i]] " " $1 else _gr_groupsbyuser[a[i]] = $1 @@ -22577,13 +22926,13 @@ Most of the work is in scanning the database and building the various associative arrays. The functions that the user calls are themselves very simple, relying on @command{awk}'s associative arrays to do work. -The @command{id} program in @ref{Id Program}, +The @command{id} program in @DBREF{Id Program} uses these functions. @node Walking Arrays @section Traversing Arrays of Arrays -@ref{Arrays of Arrays}, described how @command{gawk} +@DBREF{Arrays of Arrays} described how @command{gawk} provides arrays of arrays. In particular, any element of an array may be either a scalar, or another array. The @code{isarray()} function (@pxref{Type Functions}) @@ -22633,12 +22982,12 @@ When run, the program produces the following output: @example $ @kbd{gawk -f walk_array.awk} -@print{} a[4][1][1] = 411 -@print{} a[4][2] = 42 @print{} a[1] = 1 @print{} a[2][1] = 21 @print{} a[2][2] = 22 @print{} a[3] = 3 +@print{} a[4][1][1] = 411 +@print{} a[4][2] = 42 @end example @c ENDOFRANGE libfgdata @@ -22652,8 +23001,8 @@ $ @kbd{gawk -f walk_array.awk} @itemize @value{BULLET} @item Reading programs is an excellent way to learn Good Programming. -The functions provided in this @value{CHAPTER} and the next are intended -to serve that purpose. +The functions and programs provided in this @value{CHAPTER} and the next +are intended to serve that purpose. @item When writing general-purpose library functions, put some thought into how @@ -22689,7 +23038,8 @@ A simple function to traverse an array of arrays to any depth. @end itemize -@node Library exercises +@c EXCLUDE START +@node Library Exercises @section Exercises @enumerate @@ -22737,7 +23087,7 @@ As a related challenge, revise that code to handle the case where an intervening value in @code{ARGV} is a variable assignment. @item -@ref{Walking Arrays}, presented a function that walked a multidimensional +@DBREF{Walking Arrays} presented a function that walked a multidimensional array to print it out. However, walking an array and processing each element is a general-purpose operation. Generalize the @code{walk_array()} function by adding an additional parameter named @@ -22755,6 +23105,7 @@ Test your new version by printing the array; you should end up with output identical to that of the original version. @end enumerate +@c EXCLUDE END @c ENDOFRANGE flib @c ENDOFRANGE fudlib @@ -22938,22 +23289,16 @@ supplied: # Requires getopt() and join() library functions @group -function usage( e1, e2) +function usage() @{ - e1 = "usage: cut [-f list] [-d c] [-s] [files...]" - e2 = "usage: cut [-c list] [files...]" - print e1 > "/dev/stderr" - print e2 > "/dev/stderr" + print("usage: cut [-f list] [-d c] [-s] [files...]") > "/dev/stderr" + print("usage: cut [-c list] [files...]") > "/dev/stderr" exit 1 @} @end group @c endfile @end example -@noindent -The variables @code{e1} and @code{e2} are used so that the function -fits nicely on the @value{PAGE}. - @cindex @code{BEGIN} pattern, running @command{awk} programs and @cindex @code{FS} variable, running @command{awk} programs and Next comes a @code{BEGIN} rule that parses the command-line options. @@ -22968,8 +23313,7 @@ string: @example @c file eg/prog/cut.awk -BEGIN \ -@{ +BEGIN @{ FS = "\t" # default OFS = FS while ((c = getopt(ARGC, ARGV, "sf:c:d:")) != -1) @{ @@ -23249,7 +23593,7 @@ and the file transition library program The program begins with a descriptive comment and then a @code{BEGIN} rule that processes the command-line arguments with @code{getopt()}. The @option{-i} (ignore case) option is particularly easy with @command{gawk}; we just use the -@code{IGNORECASE} built-in variable +@code{IGNORECASE} predefined variable (@pxref{Built-in Variables}): @cindex @code{egrep.awk} program @@ -23444,8 +23788,7 @@ there are no matches, the exit status is one; otherwise it is zero: @example @c file eg/prog/egrep.awk -END \ -@{ +END @{ exit (total == 0) @} @c endfile @@ -23456,30 +23799,15 @@ and then exits: @example @c file eg/prog/egrep.awk -function usage( e) +function usage() @{ - e = "Usage: egrep [-csvil] [-e pat] [files ...]" - e = e "\n\tegrep [-csvil] pat [files ...]" - print e > "/dev/stderr" + print("Usage: egrep [-csvil] [-e pat] [files ...]") > "/dev/stderr" + print("\n\tegrep [-csvil] pat [files ...]") > "/dev/stderr" exit 1 @} @c endfile @end example -The variable @code{e} is used so that the function fits nicely -on the printed page. - -@cindex @code{END} pattern, backslash continuation and -@cindex @code{\} (backslash), continuing lines and -@cindex backslash (@code{\}), continuing lines and -Just a note on programming style: you may have noticed that the @code{END} -rule uses backslash continuation, with the open brace on a line by -itself. This is so that it more closely resembles the way functions -are written. Many of the examples -in this @value{CHAPTER} -use this style. You can decide for yourself if you like writing -your @code{BEGIN} and @code{END} rules this way -or not. @c ENDOFRANGE regexps @c ENDOFRANGE sfregexp @c ENDOFRANGE fsregexp @@ -23537,6 +23865,7 @@ numbers: # May 1993 # Revised February 1996 # Revised May 2014 +# Revised September 2014 @c endfile @end ignore @@ -23546,8 +23875,7 @@ numbers: # egid=5(blat) groups=9(nine),2(two),1(one) @group -BEGIN \ -@{ +BEGIN @{ uid = PROCINFO["uid"] euid = PROCINFO["euid"] gid = PROCINFO["gid"] @@ -23556,26 +23884,22 @@ BEGIN \ printf("uid=%d", uid) pw = getpwuid(uid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (euid != uid) @{ printf(" euid=%d", euid) pw = getpwuid(euid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) @} printf(" gid=%d", gid) pw = getgrgid(gid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (egid != gid) @{ printf(" egid=%d", egid) pw = getgrgid(egid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) @} for (i = 1; ("group" i) in PROCINFO; i++) @{ @@ -23584,8 +23908,7 @@ BEGIN \ group = PROCINFO["group" i] printf("%d", group) pw = getgrgid(group) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (("group" (i+1)) in PROCINFO) printf(",") @} @@ -23595,8 +23918,10 @@ BEGIN \ function pr_first_field(str, a) @{ - split(str, a, ":") - printf("(%s)", a[1]) + if (str != "") @{ + split(str, a, ":") + printf("(%s)", a[1]) + @} @} @c endfile @end example @@ -23619,7 +23944,8 @@ tested, and the loop body never executes. The @code{pr_first_field()} function simply isolates out some code that is used repeatedly, making the whole program -slightly shorter and cleaner. +shorter and cleaner. In particular, moving the check for +the empty string into this function saves several lines of code. @c ENDOFRANGE id @@ -23746,24 +24072,25 @@ The @code{usage()} function simply prints an error message and exits: @example @c file eg/prog/split.awk -function usage( e) +function usage() @{ - e = "usage: split [-num] [file] [outname]" - print e > "/dev/stderr" + print("usage: split [-num] [file] [outname]") > "/dev/stderr" exit 1 @} @c endfile @end example -@noindent -The variable @code{e} is used so that the function -fits nicely on the @value{PAGE}. - This program is a bit sloppy; it relies on @command{awk} to automatically close the last file instead of doing it in an @code{END} rule. It also assumes that letters are contiguous in the character set, which isn't true for EBCDIC systems. +@ifset FOR_PRINT +You might want to consider how to eliminate the use of +@code{ord()} and @code{chr()}; this can be done in such a +way as to solve the EBCDIC issue as well. +@end ifset + @c ENDOFRANGE filspl @c ENDOFRANGE split @@ -23817,8 +24144,7 @@ Finally, @command{awk} is forced to read the standard input by setting @c endfile @end ignore @c file eg/prog/tee.awk -BEGIN \ -@{ +BEGIN @{ for (i = 1; i < ARGC; i++) copy[i] = ARGV[i] @@ -23880,8 +24206,7 @@ Finally, the @code{END} rule cleans up by closing all the output files: @example @c file eg/prog/tee.awk -END \ -@{ +END @{ for (i in copy) close(copy[i]) @} @@ -23913,10 +24238,10 @@ The options for @command{uniq} are: @table @code @item -d -Print only repeated lines. +Print only repeated (duplicated) lines. @item -u -Print only nonrepeated lines. +Print only nonrepeated (unique) lines. @item -c Count lines. This option overrides @option{-d} and @option{-u}. Both repeated @@ -23985,10 +24310,9 @@ standard output, @file{/dev/stdout}: @end ignore @c file eg/prog/uniq.awk -function usage( e) +function usage() @{ - e = "Usage: uniq [-udc [-n]] [+n] [ in [ out ]]" - print e > "/dev/stderr" + print("Usage: uniq [-udc [-n]] [+n] [ in [ out ]]") > "/dev/stderr" exit 1 @} @@ -23998,8 +24322,7 @@ function usage( e) # -n skip n fields # +n skip n characters, skip fields first -BEGIN \ -@{ +BEGIN @{ count = 1 outputfile = "/dev/stdout" opts = "udc0:1:2:3:4:5:6:7:8:9:" @@ -24011,7 +24334,7 @@ BEGIN \ else if (c == "c") do_count++ else if (index("0123456789", c) != 0) @{ - # getopt requires args to options + # getopt() requires args to options # this messes us up for things like -5 if (Optarg ~ /^[[:digit:]]+$/) fcount = (c Optarg) + 0 @@ -24043,22 +24366,20 @@ BEGIN \ @end example The following function, @code{are_equal()}, compares the current line, -@code{$0}, to the -previous line, @code{last}. It handles skipping fields and characters. -If no field count and no character count are specified, @code{are_equal()} -simply returns one or zero depending upon the result of a simple string -comparison of @code{last} and @code{$0}. Otherwise, things get more -complicated. -If fields have to be skipped, each line is broken into an array using -@code{split()} -(@pxref{String Functions}); -the desired fields are then joined back into a line using @code{join()}. -The joined lines are stored in @code{clast} and @code{cline}. -If no fields are skipped, @code{clast} and @code{cline} are set to -@code{last} and @code{$0}, respectively. -Finally, if characters are skipped, @code{substr()} is used to strip off the -leading @code{charcount} characters in @code{clast} and @code{cline}. The -two strings are then compared and @code{are_equal()} returns the result: +@code{$0}, to the previous line, @code{last}. It handles skipping fields +and characters. If no field count and no character count are specified, +@code{are_equal()} returns one or zero depending upon the result of a +simple string comparison of @code{last} and @code{$0}. + +Otherwise, things get more complicated. If fields have to be skipped, +each line is broken into an array using @code{split()} (@pxref{String +Functions}); the desired fields are then joined back into a line +using @code{join()}. The joined lines are stored in @code{clast} and +@code{cline}. If no fields are skipped, @code{clast} and @code{cline} +are set to @code{last} and @code{$0}, respectively. Finally, if +characters are skipped, @code{substr()} is used to strip off the leading +@code{charcount} characters in @code{clast} and @code{cline}. The two +strings are then compared and @code{are_equal()} returns the result: @example @c file eg/prog/uniq.awk @@ -24148,6 +24469,29 @@ END @{ @} @c endfile @end example + +@c FIXME: Include this? +@ignore +This program does not follow our recommended convention of naming +global variables with a leading capital letter. Doing that would +make the program a little easier to follow. +@end ignore + +@ifset FOR_PRINT +The logic for choosing which lines to print represents a @dfn{state +machine}, which is ``a device that can be in one of a set number of stable +conditions depending on its previous condition and on the present values +of its inputs.''@footnote{This is the definition returned from entering +@code{define: state machine} into Google.} +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 +suggestion. +@end ifset + + @c ENDOFRANGE prunt @c ENDOFRANGE tpul @c ENDOFRANGE uniq @@ -24178,7 +24522,7 @@ one or more input files. Its usage is as follows: If no files are specified on the command line, @command{wc} reads its standard input. If there are multiple files, it also prints total counts for all -the files. The options and their meanings are shown in the following list: +the files. The options and their meanings are as follows: @table @code @item -l @@ -24518,8 +24862,7 @@ Here is the program: @c file eg/prog/alarm.awk # usage: alarm time [ "message" [ count [ delay ] ] ] -BEGIN \ -@{ +BEGIN @{ # Initial argument sanity checking usage1 = "usage: alarm time ['message' [count [delay]]]" usage2 = sprintf("\t(%s) time ::= hh:mm", ARGV[1]) @@ -24660,8 +25003,8 @@ character of the ``to'' list is used for the remaining characters in the Once upon a time, @c early or mid-1989! -a user proposed that a transliteration function should -be added to @command{gawk}. +a user proposed adding a transliteration function +to @command{gawk}. @c Wishing to avoid gratuitous new features, @c at least theoretically The following program was written to @@ -24669,15 +25012,12 @@ prove that character transliteration could be done with a user-level function. This program is not as complete as the system @command{tr} utility but it does most of the job. -The @command{translate} program demonstrates one of the few weaknesses -of standard @command{awk}: dealing with individual characters is very -painful, requiring repeated use of the @code{substr()}, @code{index()}, -and @code{gsub()} built-in functions -(@pxref{String Functions}).@footnote{This -program was written before @command{gawk} acquired the ability to -split each character in a string into separate array elements.} -There are two functions. The first, @code{stranslate()}, takes three -arguments: +The @command{translate} program was written long before @command{gawk} +acquired the ability to split each character in a string into separate +array elements. Thus, it makes repeated use of the @code{substr()}, +@code{index()}, and @code{gsub()} built-in functions (@pxref{String +Functions}). There are two functions. The first, @code{stranslate()}, +takes three arguments: @table @code @item from @@ -24696,7 +25036,7 @@ loop goes through @code{from}, one character at a time. For each character in @code{from}, if the character appears in @code{target}, it is replaced with the corresponding @code{to} character. -The @code{translate()} function simply calls @code{stranslate()} using @code{$0} +The @code{translate()} function calls @code{stranslate()} using @code{$0} as the target. The main program sets two global variables, @code{FROM} and @code{TO}, from the command line, and then changes @code{ARGV} so that @command{awk} reads from the standard input. @@ -24782,6 +25122,12 @@ An obvious improvement to this program would be to set up the @code{t_ar} array only once, in a @code{BEGIN} rule. However, this assumes that the ``from'' and ``to'' lists will never change throughout the lifetime of the program. + +Another obvious improvement is to enable the use of ranges, +such as @samp{a-z}, as allowed by the @command{tr} utility. +Look at the code for @file{cut.awk} (@pxref{Cut Program}) +for inspiration. + @c ENDOFRANGE chtra @c ENDOFRANGE tr @@ -24825,7 +25171,7 @@ of lines on the page Most of the work is done in the @code{printpage()} function. The label lines are stored sequentially in the @code{line} array. But they have to print horizontally; @code{line[1]} next to @code{line[6]}, -@code{line[2]} next to @code{line[7]}, and so on. Two loops are used to +@code{line[2]} next to @code{line[7]}, and so on. Two loops accomplish this. The outer loop, controlled by @code{i}, steps through every 10 lines of data; this is each row of labels. The inner loop, controlled by @code{j}, goes through the lines within the row. @@ -24914,8 +25260,7 @@ function printpage( i, j) Count++ @} -END \ -@{ +END @{ printpage() @} @c endfile @@ -24940,7 +25285,7 @@ in a useful format. At first glance, a program like this would seem to do the job: @example -# Print list of word frequencies +# wordfreq-first-try.awk --- print list of word frequencies @{ for (i = 1; i <= NF; i++) @@ -25157,16 +25502,16 @@ Texinfo input file into separate files. This @value{DOCUMENT} is written in @uref{http://www.gnu.org/software/texinfo/, Texinfo}, the GNU project's document formatting language. A single Texinfo source file can be used to produce both -printed and online documentation. +printed documentation, with @TeX{}, and online documentation. @ifnotinfo -Texinfo is fully documented in the book +(Texinfo is fully documented in the book @cite{Texinfo---The GNU Documentation Format}, available from the Free Software Foundation, -and also available @uref{http://www.gnu.org/software/texinfo/manual/texinfo/, online}. +and also available @uref{http://www.gnu.org/software/texinfo/manual/texinfo/, online}.) @end ifnotinfo @ifinfo -The Texinfo language is described fully, starting with -@inforef{Top, , Texinfo, texinfo,Texinfo---The GNU Documentation Format}. +(The Texinfo language is described fully, starting with +@inforef{Top, , Texinfo, texinfo,Texinfo---The GNU Documentation Format}.) @end ifinfo For our purposes, it is enough to know three things about Texinfo input @@ -25244,8 +25589,7 @@ exits with a zero exit status, signifying OK: @cindex @code{extract.awk} program @example @c file eg/prog/extract.awk -# extract.awk --- extract files and run programs -# from texinfo files +# extract.awk --- extract files and run programs from texinfo files @c endfile @ignore @c file eg/prog/extract.awk @@ -25259,8 +25603,7 @@ exits with a zero exit status, signifying OK: BEGIN @{ IGNORECASE = 1 @} -/^@@c(omment)?[ \t]+system/ \ -@{ +/^@@c(omment)?[ \t]+system/ @{ if (NF < 3) @{ e = ("extract: " FILENAME ":" FNR) e = (e ": badly formed `system' line") @@ -25317,8 +25660,7 @@ line. That line is then printed to the output file: @example @c file eg/prog/extract.awk -/^@@c(omment)?[ \t]+file/ \ -@{ +/^@@c(omment)?[ \t]+file/ @{ if (NF != 3) @{ e = ("extract: " FILENAME ":" FNR ": badly formed `file' line") print e > "/dev/stderr" @@ -25378,7 +25720,7 @@ The @code{END} rule handles the final cleanup, closing the open file: function unexpected_eof() @{ printf("extract: %s:%d: unexpected EOF or error\n", - FILENAME, FNR) > "/dev/stderr" + FILENAME, FNR) > "/dev/stderr" exit 1 @} @end group @@ -25406,7 +25748,7 @@ While @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 -command1 < orig.data | sed 's/old/new/g' | command2 > result +@var{command1} < orig.data | sed 's/old/new/g' | @var{command2} > result @end example Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp @@ -25638,6 +25980,7 @@ should be the @command{awk} program. If there are no command-line arguments left, @command{igawk} prints an error message and exits. Otherwise, the first argument is appended to @code{program}. In any case, after the arguments have been processed, +the shell variable @code{program} contains the complete text of the original @command{awk} program. @@ -25760,8 +26103,8 @@ the path, and an attempt is made to open the generated @value{FN}. The only way to test if a file can be read in @command{awk} is to go ahead and try to read it with @code{getline}; this is what @code{pathto()} does.@footnote{On some very old versions of @command{awk}, the test -@samp{getline junk < t} can loop forever if the file exists but is empty. -Caveat emptor.} If the file can be read, it is closed and the @value{FN} +@samp{getline junk < t} can loop forever if the file exists but is empty.} +If the file can be read, it is closed and the @value{FN} is returned: @ignore @@ -25961,12 +26304,10 @@ in C or C++, and it is frequently easier to do certain kinds of string and argument manipulation using the shell than it is in @command{awk}. Finally, @command{igawk} shows that it is not always necessary to add new -features to a program; they can often be layered on top. -@ignore -With @command{igawk}, -there is no real reason to build @code{@@include} processing into -@command{gawk} itself. -@end ignore +features to a program; they can often be layered on top.@footnote{@command{gawk} +does @code{@@include} processing itself in order to support the use +of @command{awk} programs as Web CGI scripts.} + @c ENDOFRANGE libfex @c ENDOFRANGE flibex @c ENDOFRANGE awkpex @@ -25984,12 +26325,11 @@ One word is an anagram of another if both words contain the same letters (for example, ``babbling'' and ``blabbing''). -An elegant algorithm is presented in Column 2, Problem C of -Jon Bentley's @cite{Programming Pearls}, second edition. -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. +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 @@ -26223,7 +26563,7 @@ BEGIN { @itemize @value{BULLET} @item -The functions provided in this @value{CHAPTER} and the previous one +The programs provided in this @value{CHAPTER} continue on the theme that reading programs is an excellent way to learn Good Programming. @@ -26254,13 +26594,14 @@ mailing labels, and finding anagrams. @end itemize +@c EXCLUDE START @node Programs Exercises @section Exercises @enumerate @item Rewrite @file{cut.awk} (@pxref{Cut Program}) -using @code{split()} with @code{""} as the seperator. +using @code{split()} with @code{""} as the separator. @item In @ref{Egrep Program}, we mentioned that @samp{egrep -i} could be @@ -26277,17 +26618,27 @@ information is printed. Modify the @command{awk} version same way. @item -The @code{split.awk} program (@pxref{Split Program}) uses -the @code{chr()} and @code{ord()} functions to move through the -letters of the alphabet. -Modify the program to instead use only the @command{awk} -built-in functions, such as @code{index()} and @code{substr()}. - -@item The @code{split.awk} program (@pxref{Split Program}) assumes that letters are contiguous in the character set, which isn't true for EBCDIC systems. Fix this problem. +(Hint: Consider a different way to work through the alphabet, +without relying on @code{ord()} and @code{chr()}.) + +@item +In @file{uniq.awk} (@pxref{Uniq Program}, the +logic for choosing which lines to print represents a @dfn{state +machine}, which is ``a device that can be in one of a set number of stable +conditions depending on its previous condition and on the present values +of its inputs.''@footnote{This is the definition returned from entering +@code{define: state machine} into Google.} +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 +suggestion. + @item Why can't the @file{wc.awk} program (@pxref{Wc Program}) just @@ -26383,6 +26734,7 @@ Modify @file{anagram.awk} (@pxref{Anagram Program}), to avoid the use of the external @command{sort} utility. @end enumerate +@c EXCLUDE END @ifnotinfo @part @value{PART3}Moving Beyond Standard @command{awk} With @command{gawk} @@ -26488,13 +26840,11 @@ discusses the ability to dynamically add new built-in functions to @cindex constants, nondecimal If you run @command{gawk} with the @option{--non-decimal-data} option, -you can have nondecimal constants in your input data: +you can have nondecimal values in your input data: -@c line break here for small book format @example $ @kbd{echo 0123 123 0x123 |} -> @kbd{gawk --non-decimal-data '@{ printf "%d, %d, %d\n",} -> @kbd{$1, $2, $3 @}'} +> @kbd{gawk --non-decimal-data '@{ printf "%d, %d, %d\n", $1, $2, $3 @}'} @print{} 83, 123, 291 @end example @@ -26535,6 +26885,8 @@ Instead, use the @code{strtonum()} function to convert your data (@pxref{String Functions}). This makes your programs easier to write and easier to read, and leads to less surprising results. + +This option may disappear in a future version of @command{gawk}. @end quotation @node Array Sorting @@ -26564,12 +26916,14 @@ Often, though, it is desirable to be able to loop over the elements in a particular order that you, the programmer, choose. @command{gawk} lets you do this. -@ref{Controlling Scanning}, describes how you can assign special, +@DBREF{Controlling Scanning} describes how you can assign special, pre-defined values to @code{PROCINFO["sorted_in"]} in order to control the order in which @command{gawk} traverses an array during a @code{for} loop. -In addition, the value of @code{PROCINFO["sorted_in"]} can be a function name. +In addition, the value of @code{PROCINFO["sorted_in"]} can be a +function name.@footnote{This is why the predefined sorting orders +start with an @samp{@@} character, which cannot be part of an identifier.} This lets you traverse an array based on any custom criterion. The array elements are ordered according to the return value of this function. The comparison function should be defined with at least @@ -26701,7 +27055,7 @@ according to login name. The following program sorts records by a specific field position and can be used for this purpose: @example -# sort.awk --- simple program to sort by field position +# passwd-sort.awk --- simple program to sort by field position # field position is specified by the global variable POS function cmp_field(i1, v1, i2, v2) @@ -26760,7 +27114,7 @@ As mentioned above, 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 -may change during the next loop traversal, if other elements are added or +may change the next time the array is traversed, if other elements are added or removed from the array. One way to resolve ties when comparing elements with otherwise equal values is to include the indices in the comparison rules. Note that doing this may make the loop traversal less efficient, @@ -26929,7 +27283,6 @@ 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 @command{gawk} extensions, they are not available in that case.} -Caveat Emptor. @node Two-way I/O @section Two-Way Communications with Another Process @@ -26995,7 +27348,7 @@ for example, @file{/tmp} will not do, as another user might happen to be using a temporary file with the same name.@footnote{Michael Brennan suggests the use of @command{rand()} to generate unique @value{FN}s. This is a valid point; nevertheless, temporary files -remain more difficult than two-way pipes.} @c 8/2014 +remain more difficult to use than two-way pipes.} @c 8/2014 @cindex coprocesses @cindex input/output, two-way @@ -27132,13 +27485,27 @@ using regular pipes. @cindex @code{/inet6/@dots{}} special files (@command{gawk}) @cindex files, @code{/inet6/@dots{}} (@command{gawk}) @cindex @code{EMISTERED} +@ifnotdocbook @quotation -@code{EMISTERED}:@* +@code{EMRED}:@* @ @ @ @ @i{A host is a host from coast to coast,@* -@ @ @ @ and no-one can talk to host that's close,@* +@ @ @ @ and nobody talks to a host that's close,@* @ @ @ @ unless the host that isn't close@* -@ @ @ @ is busy hung or dead.} +@ @ @ @ is busy, hung, or dead.} +@author Mike O'Brien (aka Mr.@: Protocol) @end quotation +@end ifnotdocbook + +@docbook +<blockquote> +<attribution>Mike O'Brien (aka Mr. Protocol)</attribution> +<literallayout class="normal"><literal>EMISTERED</literal>: + <emphasis>A host is a host from coast to coast,</emphasis> + <emphasis>and no-one can talk to host that's close,</emphasis> + <emphasis>unless the host that isn't close</emphasis> + <emphasis>is busy, hung, or dead.</emphasis></literallayout> +</blockquote> +@end docbook In addition to being able to open a two-way pipeline to a coprocess on the same system @@ -27167,7 +27534,7 @@ the system default, most likely IPv4. @item protocol The protocol to use over IP. This must be either @samp{tcp}, or @samp{udp}, for a TCP or UDP IP connection, -respectively. The use of TCP is recommended for most applications. +respectively. TCP should be used for most applications. @item local-port @cindex @code{getaddrinfo()} function (C library) @@ -27200,10 +27567,10 @@ Consider the following very simple example: @example BEGIN @{ - Service = "/inet/tcp/0/localhost/daytime" - Service |& getline - print $0 - close(Service) + Service = "/inet/tcp/0/localhost/daytime" + Service |& getline + print $0 + close(Service) @} @end example @@ -27306,9 +27673,9 @@ in the morning to work.) @cindex @code{BEGIN} pattern, and profiling @cindex @code{END} pattern, and profiling @example - # gawk profile, created Thu Feb 27 05:16:21 2014 + # gawk profile, created Mon Sep 29 05:16:21 2014 - # BEGIN block(s) + # BEGIN rule(s) BEGIN @{ 1 print "First BEGIN rule" @@ -27335,7 +27702,7 @@ in the morning to work.) @} @} - # END block(s) + # END rule(s) END @{ 1 print "First END rule" @@ -27463,7 +27830,7 @@ come out as: @end example @noindent -which is correct, but possibly surprising. +which is correct, but possibly unexpected. @cindex profiling @command{awk} programs, dynamically @cindex @command{gawk} program, dynamic profiling @@ -27495,7 +27862,7 @@ $ @kbd{kill -USR1 13992} @noindent As usual, the profiled version of the program is written to -@file{awkprof.out}, or to a different file if one specified with +@file{awkprof.out}, or to a different file if one was specified with the @option{--profile} option. Along with the regular profile, as shown earlier, the profile file @@ -27555,6 +27922,7 @@ The @option{--non-decimal-data} option causes @command{gawk} to treat octal- and hexadecimal-looking input data as octal and hexadecimal. This option should be used with caution or not at all; use of @code{strtonum()} is preferable. +Note that this option may disappear in a future version of @command{gawk}. @item You can take over complete control of sorting in @samp{for (@var{indx} in @var{array})} @@ -27568,15 +27936,15 @@ those functions sort arrays. Or you may provide one of the predefined control strings that work for @code{PROCINFO["sorted_in"]}. @item -You can use the @samp{|&} operator to create a two-way pipe to a co-process. -You read from the co-process with @code{getline} and write to it with @code{print} -or @code{printf}. Use @code{close()} to close off the co-process completely, or +You can use the @samp{|&} operator to create a two-way pipe to a coprocess. +You read from the coprocess with @code{getline} and write to it with @code{print} +or @code{printf}. Use @code{close()} to close off the coprocess completely, or optionally, close off one side of the two-way communications. @item -By using special ``@value{FN}s'' with the @samp{|&} operator, you can open a +By using special @value{FN}s with the @samp{|&} operator, you can open a TCP/IP (or UDP/IP) connection to remote hosts in the Internet. @command{gawk} -supports both IPv4 an IPv6. +supports both IPv4 and IPv6. @item You can generate statement count profiles of your program. This can help you @@ -27814,7 +28182,7 @@ In June 2001 Bruno Haible wrote: This information is accessed via the POSIX character classes in regular expressions, such as @code{/[[:alnum:]]/} -(@pxref{Regexp Operators}). +(@pxref{Bracket Expressions}). @cindex monetary information, localization @cindex currency symbols, localization @@ -27897,7 +28265,7 @@ default arguments. Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @var{domain} for locale category @var{category}. @var{string1} is the -English singular variant of a message, and @var{string2} the English plural +English singular variant of a message, and @var{string2} is the English plural variant of the same message. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. The default value for @var{category} is @code{"LC_MESSAGES"}. @@ -27985,9 +28353,11 @@ This example would be better done with @code{dcngettext()}: @example if (groggy) - message = dcngettext("%d customer disturbing me\n", "%d customers disturbing me\n", "adminprog") + message = dcngettext("%d customer disturbing me\n", + "%d customers disturbing me\n", "adminprog") else - message = dcngettext("enjoying %d customer\n", "enjoying %d customers\n", "adminprog") + message = dcngettext("enjoying %d customer\n", + "enjoying %d customers\n", "adminprog") printf(message, ncustomers) @end example @@ -28059,7 +28429,7 @@ First, use the @option{--gen-pot} command-line option to create the initial @file{.pot} file: @example -$ @kbd{gawk --gen-pot -f guide.awk > guide.pot} +gawk --gen-pot -f guide.awk > guide.pot @end example @cindex @code{xgettext} utility @@ -28123,11 +28493,11 @@ example, @samp{string} is the first argument and @samp{length(string)} is the se @example $ @kbd{gawk 'BEGIN @{} -> @kbd{string = "Dont Panic"} +> @kbd{string = "Don\47t Panic"} > @kbd{printf "%2$d characters live in \"%1$s\"\n",} > @kbd{string, length(string)} > @kbd{@}'} -@print{} 10 characters live in "Dont Panic" +@print{} 11 characters live in "Don't Panic" @end example If present, positional specifiers come first in the format specification, @@ -28339,7 +28709,8 @@ msgstr "Like, the scoop is" @cindex GNU/Linux 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. +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. 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: @@ -28360,8 +28731,8 @@ $ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES} The @command{msgfmt} utility does the conversion from human-readable @file{.po} file to machine-readable @file{.mo} file. By default, @command{msgfmt} creates a file named @file{messages}. -This file must be renamed and placed in the proper directory so that -@command{gawk} can find it: +This file must be renamed and placed in the proper directory (using +the @option{-o} option) so that @command{gawk} can find it: @example $ @kbd{msgfmt guide-mellow.po -o en_US.UTF-8/LC_MESSAGES/guide.mo} @@ -28404,8 +28775,8 @@ complete detail in @cite{GNU gettext tools}}.) @end ifnotinfo As of this writing, the latest version of GNU @command{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.1.tar.gz, -@value{PVERSION} 0.19.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.2.tar.gz, +@value{PVERSION} 0.19.2}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -28493,7 +28864,7 @@ the discussion of debugging in @command{gawk}. @subsection Debugging in General (If you have used debuggers in other languages, you may want to skip -ahead to the next section on the specific features of the @command{awk} +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 @@ -28533,7 +28904,7 @@ is going wrong (or, for that matter, to better comprehend a perfectly functional program that you or someone else wrote). @node Debugging Terms -@subsection Additional Debugging Concepts +@subsection Debugging Concepts Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. @@ -28622,8 +28993,8 @@ as our example. @cindex starting the debugger @cindex debugger, how to start -Starting the debugger is almost exactly like running @command{gawk}, -except you have to pass an additional option @option{--debug} or the +Starting the debugger is almost exactly like running @command{gawk} normally, +except you have to pass an additional option @option{--debug}, or the corresponding short option @option{-D}. The file(s) containing the program and any supporting code are given on the command line as arguments to one or more @option{-f} options. (@command{gawk} is not designed @@ -28631,7 +29002,7 @@ to debug command-line programs, only programs contained in files.) In our case, we invoke the debugger like this: @example -$ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk inputfile} +$ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk -1 inputfile} @end example @noindent @@ -28641,6 +29012,7 @@ this syntax is slightly different from what they are used to. With the @command{gawk} debugger, you give the arguments for running the program in the command line to the debugger rather than as part of the @code{run} command at the debugger prompt.) +The @option{-1} is an option to @file{uniq.awk}. Instead of immediately running the program on @file{inputfile}, as @command{gawk} would ordinarily do, the debugger merely loads all @@ -28693,7 +29065,7 @@ the breakpoint, use the @code{b} (breakpoint) command: @example gawk> @kbd{b are_equal} -@print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 64 +@print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 63 @end example The debugger tells us the file and line number where the breakpoint is. @@ -28705,8 +29077,8 @@ gawk> @kbd{r} @print{} Starting program: @print{} Stopping in Rule ... @print{} Breakpoint 1, are_equal(n, m, clast, cline, alast, aline) - at `awklib/eg/prog/uniq.awk':64 -@print{} 64 if (fcount == 0 && charcount == 0) + at `awklib/eg/prog/uniq.awk':63 +@print{} 63 if (fcount == 0 && charcount == 0) gawk> @end example @@ -28718,12 +29090,12 @@ listing of the current stack frames: @example gawk> @kbd{bt} @print{} #0 are_equal(n, m, clast, cline, alast, aline) - at `awklib/eg/prog/uniq.awk':69 -@print{} #1 in main() at `awklib/eg/prog/uniq.awk':89 + at `awklib/eg/prog/uniq.awk':68 +@print{} #1 in main() at `awklib/eg/prog/uniq.awk':88 @end example This tells us that @code{are_equal()} was called by the main program at -line 89 of @file{uniq.awk}. (This is not a big surprise, since this +line 88 of @file{uniq.awk}. (This is not a big surprise, since 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.) @@ -28747,7 +29119,7 @@ A more useful variable to display might be the current record: @example gawk> @kbd{p $0} -@print{} $0 = string ("gawk is a wonderful program!") +@print{} $0 = "gawk is a wonderful program!" @end example @noindent @@ -28756,7 +29128,7 @@ our test input above. Let's look at @code{NR}: @example gawk> @kbd{p NR} -@print{} NR = number (2) +@print{} NR = 2 @end example @noindent @@ -28775,7 +29147,7 @@ OK, let's just check that that rule worked correctly: @example gawk> @kbd{p last} -@print{} last = string ("awk is a wonderful program!") +@print{} last = "awk is a wonderful program!" @end example Everything we have done so far has verified that the program has worked as @@ -28786,13 +29158,13 @@ be inside this function. To investigate further, we must begin @example gawk> @kbd{n} -@print{} 67 if (fcount > 0) @{ +@print{} 66 if (fcount > 0) @{ @end example -This tells us that @command{gawk} is now ready to execute line 67, which +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{-f} command-line option. (Notice that we skipped -from where we were before at line 64 to here, since the condition in line 64 +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 @samp{if (fcount == 0 && charcount == 0)} was false.) Continuing to step, we now get to the splitting of the current and @@ -28800,9 +29172,9 @@ last records: @example gawk> @kbd{n} -@print{} 68 n = split(last, alast) +@print{} 67 n = split(last, alast) gawk> @kbd{n} -@print{} 69 m = split($0, aline) +@print{} 68 m = split($0, aline) @end example At this point, we should be curious to see what our records were split @@ -28810,10 +29182,10 @@ into, so we try to look: @example gawk> @kbd{p n m alast aline} -@print{} n = number (5) -@print{} m = number (5) +@print{} n = 5 +@print{} m = untyped variable @print{} alast = array, 5 elements -@print{} aline = array, 5 elements +@print{} aline = untyped variable @end example @noindent @@ -28821,7 +29193,9 @@ gawk> @kbd{p n m alast aline} @command{awk}'s @code{print} statement.) This is kind of disappointing, though. All we found out is that there -are five elements in each of our arrays. Useful enough (we now know that +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. +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? @@ -28837,7 +29211,7 @@ Oops! @example gawk> @kbd{p alast[1]} -@print{} alast["1"] = string ("awk") +@print{} alast["1"] = "awk" @end example This would be kind of slow for a 100-member array, though, so @@ -28846,11 +29220,11 @@ not to be mentioned): @example gawk> @kbd{p @@alast} -@print{} alast["1"] = string ("awk") -@print{} alast["2"] = string ("is") -@print{} alast["3"] = string ("a") -@print{} alast["4"] = string ("wonderful") -@print{} alast["5"] = string ("program!") +@print{} alast["1"] = "awk" +@print{} alast["2"] = "is" +@print{} alast["3"] = "a" +@print{} alast["4"] = "wonderful" +@print{} alast["5"] = "program!" @end example It looks like we got this far OK. Let's take another step @@ -28858,9 +29232,9 @@ or two: @example gawk> @kbd{n} -@print{} 70 clast = join(alast, fcount, n) +@print{} 69 clast = join(alast, fcount, n) gawk> @kbd{n} -@print{} 71 cline = join(aline, fcount, m) +@print{} 70 cline = join(aline, fcount, m) @end example Well, here we are at our error (sorry to spoil the suspense). What we @@ -28870,8 +29244,8 @@ this would work. Let's look at what we've got: @example gawk> @kbd{p cline clast} -@print{} cline = string ("gawk is a wonderful program!") -@print{} clast = string ("awk is a wonderful program!") +@print{} cline = "gawk is a wonderful program!" +@print{} clast = "awk is a wonderful program!" @end example Hey, those look pretty familiar! They're just our original, unaltered, @@ -29013,7 +29387,8 @@ Delete breakpoint(s) set at entry to function @var{function}. @cindex breakpoint condition @item @code{condition} @var{n} @code{"@var{expression}"} Add a condition to existing breakpoint or watchpoint @var{n}. The -condition is an @command{awk} expression that the debugger evaluates +condition is an @command{awk} expression @emph{enclosed in double quotes} +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 @@ -29201,7 +29576,7 @@ see the output shown under @code{dump} in @ref{Miscellaneous Debugger Commands}. @item @code{until} [[@var{filename}@code{:}]@var{n} | @var{function}] @itemx @code{u} [[@var{filename}@code{:}]@var{n} | @var{function}] Without any argument, continue execution until a line past the current -line in current stack frame is reached. With an argument, +line in the current stack frame is reached. With an argument, continue execution until the specified location is reached, or the current stack frame returns. @end table @@ -29265,7 +29640,7 @@ gawk> @kbd{print $3} @noindent This prints the third field in the input record (if the specified field does not exist, it prints @samp{Null field}). A variable can be an array element, with -the subscripts being constant values. To print the contents of an array, +the subscripts being constant string values. To print the contents of an array, prefix the name of the array with the @samp{@@} symbol: @example @@ -29331,7 +29706,7 @@ watch list. @end table @node Execution Stack -@subsection Dealing with the Stack +@subsection Working with the Stack Whenever you run a program which contains any function calls, @command{gawk} maintains a stack of all of the function calls leading up @@ -29342,16 +29717,22 @@ functions which called the one you are in. The commands for doing this are: @table @asis @cindex debugger commands, @code{bt} (@code{backtrace}) @cindex debugger commands, @code{backtrace} +@cindex debugger commands, @code{where} (@code{backtrace}) @cindex @code{backtrace} debugger command @cindex @code{bt} debugger command (alias for @code{backtrace}) +@cindex @code{where} debugger command +@cindex @code{where} debugger command (alias for @code{backtrace}) @cindex call stack, display in debugger @cindex traceback, display in debugger @item @code{backtrace} [@var{count}] @itemx @code{bt} [@var{count}] +@itemx @code{where} [@var{count}] 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 +GDB users who may be used to that command. @cindex debugger commands, @code{down} @cindex @code{down} debugger command @@ -29401,7 +29782,7 @@ The value for @var{what} should be one of the following: @table @code @item args @cindex show function arguments, in debugger -Arguments of the selected frame. +List arguments of the selected frame. @item break @cindex show breakpoints @@ -29413,7 +29794,7 @@ List all items in the automatic display list. @item frame @cindex describe call stack frame, in debugger -Description of the selected stack frame. +Give a description of the selected stack frame. @item functions @cindex list function definitions, in debugger @@ -29422,11 +29803,11 @@ line numbers. @item locals @cindex show local variables, in debugger -Local variables of the selected frame. +List local variables of the selected frame. @item source @cindex show name of current source file, in debugger -The name of the current source file. Each time the program stops, the +Print the name of the current source file. Each time the program stops, the current source file is the file containing the current instruction. When the debugger first starts, the current source file is the first file included via the @option{-f} option. The @@ -29543,6 +29924,7 @@ commands in a program. This can be very enlightening, as the following partial dump of Davide Brini's obfuscated code (@pxref{Signature Program}) demonstrates: +@c FIXME: This will need updating if num-handler branch is ever merged in. @smallexample gawk> @kbd{dump} @print{} # BEGIN @@ -29616,7 +29998,7 @@ are as follows: @c nested table @table @asis -@item @code{-} +@item @code{-} (Minus) Print lines before the lines last printed. @item @code{+} @@ -29704,7 +30086,7 @@ and @end table @node Limitations -@section Limitations and Future Plans +@section Limitations We hope you find the @command{gawk} debugger useful and enjoyable to work with, but as with any program, especially in its early releases, it still has @@ -29718,7 +30100,9 @@ responds @samp{syntax error}. When you do figure out what your mistake was, though, you'll feel like a real guru. @item -If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands}, +@c NOTE: no comma after the ref{} on purpose, due to following +@c parenthetical remark. +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. @@ -29750,8 +30134,10 @@ executing, short programs. The @command{gawk} debugger only accepts source supplied with the @option{-f} option. @end itemize +@ignore Look forward to a future release when these and other missing features may be added, and of course feel free to try to add them yourself! +@end ignore @node Debugging Summary @section Summary @@ -29794,9 +30180,8 @@ and editing. @cindex floating-point, numbers@comma{} arbitrary precision This @value{CHAPTER} introduces some basic concepts relating to -how computers do arithmetic and briefly lists the features in -@command{gawk} for performing arbitrary precision floating point -computations. It then proceeds to describe floating-point arithmetic, +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 a feature available only in @command{gawk}. It continues on to present @@ -29891,10 +30276,12 @@ 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 the following table. +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} @multitable @columnfractions .34 .33 .33 -@headitem Numeric representation @tab Miniumum value @tab Maximum value +@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 @@ -29902,6 +30289,7 @@ signed. The possible ranges of values are shown in the following table. @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 @@ -29929,14 +30317,12 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.''@footnote{Thanks -to Michael Brennan for this description, which I have paraphrased, and -for the examples}. -A special value that results from attempting a -calculation that has no answer as a real number. In such a case, -programs can either receive a floating-point exception, or get @code{NaN} -back as the result. The IEEE 754 standard recommends that systems return -@code{NaN}. Some examples: +``Not A Number.''@footnote{Thanks to Michael Brennan for this description, +which we have paraphrased, and for the examples.} A special value that +results from attempting a calculation that has no answer as a real number. +In such a case, programs can either receive a floating-point exception, +or get @code{NaN} back as the result. The IEEE 754 standard recommends +that systems return @code{NaN}. Some examples: @table @code @item sqrt(-1) @@ -30010,9 +30396,9 @@ to allow greater precisions and larger exponent ranges. field values for the basic IEEE 754 binary formats: @float Table,table-ieee-formats -@caption{Basic IEEE Format Context Values} +@caption{Basic IEEE Format Values} @multitable @columnfractions .20 .20 .20 .20 .20 -@headitem Name @tab Total bits @tab Precision @tab emin @tab emax +@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 Double @tab 64 @tab 53 @tab @minus{}1022 @tab +1023 @item Quadruple @tab 128 @tab 113 @tab @minus{}16382 @tab +16383 @@ -30025,18 +30411,18 @@ one extra bit of significand. @end quotation @node MPFR features -@section Arbitrary Precison 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, @command{gawk} uses the @uref{http://www.mpfr.org, GNU -MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for arbitrary +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} -@print{} GNU Awk 4.1.1, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) +@print{} GNU Awk 4.1.2, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) @print{} Copyright (C) 1989, 1991-2014 Free Software Foundation. @dots{} @end example @@ -30056,17 +30442,18 @@ results. With the @option{-M} command-line option, all floating-point arithmetic operators and numeric functions can yield results to any desired precision level supported by MPFR. -Two built-in variables, @code{PREC} and @code{ROUNDMODE}, +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{Auto-set}, for more information. +@xref{Setting precision}, and @ref{Setting the rounding mode}, +for more information. @node FP Math Caution @section Floating Point Arithmetic: Caveat Emptor! @quotation -Math class is tough! +@i{Math class is tough!} @author Teen Talk Barbie, July 1992 @end quotation @@ -30174,6 +30561,10 @@ else # not ok @end example +@noindent +(We assume that you have a simple absolute value function named +@code{abs()} defined elsewhere in your program.) + @node Errors accumulate @subsubsection Errors Accumulate @@ -30260,7 +30651,7 @@ 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 -computations with a particular precision and effective rounding rule, +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. @@ -30327,7 +30718,7 @@ $ @kbd{gawk -f pi2.awk} the precision or accuracy of individual numbers. Performing an arithmetic operation or calling a built-in function rounds the result to the current working precision. The default working precision is 53 bits, which you can -modify using the built-in variable @code{PREC}. You can also set the +modify using the predefined variable @code{PREC}. You can also set the value to one of the predefined case-insensitive strings shown in @ref{table-predefined-precision-strings}, to emulate an IEEE 754 binary format. @@ -30359,7 +30750,7 @@ Be wary of floating-point constants! When reading a floating-point constant from program source code, @command{gawk} uses the default precision (that of a C @code{double}), unless overridden by an assignment to the special variable @code{PREC} on the command line, to store it -internally as a MPFR number. Changing the precision using @code{PREC} +internally as an MPFR number. Changing the precision using @code{PREC} in the program text does @emph{not} change the precision of a constant. If you need to represent a floating-point constant at a higher precision @@ -30497,15 +30888,15 @@ 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 @{} > @kbd{x = 5^4^3^2} -> @kbd{print "# of digits =", length(x)} +> @kbd{print "number of digits =", length(x)} > @kbd{print substr(x, 1, 20), "...", substr(x, length(x) - 19, 20)} > @kbd{@}'} -@print{} # of digits = 183231 +@print{} number of digits = 183231 @print{} 62060698786608744707 ... 92256259918212890625 @end example @@ -30607,7 +30998,7 @@ using this user-defined function: @end ignore @c file eg/lib/div.awk -function div(numerator, denominator, result, i) +function div(numerator, denominator, result) @{ split("", result) @@ -30621,6 +31012,80 @@ function div(numerator, denominator, result, i) @c endfile @end example +The following example program, contributed by Katie Wasserman, +uses @code{div()} to +compute the digits of @value{PI} to as many places as you +choose to set: + +@example +@c file eg/prog/pi.awk +# pi.awk --- compute the digits of pi +@c endfile +@c endfile +@ignore +@c file eg/prog/pi.awk +# +# Katie Wasserman, katie@@wass.net +# August 2014 +@c endfile +@end ignore +@c file eg/prog/pi.awk + +BEGIN @{ + digits = 100000 + two = 2 * 10 ^ digits + pi = two + for (m = digits * 4; m > 0; --m) @{ + d = m * 2 + 1 + x = pi * m + div(x, d, result) + pi = result["quotient"] + pi = pi + two + @} + print pi +@} +@c endfile +@end example + +@ignore +Date: Wed, 20 Aug 2014 10:19:11 -0400 +To: arnold@skeeve.com +From: Katherine Wasserman <katie@wass.net> +Subject: Re: computation of digits of pi? + +Arnold, + +>The program that you sent to compute the digits of pi using div(). Is +>that some standard algorithm that every math student knows? If so, +>what's it called? + +It's not that well known but it's not that obscure either + +It's Euler's modification to Newton's method for calculating pi. + +Take a look at lines (23) - (25) here: http://mathworld.wolfram.com/PiFormulas.htm + +The algorithm I wrote simply expands the multiply by 2 and works from the innermost expression outwards. I used this to program HP calculators because it's quite easy to modify for tiny memory devices with smallish word sizes. + +http://www.hpmuseum.org/cgi-sys/cgiwrap/hpmuseum/articles.cgi?read=899 + +-Katie +@end ignore + +When asked about the algorithm used, Katie replied: + +@quotation +It's not that well known but it's not that obscure either. +It's Euler's modification to Newton's method for calculating pi. +Take a look at lines (23) - (25) here: @uref{http://mathworld.wolfram.com/PiFormulas.htm}. + +The algorithm I wrote simply expands the multiply by 2 and works from +the innermost expression outwards. I used this to program HP calculators +because it's quite easy to modify for tiny memory devices with smallish +word sizes. See +@uref{http://www.hpmuseum.org/cgi-sys/cgiwrap/hpmuseum/articles.cgi?read=899}. +@end quotation + @node POSIX Floating Point Problems @section Standards Versus Existing Practice @@ -30728,7 +31193,7 @@ 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. The default for @command{awk} is to use double-precision +values. Standard @command{awk} uses double precision floating-point values. @item @@ -30847,7 +31312,7 @@ 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 sample extension. In addition, it documents +them, and presents a small example extension. In addition, it documents the sample extensions included in the @command{gawk} distribution, and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @@ -30863,10 +31328,14 @@ goals and design. @node Plugin License @section Extension Licensing -Every dynamic extension should define the global symbol -@code{plugin_is_GPL_compatible} to assert that it has been licensed under -a GPL-compatible license. If this symbol does not exist, @command{gawk} -emits a fatal error and exits when it tries to load your extension. +Every dynamic extension must be distributed under a license that is +compatible with the GNU GPL (@pxref{Copying}). + +In order for the extension to tell @command{gawk} that it is +properly licensed, the extension must define the global symbol +@code{plugin_is_GPL_compatible}. If this symbol does not exist, +@command{gawk} emits a fatal error and exits when it tries to load +your extension. The declared type of the symbol should be @code{int}. It does not need to be in any allocated section, though. The code merely asserts that @@ -30881,7 +31350,7 @@ int plugin_is_GPL_compatible; Communication between @command{gawk} and an extension is two-way. First, when an extension -is loaded, it is passed a pointer to a @code{struct} whose fields are +is loaded, @command{gawk} passes it a pointer to a @code{struct} whose fields are function pointers. @ifnotdocbook This is shown in @ref{figure-load-extension}. @@ -30917,29 +31386,29 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-load-extension"/>}. The extension can call functions inside @command{gawk} through these function pointers, at runtime, without needing (link-time) access to @command{gawk}'s symbols. One of these function pointers is to a -function for ``registering'' new built-in functions. +function for ``registering'' new functions. @ifnotdocbook -This is shown in @ref{figure-load-new-function}. +This is shown in @ref{figure-register-new-function}. @end ifnotdocbook @ifdocbook -This is shown in @inlineraw{docbook, <xref linkend="figure-load-new-function"/>}. +This is shown in @inlineraw{docbook, <xref linkend="figure-register-new-function"/>}. @end ifdocbook @ifnotdocbook -@float Figure,figure-load-new-function -@caption{Loading The New Function} +@float Figure,figure-register-new-function +@caption{Registering A New Function} @ifinfo -@center @image{api-figure2, , , Loading The New Function, txt} +@center @image{api-figure2, , , Registering A New Function, txt} @end ifinfo @ifnotinfo -@center @image{api-figure2, , , Loading The New Function} +@center @image{api-figure2, , , Registering A New Function} @end ifnotinfo @end float @end ifnotdocbook @docbook -<figure id="figure-load-new-function" float="0"> -<title>Loading The New Function</title> +<figure id="figure-register-new-function" float="0"> +<title>Registering A New Function</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure2.png" format="PNG"/></imageobject> </mediaobject> @@ -30989,8 +31458,8 @@ and understandable. Although all of this sounds somewhat complicated, the result is that extension code is quite straightforward to write and to read. You can -see this in the sample extensions @file{filefuncs.c} (@pxref{Extension -Example}) and also the @file{testext.c} code for testing the APIs. +see this in the sample extension @file{filefuncs.c} (@pxref{Extension +Example}) and also in the @file{testext.c} code for testing the APIs. Some other bits and pieces: @@ -31024,13 +31493,13 @@ This (rather large) @value{SECTION} describes the API in detail. @menu * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @command{gawk}. * Printing Messages:: Functions for printing messages. * Updating @code{ERRNO}:: Functions for updating @code{ERRNO}. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -31049,6 +31518,9 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item +Allocating, reallocating, and releasing memory. + +@item Registration functions. You may register: @itemize @value{MINUS} @item @@ -31081,9 +31553,6 @@ Symbol table access: retrieving a global variable, creating one, or changing one. @item -Allocating, reallocating, and releasing memory. - -@item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -31151,15 +31620,15 @@ does not support this keyword, you should either place All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} -from the extension @emph{must} come from calling the API-provided function -pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}, +from the extension @emph{must} come from calling one of +@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item 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 since embedded @value{NUL} characters are allowed. @quotation NOTE @@ -31172,7 +31641,7 @@ and also how characters are likely to be input and output from files. @item When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type (number, string, -scalars, value cookie, array, or ``undefined''). When the request is +scalar, value cookie, array, or ``undefined''). When the request is ``undefined,'' the returned value will have the real underlying type. However, if the request and actual type don't match, the access function @@ -31235,8 +31704,8 @@ 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 the API-provided function -pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} +@strong{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. @@ -31291,7 +31760,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. Since @command{gawk} allows embedded @value{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. @@ -31331,7 +31800,7 @@ the cookie for getting the variable's value or for changing the variable's value. This is the @code{awk_scalar_t} type and @code{scalar_cookie} macro. Given a scalar cookie, @command{gawk} can directly retrieve or -modify the value, as required, without having to first find it. +modify the value, as required, without having to find it first. The @code{awk_value_cookie_t} type and @code{value_cookie} macro are similar. If you know that you wish to @@ -31341,149 +31810,6 @@ and then pass in that value cookie whenever you wish to set the value of a variable. This saves both storage space within the running @command{gawk} process as well as the time needed to create the value. -@node Requesting Values -@subsection Requesting Values - -All of the functions that return values from @command{gawk} -work in the same way. You pass in an @code{awk_valtype_t} value -to indicate what kind of value you expect. If the actual value -matches what you requested, the function returns true and fills -in the @code{awk_value_t} result. -Otherwise, the function returns false, and the @code{val_type} -member indicates the type of the actual value. You may then -print an error message, or reissue the request for the actual -value type, as appropriate. This behavior is summarized in -@ref{table-value-types-returned}. - -@c FIXME: Try to do this with spans... - -@float Table,table-value-types-returned -@caption{API Value Types Returned} -@docbook -<informaltable> -<tgroup cols="2"> - <colspec colwidth="50*"/><colspec colwidth="50*"/> - <thead> - <row><entry></entry><entry><para>Type of Actual Value:</para></entry></row> - </thead> - <tbody> - <row><entry></entry><entry></entry></row> - </tbody> -</tgroup> -<tgroup cols="6"> - <colspec colwidth="16.6*"/> - <colspec colwidth="16.6*"/> - <colspec colwidth="19.8*"/> - <colspec colwidth="15*"/> - <colspec colwidth="15*"/> - <colspec colwidth="16.6*"/> - <thead> - <row> - <entry></entry> - <entry></entry> - <entry><para>String</para></entry> - <entry><para>Number</para></entry> - <entry><para>Array</para></entry> - <entry><para>Undefined</para></entry> - </row> - </thead> - <tbody> - <row> - <entry></entry> - <entry><para><emphasis role="bold">String</emphasis></para></entry> - <entry><para>String</para></entry> - <entry><para>String</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Number</emphasis></para></entry> - <entry><para>Number if can be converted, else false</para></entry> - <entry><para>Number</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry><para><emphasis role="bold">Type</emphasis></para></entry> - <entry><para><emphasis role="bold">Array</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>Array</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <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> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> - <entry><para>String</para></entry> - <entry><para>Number</para></entry> - <entry><para>Array</para></entry> - <entry><para>Undefined</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para> - </entry><entry><para>false</para></entry> - </row> - </tbody> -</tgroup> -</informaltable> -@end docbook - -@ifnotplaintext -@ifnotdocbook -@multitable @columnfractions .50 .50 -@headitem @tab Type of Actual Value: -@end multitable -@multitable @columnfractions .166 .166 .198 .15 .15 .166 -@headitem @tab @tab String @tab Number @tab Array @tab Undefined -@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 @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 -@end ifnotdocbook -@end ifnotplaintext -@ifplaintext -@example - +-------------------------------------------------+ - | Type of Actual Value: | - +------------+------------+-----------+-----------+ - | String | Number | Array | Undefined | -+-----------+-----------+------------+------------+-----------+-----------+ -| | String | String | String | false | false | -| |-----------+------------+------------+-----------+-----------+ -| | Number | Number if | Number | false | false | -| | | can be | | | | -| | | converted, | | | | -| | | else false | | | | -| |-----------+------------+------------+-----------+-----------+ -| Type | Array | false | false | Array | false | -| Requested |-----------+------------+------------+-----------+-----------+ -| | Scalar | Scalar | Scalar | false | false | -| |-----------+------------+------------+-----------+-----------+ -| | Undefined | String | Number | Array | Undefined | -| |-----------+------------+------------+-----------+-----------+ -| | Value | false | false | false | false | -| | Cookie | | | | | -+-----------+-----------+------------+------------+-----------+-----------+ -@end example -@end ifplaintext -@end float - @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros @cindex allocating memory for extensions @@ -31492,22 +31818,24 @@ value type, as appropriate. This behavior is summarized in 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. @table @code @item void *gawk_malloc(size_t size); -Call @command{gawk}-provided @code{api_malloc()} to allocate storage that may +Call the correct version of @code{malloc()} to allocate storage that may be passed to @command{gawk}. @item void *gawk_calloc(size_t nmemb, size_t size); -Call @command{gawk}-provided @code{api_calloc()} to allocate storage that may +Call the correct version of @code{calloc()} to allocate storage that may be passed to @command{gawk}. @item void *gawk_realloc(void *ptr, size_t size); -Call @command{gawk}-provided @code{api_realloc()} to allocate storage that may +Call the correct version of @code{realloc()} to allocate storage that may be passed to @command{gawk}. @item void gawk_free(void *ptr); -Call @command{gawk}-provided @code{api_free()} to release storage that was +Call the correct version of @code{free()} to release storage that was allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. @end table @@ -31521,8 +31849,8 @@ unrelated version of @code{malloc()}, unexpected behavior would likely result. Two convenience macros may be used for allocating storage -from the API-provided function pointers @code{api_malloc()} and -@code{api_realloc()}. If the allocation fails, they cause @command{gawk} +from @code{gawk_malloc()} and +@code{gawk_realloc()}. If the allocation fails, they cause @command{gawk} to exit with a fatal error message. They should be used as if they were procedure calls that do not return a value. @@ -31536,7 +31864,7 @@ 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{api_malloc()}. +The type of the pointer variable, used to create a cast for the call to @code{gawk_malloc()}. @item size The total number of bytes to be allocated. @@ -31560,8 +31888,8 @@ make_malloced_string(message, strlen(message), & result); @end example @item #define erealloc(pointer, type, size, message) @dots{} -This is like @code{emalloc()}, but it calls @code{api_realloc()}, -instead of @code{api_malloc()}. +This is like @code{emalloc()}, but it calls @code{gawk_realloc()}, +instead of @code{gawk_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table @@ -31585,7 +31913,7 @@ for storage in @code{result}. It returns @code{result}. @itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) This function creates a string value in the @code{awk_value_t} variable pointed to by @code{result}. It expects @code{string} to be a @samp{char *} -value pointing to data previously obtained from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. The idea here +value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. The idea here is that the data is passed directly to @command{gawk}, which assumes responsibility for it. It returns @code{result}. @@ -31640,17 +31968,18 @@ The name of the new function. This is a regular C string. Function names must obey the rules for @command{awk} -identifiers. That is, they must begin with either a letter +identifiers. That is, they must begin with either an English letter or an underscore, which may be followed by any number of letters, digits, and underscores. Letter case in function names is significant. @item awk_value_t *(*function)(int num_actual_args, awk_value_t *result); -This is a pointer to the C function that provides the desired +This is a pointer to the C function that provides the extension's functionality. -The function must fill in the result with either a number +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 the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_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. @@ -31661,7 +31990,7 @@ This is for the convenience of the calling code inside @command{gawk}. @item size_t num_expected_args; This is the number of arguments the function expects to receive. Each extension function may decide what to do if the number of -arguments isn't what it expected. Following @command{awk} functions, it +arguments isn't what it expected. As with real @command{awk} functions, it is likely OK to ignore extra arguments. @end table @@ -31915,7 +32244,7 @@ If the concept of a ``record terminator'' makes sense, then @code{RT}, and @code{*rt_len} should be set to the length of the data. Otherwise, @code{*rt_len} should be set to zero. @code{gawk} makes its own copy of this data, so the -extension must manage the storage. +extension must manage this storage. @end table The return value is the length of the buffer pointed to by @@ -32194,10 +32523,148 @@ into a (possibly translated) string using the C @code{strerror()} function. Set @code{ERRNO} directly to the string value of @code{ERRNO}. @command{gawk} makes a copy of the value of @code{string}. -@item void unset_ERRNO(); +@item void unset_ERRNO(void); Unset @code{ERRNO}. @end table +@node Requesting Values +@subsection Requesting Values + +All of the functions that return values from @command{gawk} +work in the same way. You pass in an @code{awk_valtype_t} value +to indicate what kind of value you expect. If the actual value +matches what you requested, the function returns true and fills +in the @code{awk_value_t} result. +Otherwise, the function returns false, and the @code{val_type} +member indicates the type of the actual value. You may then +print an error message, or reissue the request for the actual +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} +@docbook +<informaltable> +<tgroup cols="6"> + <colspec colwidth="16.6*"/> + <colspec colwidth="16.6*"/> + <colspec colwidth="19.8*" colname="c3"/> + <colspec colwidth="15*" colname="c4"/> + <colspec colwidth="15*" colname="c5"/> + <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></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + </thead> + <tbody> + <row> + <entry></entry> + <entry><para><emphasis role="bold">String</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>String</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Number</emphasis></para></entry> + <entry><para>Number if can be converted, else false</para></entry> + <entry><para>Number</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Type</emphasis></para></entry> + <entry><para><emphasis role="bold">Array</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>Array</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <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> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para> + </entry><entry><para>false</para></entry> + </row> + </tbody> +</tgroup> +</informaltable> +@end docbook + +@ifnotplaintext +@ifnotdocbook +@multitable @columnfractions .50 .50 +@headitem @tab Type of Actual Value: +@end multitable +@c 10/2014: Thanks to Karl Berry for this bit to reduce the space: +@tex +\vglue-1.1\baselineskip +@end tex +@multitable @columnfractions .166 .166 .198 .15 .15 .166 +@headitem @tab @tab String @tab Number @tab Array @tab Undefined +@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 @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 +@end ifnotdocbook +@end ifnotplaintext +@ifplaintext +@example + +-------------------------------------------------+ + | Type of Actual Value: | + +------------+------------+-----------+-----------+ + | String | Number | Array | Undefined | ++-----------+-----------+------------+------------+-----------+-----------+ +| | String | String | String | false | false | +| |-----------+------------+------------+-----------+-----------+ +| | Number | Number if | Number | false | false | +| | | can be | | | | +| | | converted, | | | | +| | | else false | | | | +| |-----------+------------+------------+-----------+-----------+ +| Type | Array | false | false | Array | false | +| Requested |-----------+------------+------------+-----------+-----------+ +| | Scalar | Scalar | Scalar | false | false | +| |-----------+------------+------------+-----------+-----------+ +| | Undefined | String | Number | Array | Undefined | +| |-----------+------------+------------+-----------+-----------+ +| | Value | false | false | false | false | +| | Cookie | | | | | ++-----------+-----------+------------+------------+-----------+-----------+ +@end example +@end ifplaintext +@end float + @node Accessing Parameters @subsection Accessing and Updating Parameters @@ -32252,7 +32719,7 @@ about symbols is termed a @dfn{symbol table}. Fill in the @code{awk_value_t} structure pointed to by @code{result} with the value of the variable named by the string @code{name}, which is a regular C string. @code{wanted} indicates the type of value expected. -Return true if the actual type matches @code{wanted}, false otherwise +Return true if the actual type matches @code{wanted}, false otherwise. In the latter case, @code{result->val_type} indicates the actual type (@pxref{table-value-types-returned}). @@ -32271,7 +32738,7 @@ An extension can look up the value of @command{gawk}'s special variables. However, with the exception of the @code{PROCINFO} array, an extension cannot change any of those variables. -@quotation NOTE +@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 @@ -32293,14 +32760,14 @@ The following functions let you work with scalar cookies. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result); Retrieve the current value of a scalar cookie. -Once you have obtained a scalar_cookie using @code{sym_lookup()}, you can +Once you have obtained a scalar cookie using @code{sym_lookup()}, you can use this function to get its value more efficiently. Return false if the value cannot be retrieved. @item awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value); Update the value associated with a scalar cookie. Return false if the new value is not of type @code{AWK_STRING} or @code{AWK_NUMBER}. -Here too, the built-in variables may not be updated. +Here too, the predefined variables may not be updated. @end table It is not obvious at first glance how to work with scalar cookies or @@ -32355,7 +32822,7 @@ my_extension_init() /* install initial value */ sym_update("MAGIC_VAR", make_number(42.0, & value)); - /* get cookie */ + /* get the cookie */ sym_lookup("MAGIC_VAR", AWK_SCALAR, & value); /* save the cookie */ @@ -32404,7 +32871,8 @@ assign those values to variables using @code{sym_update()} 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{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. +@emph{every} string value's storage @emph{must} come from @code{gawk_malloc()}, +@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.} @@ -32475,7 +32943,7 @@ Using value cookies in this way saves considerable storage, since all of You might be wondering, ``Is this sharing problematic? What happens if @command{awk} code assigns a new value to @code{VAR1}, -are all the others be changed too?'' +are all the others changed too?'' That's a great question. The answer is that no, it's not a problem. Internally, @command{gawk} uses @dfn{reference-counted strings}. This means @@ -32530,7 +32998,7 @@ with the @code{<stdio.h>} library routines. @itemx @ @ @ @ struct awk_element *next; @itemx @ @ @ @ enum @{ @itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DEFAULT = 0,@ @ /* set by gawk */ -@itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DELETE = 1@ @ @ @ /* set by extension if should be deleted */ +@itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DELETE = 1@ @ @ @ /* set by extension */ @itemx @ @ @ @ @} flags; @itemx @ @ @ @ awk_value_t index; @itemx @ @ @ @ awk_value_t value; @@ -32550,8 +33018,8 @@ an extension to create a linked list of new elements that can then be added to an array in a loop that traverses the list. @item enum @{ @dots{} @} flags; -A set of flag values that convey information between @command{gawk} -and the extension. Currently there is only one: @code{AWK_ELEMENT_DELETE}. +A set of flag values that convey information between the extension +and @command{gawk}. Currently there is only one: @code{AWK_ELEMENT_DELETE}. Setting it causes @command{gawk} to delete the element from the original array upon release of the flattened array. @@ -32562,8 +33030,8 @@ The index and value of the element, respectively. @end table @item typedef struct awk_flat_array @{ -@itemx @ @ @ @ awk_const void *awk_const opaque1;@ @ @ @ /* private data for use by gawk */ -@itemx @ @ @ @ awk_const void *awk_const opaque2;@ @ @ @ /* private data for use by gawk */ +@itemx @ @ @ @ awk_const void *awk_const opaque1;@ @ @ @ /* for use by gawk */ +@itemx @ @ @ @ awk_const void *awk_const opaque2;@ @ @ @ /* for use by gawk */ @itemx @ @ @ @ awk_const size_t count;@ @ @ @ @ /* how many elements */ @itemx @ @ @ @ awk_element_t elements[1];@ @ /* will be extended */ @itemx @} awk_flat_array_t; @@ -32582,7 +33050,7 @@ The following functions relate to individual array elements. @table @code @item awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count); -For the array represented by @code{a_cookie}, return in @code{*count} +For the array represented by @code{a_cookie}, place in @code{*count} the number of elements it contains. A subarray counts as a single element. Return false if there is an error. @@ -32602,7 +33070,8 @@ requires that you understand how such values are converted to strings (@pxref{Conversion}); thus using integral values is safest. As with @emph{all} strings passed into @code{gawk} from an extension, -the string value of @code{index} must come from the API-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and +the string value of @code{index} must come from @code{gawk_malloc()}, +@code{gawk_calloc()} or @code{gawk_realloc()}, and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -32629,7 +33098,7 @@ not exist in the array. The following functions relate to arrays as a whole: @table @code -@item awk_array_t create_array(); +@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 create a new array and add elements to it. @@ -32646,7 +33115,13 @@ For the array represented by @code{a_cookie}, create an @code{awk_flat_array_t} structure and fill it in. Set the pointer whose address is passed as @code{data} to point to this structure. Return true upon success, or false otherwise. -@xref{Flattening Arrays}, for a discussion of how to +@ifset FOR_PRINT +See the next section +@end ifset +@ifclear FOR_PRINT +@xref{Flattening Arrays}, +@end ifclear +for a discussion of how to flatten an array and work with it. @item awk_bool_t release_flattened_array(awk_array_t a_cookie, @@ -32666,6 +33141,7 @@ for C code to traverse the entire array. Test code in @file{extension/testext.c} does this, and also serves as a nice example showing how to use the APIs. +We walk through that part of the code one step at a time. First, the @command{gawk} script that drives the test extension: @example @@ -32804,8 +33280,7 @@ have this flag bit set: valrep2str(& flat_array->elements[i].value)); if (strcmp(value3.str_value.str, - flat_array->elements[i].index.str_value.str) - == 0) @{ + flat_array->elements[i].index.str_value.str) == 0) @{ flat_array->elements[i].flags |= AWK_ELEMENT_DELETE; printf("dump_array_and_delete: marking element \"%s\" " "for deletion\n", @@ -32909,7 +33384,9 @@ of the array cookie after the call to @code{set_element()}. 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} -directives and boilerplate variable declarations are omitted for brevity. +directives and boilerplate variable declarations +(@pxref{Extension API Boilerplate}) +are omitted for brevity. The first step is to create a new array and then install it in the symbol table: @@ -33155,7 +33632,7 @@ This variable is true if @command{gawk} was invoked with @option{--traditional} @end table The value of @code{do_lint} can change if @command{awk} code -modifies the @code{LINT} built-in variable (@pxref{Built-in Variables}). +modifies the @code{LINT} predefined variable (@pxref{Built-in Variables}). The others should not change during execution. @node Extension API Boilerplate @@ -33188,12 +33665,12 @@ static awk_bool_t (*init_func)(void) = NULL; /* OR: */ static awk_bool_t -init_my_module(void) +init_my_extension(void) @{ @dots{} @} -static awk_bool_t (*init_func)(void) = init_my_module; +static awk_bool_t (*init_func)(void) = init_my_extension; dl_load_func(func_table, some_name, "name_space_in_quotes") @end example @@ -33236,8 +33713,8 @@ It can then be looped over for multiple calls to @c Use @var{OR} for docbook @item static awk_bool_t (*init_func)(void) = NULL; @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @var{OR} -@itemx static awk_bool_t init_my_module(void) @{ @dots{} @} -@itemx static awk_bool_t (*init_func)(void) = init_my_module; +@itemx static awk_bool_t init_my_extension(void) @{ @dots{} @} +@itemx static awk_bool_t (*init_func)(void) = init_my_extension; If you need to do some initialization work, you should define a function that does it (creates variables, opens files, etc.) and then define the @code{init_func} pointer to point to your @@ -33304,8 +33781,8 @@ path with a list of directories to search for compiled extensions. Two useful functions that are not in @command{awk} are @code{chdir()} (so that an @command{awk} program can change its directory) and @code{stat()} (so that an @command{awk} program can gather information about a file). -This @value{SECTION} implements these functions for @command{gawk} -in an extension. +In order to illustrate the API in action, this @value{SECTION} implements +these functions for @command{gawk} in an extension. @menu * Internal File Description:: What the new functions will do. @@ -33327,8 +33804,7 @@ straightforward. It takes one argument, the new directory to change to: newdir = "/home/arnold/funstuff" ret = chdir(newdir) if (ret < 0) @{ - printf("could not change to %s: %s\n", - newdir, ERRNO) > "/dev/stderr" + printf("could not change to %s: %s\n", newdir, ERRNO) > "/dev/stderr" exit 1 @} @dots{} @@ -33516,7 +33992,7 @@ The second is a pointer to an @code{awk_value_t}, usually named @code{result}. @example -/* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ +/* do_chdir --- provide dynamically loaded chdir() function for gawk */ static awk_value_t * do_chdir(int nargs, awk_value_t *result) @@ -33725,13 +34201,22 @@ for success: @} @} - array_set(array, "type", make_const_string(type, strlen(type), &tmp)); + array_set(array, "type", make_const_string(type, strlen(type), & tmp)); return 0; @} @end example -Finally, here is the @code{do_stat()} function. It starts with +The third argument to @code{stat()} was not discussed previously. This +argument is optional. If present, it causes @code{do_stat()} to use +the @code{stat()} system call instead of the @code{lstat()} system +call. This is done by using a function pointer: @code{statfunc}. +@code{statfunc} is initialized to point to @code{lstat()} (instead +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 variable declarations and argument checking: @ignore @@ -33762,16 +34247,10 @@ do_stat(int nargs, awk_value_t *result) @} @end example -The third argument to @code{stat()} was not discussed previously. This argument -is optional. If present, it causes @code{stat()} to use the @code{stat()} -system call instead of the @code{lstat()} system call. - Then comes the actual work. First, the function gets the arguments. -Next, it gets the information for the file. -The code use @code{lstat()} (instead of @code{stat()}) -to get the file information, -in case the file is a symbolic link. -If there's an error, it sets @code{ERRNO} and returns: +Next, it gets the information for the file. If the called function +(@code{lstat()} or @code{stat()}) returns an error, the code sets +@code{ERRNO} and returns: @example /* file is first arg, array to hold results is second */ @@ -33800,7 +34279,7 @@ If there's an error, it sets @code{ERRNO} and returns: @end example The tedious work is done by @code{fill_stat_array()}, shown -earlier. When done, return the result from @code{fill_stat_array()}: +earlier. When done, the function returns the result from @code{fill_stat_array()}: @example ret = fill_stat_array(name, array, & sbuf); @@ -33863,7 +34342,7 @@ 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 configure and build your libraries. Instructions for doing so are beyond -the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for WWW links to +the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for Internet links to the tools.} create a GNU/Linux shared library: @example @@ -33891,14 +34370,14 @@ BEGIN @{ for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] print "testff.awk modified:", - strftime("%m %d %y %H:%M:%S", data["mtime"]) + strftime("%m %d %Y %H:%M:%S", data["mtime"]) print "\nInfo for JUNK" ret = stat("JUNK", data) print "ret =", ret for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] - print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"]) + print "JUNK modified:", strftime("%m %d %Y %H:%M:%S", data["mtime"]) @} @end example @@ -33912,25 +34391,26 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @print{} Info for testff.awk @print{} ret = 0 @print{} data["blksize"] = 4096 -@print{} data["mtime"] = 1350838628 +@print{} data["devbsize"] = 512 +@print{} data["mtime"] = 1412004710 @print{} data["mode"] = 33204 @print{} data["type"] = file @print{} data["dev"] = 2053 @print{} data["gid"] = 1000 -@print{} data["ino"] = 1719496 -@print{} data["ctime"] = 1350838628 +@print{} data["ino"] = 10358899 +@print{} data["ctime"] = 1412004710 @print{} data["blocks"] = 8 @print{} data["nlink"] = 1 @print{} data["name"] = testff.awk -@print{} data["atime"] = 1350838632 +@print{} data["atime"] = 1412004716 @print{} data["pmode"] = -rw-rw-r-- -@print{} data["size"] = 662 +@print{} data["size"] = 666 @print{} data["uid"] = 1000 -@print{} testff.awk modified: 10 21 12 18:57:08 -@print{} +@print{} testff.awk modified: 09 29 2014 18:31:50 +@print{} @print{} Info for JUNK @print{} ret = -1 -@print{} JUNK modified: 01 01 70 02:00:00 +@print{} JUNK modified: 01 01 1970 02:00:00 @end example @node Extension Samples @@ -33955,9 +34435,9 @@ Others mainly provide example code that shows how to use the extension API. * Extension Sample Rev2way:: Reversing data sample two-way processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to @code{gettimeofday()} and @code{sleep()}. +* Extension Sample API Tests:: Tests for the API. @end menu @node Extension Sample File Functions @@ -33967,7 +34447,7 @@ The @code{filefuncs} extension provides three different functions, as follows: The usage is: @table @asis -@item @@load "filefuncs" +@item @code{@@load "filefuncs"} This is how you load the extension. @cindex @code{chdir()} extension function @@ -34030,7 +34510,7 @@ Not all systems support all file types. @tab All @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 constant values, also described below. +OR of several predefined values, also described below. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -34075,10 +34555,10 @@ Immediately follow a symbolic link named in @code{pathlist}, whether or not @code{FTS_LOGICAL} is set. @item FTS_SEEDOT -By default, the @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.) +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.) @item FTS_XDEV During a traversal, do not cross onto a different mounted filesystem. @@ -34132,8 +34612,8 @@ Otherwise it returns @minus{}1. @quotation NOTE 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 should -be more comfortable to use from an @command{awk} program. This includes the +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 interface could have been provided, this felt less natural than simply @@ -34141,7 +34621,8 @@ creating a multidimensional array to represent the file hierarchy and its information. @end quotation -See @file{test/fts.awk} in the @command{gawk} distribution for an example. +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()} @@ -34349,7 +34830,7 @@ indicating the type of the file. The letters are file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types -@caption{File Types Returned By @code{readdir()}} +@caption{File Types Returned By The @code{readdir} Extension} @multitable @columnfractions .1 .9 @headitem Letter @tab File Type @item @code{b} @tab Block device @@ -34441,6 +34922,9 @@ The @code{rwarray} extension adds two functions, named @code{writea()} and @code{reada()}, as follows: @table @code +@item @@load "rwarray" +This is how you load the extension. + @cindex @code{writea()} extension function @item ret = writea(file, array) This function takes a string argument, which is the name of the file @@ -34516,17 +35000,6 @@ if (contents == "" && ERRNO != "") @{ @} @end example -@node Extension Sample API Tests -@subsection API Tests -@cindex @code{testext} extension - -The @code{testext} extension exercises parts of the extension API that -are not tested by the other samples. The @file{extension/testext.c} -file contains both the C code for the extension and @command{awk} -test code inside C comments that run the tests. The testing framework -extracts the @command{awk} code and runs the tests. See the source file -for more information. - @node Extension Sample Time @subsection Extension Time Functions @@ -34557,6 +35030,17 @@ Implementation details: depending on platform availability, this function tries to use @code{nanosleep()} or @code{select()} to implement the delay. @end table +@node Extension Sample API Tests +@subsection API Tests +@cindex @code{testext} extension + +The @code{testext} extension exercises parts of the extension API that +are not tested by the other samples. The @file{extension/testext.c} +file contains both the C code for the extension and @command{awk} +test code inside C comments that run the tests. The testing framework +extracts the @command{awk} code and runs the tests. See the source file +for more information. + @node gawkextlib @section The @code{gawkextlib} Project @cindex @code{gawkextlib} @@ -34572,8 +35056,7 @@ As of this writing, there are five extensions: @itemize @value{BULLET} @item -XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} -XML parsing library. +GD graphics library extension. @item PDF extension. @@ -34582,17 +35065,14 @@ PDF extension. PostgreSQL extension. @item -GD graphics library extension. - -@item MPFR library extension. This provides access to a number of MPFR functions which @command{gawk}'s native MPFR support does not. -@end itemize -The @code{time} extension described earlier (@pxref{Extension Sample -Time}) was originally from this project but has been moved in to the -main @command{gawk} distribution. +@item +XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} +XML parsing library. +@end itemize @cindex @command{git} utility You can check out the code for the @code{gawkextlib} project @@ -34669,7 +35149,7 @@ certain tasks. @item One of these tasks is to ``register'' the name and implementation of -a new @command{awk}-level function with @command{gawk}. The implementation +new @command{awk}-level functions with @command{gawk}. The implementation takes the form of a C function pointer with a defined signature. By convention, implementation functions are named @code{do_@var{XXXX}()} for some @command{awk}-level function @code{@var{XXXX}()}. @@ -34683,6 +35163,9 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item +Allocating, reallocating, and releasing memory. + +@item Registration functions. You may register extension functions, exit callbacks, @@ -34706,9 +35189,6 @@ Symbol table access: retrieving a global variable, creating one, or changing one. @item -Allocating, reallocating, and releasing memory. - -@item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -34720,7 +35200,7 @@ 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 @@ -34740,7 +35220,7 @@ treated as read-only by the extension. @item @emph{All} memory passed from an extension to @command{gawk} must come from the API's memory allocation functions. @command{gawk} takes responsibility for -the memory and will release it when appropriate. +the memory and releases it when appropriate. @item The API provides information about the running version of @command{gawk} so @@ -34757,10 +35237,11 @@ The @command{gawk} distribution includes a number of small but useful sample extensions. The @code{gawkextlib} project includes several more, larger, extensions. If you wish to write an extension and contribute it to the community of @command{gawk} users, the @code{gawkextlib} project -should be the place to do so. +is the place to do so. @end itemize +@c EXCLUDE START @node Extension Exercises @section Exercises @@ -34783,6 +35264,7 @@ Write a wrapper script that provides an interface similar to @ref{Extension Sample Inplace}. @end enumerate +@c EXCLUDE END @ifnotinfo @part @value{PART4}Appendices @@ -34837,7 +35319,7 @@ which follows the POSIX specification. Many long-time @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 -of Berkeley Unix, and some systems derived from 4.4BSD-Lite, used various +of Berkeley Unix, and, for a while, some systems derived from 4.4BSD-Lite, used various versions of @command{gawk} for their @command{awk}.) This @value{CHAPTER} briefly describes the evolution of the @command{awk} language, with cross-references to other parts of the @value{DOCUMENT} where you can @@ -34910,7 +35392,7 @@ The built-in functions @code{close()} and @code{system()} @item The @code{ARGC}, @code{ARGV}, @code{FNR}, @code{RLENGTH}, @code{RSTART}, -and @code{SUBSEP} built-in variables (@pxref{Built-in Variables}). +and @code{SUBSEP} predefined variables (@pxref{Built-in Variables}). @item Assignable @code{$0} (@pxref{Changing Fields}). @@ -34941,14 +35423,11 @@ of @code{FS}. @item Dynamic regexps as operands of the @samp{~} and @samp{!~} operators -(@pxref{Regexp Usage}). +(@pxref{Computed Regexps}). @item The escape sequences @samp{\b}, @samp{\f}, and @samp{\r} (@pxref{Escape Sequences}). -(Some vendors have updated their old versions of @command{awk} to -recognize @samp{\b}, @samp{\f}, and @samp{\r}, but this is not -something you can rely on.) @item Redirection of input for the @code{getline} function @@ -34987,7 +35466,7 @@ The @option{-v} option for assigning variables before program execution begins @c GNU, Bell Laboratories & MKS together @item -The @option{--} option for terminating command-line options. +The @option{--} signal for terminating command-line options. @item The @samp{\a}, @samp{\v}, and @samp{\x} escape sequences @@ -35004,13 +35483,13 @@ for case translation (@pxref{String Functions}). @item -A cleaner specification for the @samp{%c} format-control letter in the +A cleaner specification for the @code{%c} format-control letter in the @code{printf} function (@pxref{Control Letters}). @item The ability to dynamically pass the field width and precision (@code{"%*.*d"}) -in the argument list of the @code{printf} function +in the argument list of @code{printf} and @code{sprintf()} (@pxref{Control Letters}). @item @@ -35045,8 +35524,8 @@ The concept of a numeric string and tighter comparison rules to go with it (@pxref{Typing and Comparison}). @item -The use of built-in variables as function parameter names is forbidden -(@pxref{Definition Syntax}. +The use of predefined variables as function parameter names is forbidden +(@pxref{Definition Syntax}). @item More complete documentation of many of the previously undocumented @@ -35141,7 +35620,7 @@ in the current version of @command{gawk}. @itemize @value{BULLET} @item -Additional built-in variables: +Additional predefined variables: @itemize @value{MINUS} @item @@ -35225,14 +35704,6 @@ The @code{BEGINFILE} and @code{ENDFILE} special patterns. (@pxref{BEGINFILE/ENDFILE}). @item -The ability to delete all of an array at once with @samp{delete @var{array}} -(@pxref{Delete}). - -@item -The @code{nextfile} statement -(@pxref{Nextfile Statement}). - -@item The @code{switch} statement (@pxref{Switch Statement}). @end itemize @@ -35247,7 +35718,7 @@ of a two-way pipe to a coprocess (@pxref{Two-way I/O}). @item -POSIX compliance for @code{gsub()} and @code{sub()}. +POSIX compliance for @code{gsub()} and @code{sub()} with @option{--posix}. @item The @code{length()} function accepts an array argument @@ -35275,6 +35746,20 @@ Additional functions only in @command{gawk}: @itemize @value{MINUS} @item +The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions +for more powerful text manipulation +(@pxref{String Functions}). + +@item +The @code{asort()} and @code{asorti()} functions for sorting arrays +(@pxref{Array Sorting}). + +@item +The @code{mktime()}, @code{systime()}, and @code{strftime()} +functions for working with timestamps +(@pxref{Time Functions}). + +@item The @code{and()}, @code{compl()}, @@ -35288,30 +35773,15 @@ functions for bit manipulation @c In 4.1, and(), or() and xor() grew the ability to take > 2 arguments @item -The @code{asort()} and @code{asorti()} functions for sorting arrays -(@pxref{Array Sorting}). +The @code{isarray()} function to check if a variable is an array or not +(@pxref{Type Functions}). @item The @code{bindtextdomain()}, @code{dcgettext()} and @code{dcngettext()} functions for internationalization (@pxref{Programmer i18n}). - -@item -The @code{fflush()} function from BWK @command{awk} -(@pxref{I/O Functions}). - -@item -The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions -for more powerful text manipulation -(@pxref{String Functions}). - -@item -The @code{mktime()}, @code{systime()}, and @code{strftime()} -functions for working with timestamps -(@pxref{Time Functions}). @end itemize - @item Changes and/or additions in the command-line options: @@ -35434,7 +35904,7 @@ GCC for VAX and Alpha has not been tested for a while. @item Support for the following obsolete systems was removed from the code -and the documentation for @command{gawk} @value{PVERSION} 4.1: +for @command{gawk} @value{PVERSION} 4.1: @c nested table @itemize @value{MINUS} @@ -35442,6 +35912,10 @@ and the documentation for @command{gawk} @value{PVERSION} 4.1: Ultrix @end itemize +@item +@c FIXME: Verify the version here. +Support for MirBSD was removed at @command{gawk} @value{PVERSION} 4.2. + @end itemize @c XXX ADD MORE STUFF HERE @@ -36067,33 +36541,29 @@ The dynamic extension interface was completely redone @cindex extensions, Brian Kernighan's @command{awk} @cindex extensions, @command{mawk} -This @value{SECTION} summarizes the common extensions supported +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} (@pxref{Other Versions}). -@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} -@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk -@item @samp{\x} Escape sequence @tab X @tab X @tab X -@item @code{FS} as null string @tab X @tab X @tab X -@item @file{/dev/stdin} special file @tab X @tab X @tab X -@item @file{/dev/stdout} special file @tab X @tab X @tab X -@item @file{/dev/stderr} special file @tab X @tab X @tab X -@item @code{delete} without subscript @tab X @tab X @tab X -@item @code{fflush()} function @tab X @tab X @tab X -@item @code{length()} of an array @tab X @tab X @tab X -@item @code{nextfile} statement @tab X @tab X @tab X -@item @code{**} and @code{**=} operators @tab X @tab @tab X -@item @code{func} keyword @tab X @tab @tab X -@item @code{BINMODE} variable @tab @tab X @tab X -@item @code{RS} as regexp @tab @tab X @tab X -@item Time related functions @tab @tab X @tab X +@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} {Now standard} +@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk @tab Now standard +@item @samp{\x} Escape sequence @tab X @tab X @tab X @tab +@item @code{FS} as null string @tab X @tab X @tab X @tab +@item @file{/dev/stdin} special file @tab X @tab X @tab X @tab +@item @file{/dev/stdout} special file @tab X @tab X @tab X @tab +@item @file{/dev/stderr} special file @tab X @tab X @tab X @tab +@item @code{delete} without subscript @tab X @tab X @tab X @tab X +@item @code{fflush()} function @tab X @tab X @tab X @tab X +@item @code{length()} of an array @tab X @tab X @tab X @tab +@item @code{nextfile} statement @tab X @tab X @tab X @tab X +@item @code{**} and @code{**=} operators @tab X @tab @tab X @tab +@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 @end multitable -(Technically speaking, as of late 2012, @code{fflush()}, @samp{delete @var{array}}, -and @code{nextfile} are no longer extensions, since they have been added -to POSIX.) - @node Ranges and Locales @appendixsec Regexp Ranges and Locales: A Long Sad Story @@ -36130,6 +36600,7 @@ In the @code{"C"} and @code{"POSIX"} locales, a range expression like But outside those locales, the ordering was defined to be based on @dfn{collation order}. +What does that mean? In many locales, @samp{A} and @samp{a} are both less than @samp{B}. In other words, these locales sort characters in dictionary order, and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; @@ -36137,7 +36608,7 @@ instead it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. 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 matched all of the uppercase characters +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 into the twenty-first century. @@ -36327,7 +36798,7 @@ the various PC platforms. @cindex Zoulas, Christos Christos Zoulas provided the @code{extension()} -built-in function for dynamically adding new modules. +built-in function for dynamically adding new functions. (This was obsoleted at @command{gawk} 4.1.) @item @@ -36443,6 +36914,11 @@ The development of the extension API first released with Arnold Robbins and Andrew Schorr, with notable contributions from the rest of the development team. +@cindex Malmberg, John E. +@item +John Malmberg contributed significant improvements to the +OpenVMS port and the related documentation. + @item @cindex Colombo, Antonio Antonio Giovanni Colombo rewrote a number of examples in the early @@ -36504,7 +36980,7 @@ 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 did +for the electronic mail addresses of the people who maintain the respective ports. @menu @@ -36823,11 +37299,10 @@ Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin environment for MS-Windows. After you have extracted the @command{gawk} distribution, @command{cd} -to @file{gawk-@value{VERSION}.@value{PATCHLEVEL}}. Like most GNU software, -@command{gawk} is configured -automatically for your system by running the @command{configure} program. -This program is a Bourne shell script that is generated automatically using -GNU Autoconf. +to @file{gawk-@value{VERSION}.@value{PATCHLEVEL}}. As with most GNU +software, you configure @command{gawk} for your system by running the +@command{configure} program. This program is a Bourne shell script that +is generated automatically using GNU Autoconf. @ifnotinfo (The Autoconf software is described fully in @@ -36922,8 +37397,8 @@ Similarly, setting the @code{LINT} variable has no effect on the running @command{awk} program. When used with GCC's automatic dead-code-elimination, this option -cuts almost 200K bytes off the size of the @command{gawk} -executable on GNU/Linux x86 systems. Results on other systems and +cuts almost 23K bytes off the size of the @command{gawk} +executable on GNU/Linux x86_64 systems. Results on other systems and with other compilers are likely to vary. Using this option may bring you some slight performance improvement. @@ -37016,7 +37491,8 @@ various non-Unix systems. @cindex PC operating systems@comma{} @command{gawk} on, installing @cindex operating systems, PC@comma{} @command{gawk} on, installing -This @value{SECTION} covers installation and usage of @command{gawk} on x86 machines +This @value{SECTION} covers installation and usage of @command{gawk} +on Intel architecture machines @ifclear FOR_PRINT running MS-DOS, any version of MS-Windows, or OS/2. @end ifclear @@ -37118,7 +37594,8 @@ MS-DOS and Windows32 versions. A list of targets is printed if the build @command{gawk} using the DJGPP tools, enter @samp{make djgpp}. (The DJGPP tools needed for the build may be found at @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/}.) To build a -native MS-Windows binary of @command{gawk}, type @samp{make mingw32}. +native MS-Windows binary of @command{gawk} using the MinGW tools, +type @samp{make mingw32}. @ifclear FOR_PRINT @cindex compiling @command{gawk} with EMX for OS/2 @@ -37248,8 +37725,7 @@ The MS-DOS and MS-Windows versions of @command{gawk} search for program files as described in @ref{AWKPATH Variable}. However, semicolons (rather than colons) separate elements in the @env{AWKPATH} variable. If @env{AWKPATH} is not set or is empty, then the default -search path for MS-Windows and MS-DOS versions is -@samp{@w{.;c:/lib/awk;c:/gnu/lib/awk}}. +search path is @samp{@w{.;c:/lib/awk;c:/gnu/lib/awk}}. @ifclear FOR_PRINT @cindex @command{gawk}, OS/2 version of @@ -37294,12 +37770,12 @@ allows control over these translations and is interpreted as follows: @itemize @value{BULLET} @item -If @code{BINMODE} is @code{"r"}, or one, +If @code{BINMODE} is @code{"r"} or one, then binary mode is set on read (i.e., no translations on reads). @item -If @code{BINMODE} is @code{"w"}, or two, +If @code{BINMODE} is @code{"w"} or two, then binary mode is set on write (i.e., no translations on writes). @@ -37387,7 +37863,7 @@ same as for a Unix system: tar -xvpzf gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz cd gawk-@value{VERSION}.@value{PATCHLEVEL} ./configure -make +make && make check @end example When compared to GNU/Linux on the same system, the @samp{configure} @@ -37403,10 +37879,10 @@ 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. Caveat Emptor! +translation of @code{"\r\n"}, since it won't. @node VMS Installation -@appendixsubsec How to Compile and Install @command{gawk} on Vax/VMS and OpenVMS +@appendixsubsec Compiling and Installing @command{gawk} on Vax/VMS and OpenVMS @c based on material from Pat Rankin <rankin@eql.caltech.edu> @c now rankin@pactechdata.com @@ -37511,7 +37987,7 @@ For VAX: @end example Compile time macros need to be defined before the first VMS-supplied -header file is included. +header file is included, as follows: @example #if (__CRTL_VER >= 70200000) && !defined (__VAX) @@ -37527,6 +38003,11 @@ header file is included. #endif @end example +If you are writing your own extensions to run on VMS, you must supply these +definitions yourself. The @file{config.h} file created when building @command{gawk} +on VMS does this for you; if instead you use that file or a similar one, then you +must remember to include it before any VMS-supplied header files. + @node VMS Installation Details @appendixsubsubsec Installing @command{gawk} on VMS @@ -37623,12 +38104,12 @@ other dash-type options (or multiple parameters such as @value{DF}s to process) are present, there is no ambiguity and @option{--} can be omitted. @cindex exit status, of VMS -The @code{exit} value is a Unix-style value and is encoded to a VMS exit +The @code{exit} value is a Unix-style value and is encoded into a VMS exit status value when the program exits. The VMS severity bits will be set based on the @code{exit} value. A failure is indicated by 1 and VMS sets the @code{ERROR} status. -A fatal error is indicated by 2 and VMS will set the @code{FATAL} status. +A fatal error is indicated by 2 and VMS sets the @code{FATAL} status. All other values will have the @code{SUCCESS} status. The exit value is encoded to comply with VMS coding standards and will have the @code{C_FACILITY_NO} of @code{0x350000} with the constant @code{0xA000} @@ -37644,7 +38125,7 @@ unix_status = (vms_status .and. &x7f8) / 8 A C program that uses @code{exec()} to call @command{gawk} will get the original Unix-style exit value. -Older versions of @command{gawk} treated a Unix exit code 0 as 1, a failure +Older versions of @command{gawk} for VMS treated a Unix exit code 0 as 1, a failure as 2, a fatal error as 4, and passed all the other numbers through. This violated the VMS exit status coding requirements. @@ -37678,8 +38159,8 @@ See @w{@uref{https://sourceforge.net/p/gnv/wiki/InstallingGNVPackages/}.} The normal build procedure for @command{gawk} produces a program that is suitable for use with GNV. -The @file{vms/gawk_build_steps.txt} in the source documents the procedure -for building a VMS PCSI kit that is compatible with GNV. +The file @file{vms/gawk_build_steps.txt} in the distribution documents +the procedure for building a VMS PCSI kit that is compatible with GNV. @ignore @c The VMS POSIX product, also known as POSIX for OpenVMS, is long defunct @@ -37751,8 +38232,8 @@ 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 but we might well want to fix it. -Before reporting a bug, make sure you have actually found a real bug. -Carefully reread the documentation and see if it really says you can do +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 documentation! @@ -37770,17 +38251,15 @@ You can get this information with the command @samp{gawk --version}. @cindex @code{bug-gawk@@gnu.org} bug reporting address @cindex email address for bug reports, @code{bug-gawk@@gnu.org} @cindex bug reports, email address, @code{bug-gawk@@gnu.org} -Once you have a precise problem, send email to +Once you have a precise problem description, send email to @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. -@cindex Robbins, Arnold The @command{gawk} maintainers subscribe to this address and thus they will receive your bug report. -If necessary, the primary maintainer can be reached directly at -@EMAIL{arnold@@skeeve.com,arnold at skeeve dot com}. -The bug reporting address is preferred since the +Although you can send mail to the maintainers directly, +the bug reporting address is preferred since the email list is archived at the GNU Project. -@emph{All email should be in English. This is the only language +@emph{All email must be in English. This is the only language understood in common by all the maintainers.} @cindex @code{comp.lang.awk} newsgroup @@ -37789,7 +38268,7 @@ 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 official recognized ways for reporting bugs. +above are the only official recognized way for reporting bugs. Really. @end quotation @@ -37801,35 +38280,34 @@ bug reporting system, @emph{please} also send a copy to 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 @command{gawk} maintainer won't even see the bug report! Second, +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 -keeps things self-contained and not dependant on other web sites. +keeps things self-contained and not dependant on other organizations. @end quotation 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 me; I will try to help you out, although I -may not have the time to fix the problem. You can send me electronic -mail at the Internet address noted previously. - -If you find bugs in one of the non-Unix ports of @command{gawk}, please send -an electronic mail message 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 if it conflicts with this -@value{DOCUMENT}. +features, ask on the bug list; we will try to help you out if we can. -The people maintaining the non-Unix ports of @command{gawk} are -as follows: +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 +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 +if it conflicts with this @value{DOCUMENT}. + +The people maintaining the various @command{gawk} ports are: @c put the index entries outside the table, for docbook -@cindex Deifik, Scott -@cindex Zaretskii, Eli @cindex Buening, Andreas -@cindex Rankin, Pat +@cindex Deifik, Scott @cindex Malmberg, John @cindex Pitts, Dave +@cindex Robbins, Arnold +@cindex Zaretskii, Eli @multitable {MS-Windows with MinGW} {123456789012345678901234567890123456789001234567890} +@item Unix and POSIX systems @tab Arnold Robbins, @EMAIL{arnold@@skeeve.com,arnold at skeeve dot com}. + @item MS-DOS with DJGPP @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}. @item MS-Windows with MinGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. @@ -37838,8 +38316,7 @@ as follows: @c OS/2 is not mentioned anywhere else in the print version though. @item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}. -@item VMS @tab Pat Rankin, @EMAIL{r.pat.rankin@@gmail.com,r.pat.rankin at gmail.com}, and -John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net}. +@item VMS @tab John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net}. @item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. @end multitable @@ -37862,11 +38339,22 @@ Date: Wed, 4 Sep 1996 08:11:48 -0700 (PDT) @end ignore @cindex Brennan, Michael +@ifnotdocbook @quotation @i{It's kind of fun to put comments like this in your awk code.}@* @ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of course} @author Michael Brennan @end quotation +@end ifnotdocbook + +@docbook +<blockquote><attribution>Michael Brennan</attribution> +<literallayout><emphasis>It's kind of fun to put comments like this in your awk code.</emphasis> + <literal>// Do C++ comments work? answer: yes! of course</literal></literallayout> +</blockquote> +@end docbook + + There are a number of other freely available @command{awk} implementations. This @value{SECTION} briefly describes where to get them: @@ -37972,7 +38460,7 @@ since approximately 2003. @item @command{pawk} Nelson H.F.@: Beebe at the University of Utah has modified BWK @command{awk} to provide timing and profiling information. -It is different from @command{gawk} with the @option{--profile} option. +It is different from @command{gawk} with the @option{--profile} option (@pxref{Profiling}), in that it uses CPU-based profiling, not line-count profiling. You may find it at either @@ -37997,7 +38485,7 @@ information, see the @uref{http://busybox.net, project's home page}. The versions of @command{awk} in @file{/usr/xpg4/bin} and @file{/usr/xpg6/bin} on Solaris are more-or-less POSIX-compliant. They are based on the @command{awk} from Mortice Kern Systems for PCs. -This author was able to make this code compile and work under GNU/Linux +We were able to make this code compile and work under GNU/Linux with 1--2 hours of work. Making it more generally portable (using GNU Autoconf and/or Automake) would take more work, and this has not been done, at least to our knowledge. @@ -38173,7 +38661,7 @@ as well as any considerations you should bear in mind. @appendixsubsec Accessing The @command{gawk} Git Repository As @command{gawk} is Free Software, the source code is always available. -@ref{Gawk Distribution}, describes how to get and build the formal, +@DBREF{Gawk Distribution} describes how to get and build the formal, released versions of @command{gawk}. @cindex @command{git} utility @@ -38224,7 +38712,7 @@ make it possible to include them: @enumerate 1 @item Before building the new feature into @command{gawk} itself, -consider writing it as an extension module +consider writing it as an extension (@pxref{Dynamic Extensions}). If that's not possible, continue with the rest of the steps in this list. @@ -38469,7 +38957,7 @@ and @item Be willing to continue to maintain the port. Non-Unix operating systems are supported by volunteers who maintain -the code needed to compile and run @command{gawk} on their systems. If noone +the code needed to compile and run @command{gawk} on their systems. If no-one volunteers to maintain a port, it becomes unsupported and it may be necessary to remove it from the distribution. @@ -38531,7 +39019,7 @@ the derived files, because that keeps the repository less cluttered, and it is easier to see the substantive changes when comparing versions and trying to understand what changed between commits. -However, there are two reasons why the @command{gawk} maintainer +However, there are several reasons why the @command{gawk} maintainer likes to have everything in the repository. First, because it is then easy to reproduce any given version completely, @@ -38600,6 +39088,14 @@ the maintainer is no different than Jane User who wants to try to build Thus, the maintainer thinks that it's not just important, but critical, that for any given branch, the above incantation @emph{just works}. +@c Added 9/2014: +A third reason to have all the files is that without them, using @samp{git +bisect} to try to find the commit that introduced a bug is exceedingly +difficult. The maintainer tried to do that on another project that +requires running bootstrapping scripts just to create @command{configure} +and so on; it was really painful. When the repository is self-contained, +using @command{git bisect} in it is very easy. + @c So - that's my reasoning and philosophy. What are some of the consequences and/or actions to take? @@ -38947,7 +39443,7 @@ Pat Rankin suggested the solution that was adopted. @appendixsubsec Other Design Decisions As an arbitrary design decision, extensions can read the values of -built-in variables and arrays (such as @code{ARGV} and @code{FS}), but cannot +predefined variables and arrays (such as @code{ARGV} and @code{FS}), but cannot change them, with the exception of @code{PROCINFO}. The reason for this is to prevent an extension function from affecting @@ -39688,11 +40184,11 @@ See ``Free Documentation License.'' @item Field When @command{awk} reads an input record, it splits the record into pieces separated by whitespace (or by a separator regexp that you can -change by setting the built-in variable @code{FS}). Such pieces are +change by setting the predefined variable @code{FS}). Such pieces are called fields. If the pieces are of fixed length, you can use the built-in variable @code{FIELDWIDTHS} to describe their lengths. If you wish to specify the contents of fields instead of the field -separator, you can use the built-in variable @code{FPAT} to do so. +separator, you can use the predefined variable @code{FPAT} to do so. (@xref{Field Separators}, @ref{Constant Size}, and @@ -39711,7 +40207,7 @@ See also ``Double Precision'' and ``Single Precision.'' Format strings control the appearance of output in the @code{strftime()} and @code{sprintf()} functions, and in the @code{printf} statement as well. Also, data conversions from numbers to strings -are controlled by the format strings contained in the built-in variables +are controlled by the format strings contained in the predefined variables @code{CONVFMT} and @code{OFMT}. (@xref{Control Letters}.) @item Free Documentation License @@ -41390,6 +41886,7 @@ Consistency issues: Use --foo, not -Wfoo when describing long options Use "Bell Laboratories", but not "Bell Labs". Use "behavior" instead of "behaviour". + Use "coprocess" instead of "co-process". Use "zeros" instead of "zeroes". Use "nonzero" not "non-zero". Use "runtime" not "run time" or "run-time". @@ -41494,4 +41991,3 @@ But to use it you have to say which sorta sucks. TODO: ------ diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 0ba31813..875893f1 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -32,11 +32,13 @@ @ifnotdocbook @set BULLET @bullet{} @set MINUS @minus{} +@set NUL @sc{nul} @end ifnotdocbook @ifdocbook @set BULLET @set MINUS +@set NUL NUL @end ifdocbook @set xref-automatic-section-title @@ -46,11 +48,16 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH August, 2014 +@set UPDATE-MONTH September, 2014 @set VERSION 4.1 -@set PATCHLEVEL 1 +@set PATCHLEVEL 2 +@ifset FOR_PRINT +@set TITLE Effective AWK Programming +@end ifset +@ifclear FOR_PRINT @set TITLE GAWK: Effective AWK Programming +@end ifclear @set SUBTITLE A User's Guide for GNU Awk @set EDITION 4.1 @@ -160,6 +167,19 @@ @end macro @end ifdocbook +@c hack for docbook, where comma shouldn't always follow an @ref{} +@ifdocbook +@macro DBREF{text} +@ref{\text\} +@end macro +@end ifdocbook + +@ifnotdocbook +@macro DBREF{text} +@ref{\text\}, +@end macro +@end ifnotdocbook + @ifclear FOR_PRINT @set FN file name @set FFN File Name @@ -521,10 +541,10 @@ particular records in a file and perform operations upon them. * Escape Sequences:: How to write nonprinting characters. * Regexp Operators:: Regular Expression Operators. * Bracket Expressions:: What can go between @samp{[...]}. -* GNU Regexp Operators:: Operators specific to GNU software. -* Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* GNU Regexp Operators:: Operators specific to GNU software. +* Case-sensitivity:: How to do case-insensitive matching. * Regexp Summary:: Regular expressions summary. * Records:: Controlling how data is split into records. @@ -540,8 +560,8 @@ particular records in a file and perform operations upon them. * Regexp Field Splitting:: Using regexps as the field separator. * Single Character Fields:: Making each character a separate field. -* Command Line Field Separator:: Setting @code{FS} from the - command line. +* Command Line Field Separator:: Setting @code{FS} from the command + line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -585,17 +605,19 @@ particular records in a file and perform operations upon them. * Printf Examples:: Several examples. * Redirection:: How to redirect output to multiple files and pipes. +* Special FD:: Special files for I/O. * Special Files:: File name interpretation in @command{gawk}. @command{gawk} allows access to inherited file descriptors. -* Special FD:: Special files for I/O. +* Other Inherited Files:: Accessing other open files with + @command{gawk}. * Special Network:: Special files for network communications. * Special Caveats:: Things to watch out for. * Close Files And Pipes:: Closing Input and Output Files and Pipes. * Output Summary:: Output summary. -* Output exercises:: Exercises. +* Output Exercises:: Exercises. * Values:: Constants, Variables, and Regular Expressions. * Constants:: String, numeric and regexp constants. @@ -681,7 +703,7 @@ particular records in a file and perform operations upon them. record. * Nextfile Statement:: Stop processing the current file. * Exit Statement:: Stop execution of @command{awk}. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * User-modified:: Built-in variables that you change to control @command{awk}. * Auto-set:: Built-in variables where @command{awk} @@ -701,12 +723,12 @@ particular records in a file and perform operations upon them. elements. * Controlling Scanning:: Controlling the order in which arrays are scanned. -* Delete:: The @code{delete} statement removes an - element from an array. * Numeric Array Subscripts:: How to use numbers as subscripts in @command{awk}. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. +* Delete:: The @code{delete} statement removes an + element from an array. * Multidimensional:: Emulating multidimensional arrays in @command{awk}. * Multiscanning:: Scanning multidimensional arrays. @@ -765,6 +787,8 @@ particular records in a file and perform operations upon them. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the + shell. * Data File Management:: Functions for managing command-line data files. * Filetrans Function:: A function for handling data file @@ -782,7 +806,7 @@ particular records in a file and perform operations upon them. information. * Walking Arrays:: A function to walk arrays of arrays. * Library Functions Summary:: Summary of library functions. -* Library exercises:: Exercises. +* Library Exercises:: Exercises. * Running Examples:: How to run these examples. * Clones:: Clones of common utilities. * Cut Program:: The @command{cut} utility. @@ -879,7 +903,6 @@ particular records in a file and perform operations upon them. * Extension API Description:: A full description of the API. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @@ -892,6 +915,7 @@ particular records in a file and perform operations upon them. * Two-way processors:: Registering a two-way processor. * Printing Messages:: Functions for printing messages. * Updating @code{ERRNO}:: Functions for updating @code{ERRNO}. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -930,9 +954,9 @@ particular records in a file and perform operations upon them. processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to @code{gettimeofday()} and @code{sleep()}. +* Extension Sample API Tests:: Tests for the API. * gawkextlib:: The @code{gawkextlib} project. * Extension summary:: Extension summary. * Extension Exercises:: Exercises. @@ -1068,7 +1092,7 @@ 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 input and then perform an action---often reduced complex or tedious -data manipulations to few lines of code. I was excited to try my +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 @@ -1202,7 +1226,7 @@ March, 2001 <affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation> <affiliation><jobtitle>ISRAEL</jobtitle></affiliation> </author> - <date>June, 2014</date> + <date>December, 2014</date> </prefaceinfo> @end docbook @@ -1215,8 +1239,7 @@ 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 -(@pxref{Options}), it is fully -compatible with +it is fully compatible with the POSIX@footnote{The 2008 POSIX standard is accessible online at @w{@url{http://www.opengroup.org/onlinepubs/9699919799/}.}} specification of the @command{awk} language @@ -1224,7 +1247,7 @@ and with the Unix version of @command{awk} maintained by Brian Kernighan. This means that all properly written @command{awk} programs should work with @command{gawk}. -Thus, we usually don't distinguish between @command{gawk} and other +So most of the time, we don't distinguish between @command{gawk} and other @command{awk} implementations. @cindex @command{awk}, POSIX and, See Also POSIX @command{awk} @@ -1233,7 +1256,7 @@ Thus, we usually don't distinguish between @command{gawk} and other @cindex @command{gawk}, @command{awk} and @cindex @command{awk}, @command{gawk} and @cindex @command{awk}, uses for -Using @command{awk} allows you to: +Using @command{awk} you can: @itemize @value{BULLET} @item @@ -1271,15 +1294,15 @@ Sort data Perform simple network communications @item -Profile and debug @command{awk} programs. +Profile and debug @command{awk} programs @item -Extend the language with functions written in C or C++. +Extend the language with functions written in C or C++ @end itemize This @value{DOCUMENT} teaches you about the @command{awk} language and how you can use it effectively. You should already be familiar with basic -system commands, such as @command{cat} and @command{ls},@footnote{These commands +system commands, such as @command{cat} and @command{ls},@footnote{These utilities are available on POSIX-compliant systems, as well as on traditional Unix-based systems. If you are using some other operating system, you still need to be familiar with the ideas of I/O redirection and pipes.} as well as basic shell @@ -1301,10 +1324,9 @@ Microsoft Windows @ifclear FOR_PRINT (all versions) and OS/2 PCs, @end ifclear -and OpenVMS. -(Some other, obsolete systems to which @command{gawk} was once ported -are no longer supported and the code for those systems -has been removed.) +and OpenVMS.@footnote{Some other, obsolete systems to which @command{gawk} +was once ported are no longer supported and the code for those systems +has been removed.} @menu * History:: The history of @command{gawk} and @@ -1353,13 +1375,13 @@ The version in System V Release 4 (1989) added some new features and cleaned up the behavior in some of the ``dark corners'' of the language. The specification for @command{awk} in the POSIX Command Language and Utilities standard further clarified the language. -Both the @command{gawk} designers and the original Bell Laboratories @command{awk} -designers provided feedback for the POSIX specification. +Both the @command{gawk} designers and the original @command{awk} designers at Bell Laboratories +provided feedback for the POSIX specification. @cindex Rubin, Paul @cindex Fenlason, Jay @cindex Trueman, David -Paul Rubin wrote the GNU implementation, @command{gawk}, in 1986. +Paul Rubin wrote @command{gawk} in 1986. Jay Fenlason completed it, with advice from Richard Stallman. John Woods contributed parts of the code as well. In 1988 and 1989, David Trueman, with help from me, thoroughly reworked @command{gawk} for compatibility @@ -1382,7 +1404,7 @@ an @command{awk}-level debugger. This version became available as @command{gawk} @value{PVERSION} 4.0, in 2011. @xref{Contributors}, -for a complete list of those who made important contributions to @command{gawk}. +for a full list of those who made important contributions to @command{gawk}. @node Names @unnumberedsec A Rose by Any Other Name @@ -1391,29 +1413,27 @@ for a complete 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}'' (@command{nawk}). +is often referred to as ``new @command{awk}''. +By analogy, the original version of @command{awk} is +referred to as ``old @command{awk}.'' -@cindex @command{awk}, versions of -@cindex @command{nawk} utility -@cindex @command{oawk} utility -For some time after new @command{awk} was introduced, there were -systems with multiple versions of @command{awk}. Some systems had -an @command{awk} utility that implemented the original version of the -@command{awk} language and a @command{nawk} utility for the new version. -Others had an @command{oawk} version for the ``old @command{awk}'' -language and plain @command{awk} for the new one. Still others only -had one version, which is usually the new one. - -Today, only Solaris systems still use an old @command{awk} for the -default @command{awk} utility. (A more modern @command{awk} lives in -@file{/usr/xpg6/bin} on these systems.) All other modern systems use -some version of new @command{awk}.@footnote{Many of these systems use -@command{gawk} for their @command{awk} implementation!} - -It is likely that you already have some version of new @command{awk} on -your system, which is what you should use when running your programs. -(Of course, if you're reading this @value{DOCUMENT}, chances are good -that you have @command{gawk}!) +Today, on most systems, when you run the @command{awk} utility, +you get some version of new @command{awk}.@footnote{Only +Solaris systems still use an old @command{awk} for the +default @command{awk} utility. A more modern @command{awk} lives in +@file{/usr/xpg6/bin} on these systems.} If your system's standard +@command{awk} is the old one, you will see something like this +if you try the test program: + +@example +$ @kbd{awk 1 /dev/null} +@error{} awk: syntax error near line 1 +@error{} awk: bailing out near line 1 +@end example + +@noindent +In this case, you should find a version of new @command{awk}, +or just install @command{gawk}! Throughout this @value{DOCUMENT}, whenever we refer to a language feature that should be available in any complete implementation of POSIX @command{awk}, @@ -1450,8 +1470,8 @@ entry ``differences in @command{awk} and @command{gawk}.''} @ifset FOR_PRINT implementations. @end ifset -Finally, any @command{gawk} features that are not in -the POSIX standard for @command{awk} are noted. +Finally, it notes any @command{gawk} features that are not in +the POSIX standard for @command{awk}. @ifnotinfo This @value{DOCUMENT} has the difficult task of being both a tutorial and a reference. @@ -1464,11 +1484,13 @@ There are sidebars scattered throughout the @value{DOCUMENT}. They add a more complete explanation of points that are relevant, but not likely to be of interest on first reading. +@ifclear FOR_PRINT All appear in the index, under the heading ``sidebar.'' +@end ifclear 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 currently being described. +program that illustrates the concept being described. While this @value{DOCUMENT} is aimed principally at people who have not been exposed @@ -1516,7 +1538,7 @@ for getting most things done in a program. @ref{Patterns and Actions}, describes how to write patterns for matching records, actions for -doing something when a record is matched, and the built-in variables +doing something when a record is matched, and the predefined variables @command{awk} and @command{gawk} use. @ref{Arrays}, @@ -1526,9 +1548,9 @@ sorting arrays in @command{gawk}. It also describes how @command{gawk} provides arrays of arrays. @ref{Functions}, -describes the built-in functions @command{awk} and -@command{gawk} provide, as well as how to define -your own 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. 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. @@ -1547,21 +1569,21 @@ Part III focuses on features specific to @command{gawk}. It contains the following chapters: @ref{Advanced Features}, -describes a number of @command{gawk}-specific advanced features. +describes a number of advanced features. Of particular note -are the abilities to have two-way communications with another process, +are the abilities to control the order of array traversal, +have two-way communications with another process, perform TCP/IP networking, and profile your @command{awk} programs. @ref{Internationalization}, -describes special features in @command{gawk} for translating program +describes special features for translating program messages into different languages at runtime. -@ref{Debugger}, describes the @command{awk} debugger. +@ref{Debugger}, describes the @command{gawk} debugger. @ref{Arbitrary Precision Arithmetic}, -describes advanced arithmetic facilities provided by -@command{gawk}. +describes advanced arithmetic facilities. @ref{Dynamic Extensions}, describes how to add new variables and functions to @command{gawk} by writing extensions in C or C++. @@ -1601,9 +1623,10 @@ printed edition. You may find them online, as follows: @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, as -well as how to contribute new code to @command{gawk}, -and some possible future directions for @command{gawk} development. +describes how to disable @command{gawk}'s extensions, how to contribute +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. @uref{http://www.gnu.org/software/gawk/manual/html_node/Basic-Concepts.html, The appendix on basic concepts} @@ -1619,6 +1642,9 @@ try looking them up here. @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}. + +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 @@ -1740,9 +1766,10 @@ the picture of a flashlight in the margin, as shown here. They also appear in the index under the heading ``dark corner.'' @end ifclear -As noted by the opening quote, though, any coverage of dark corners is, -by definition, incomplete. +But, as noted by the opening quote, any coverage of dark +corners is by definition incomplete. +@cindex c.e., See common extensions Extensions to the standard @command{awk} language that are supported by more than one @command{awk} implementation are marked @ifclear FOR_PRINT @@ -1814,9 +1841,7 @@ available for download from the Internet. @ifnotinfo The @value{DOCUMENT} you are reading is actually free---at least, the information in it is free to anyone. The machine-readable -source code for the @value{DOCUMENT} comes with @command{gawk}; anyone -may take this @value{DOCUMENT} to a copying machine and make as many -copies as they like. +source code for the @value{DOCUMENT} comes with @command{gawk}. @ifclear FOR_PRINT (Take a moment to check the Free Documentation License in @ref{GNU Free Documentation License}.) @@ -1824,7 +1849,7 @@ License in @ref{GNU Free Documentation License}.) @end ifnotinfo @cindex Close, Diane -The @value{DOCUMENT} itself has gone through a number of previous editions. +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. Diane Close and Richard Stallman improved it, yielding a @@ -1840,15 +1865,14 @@ The FSF published the first two editions under the title @cite{The GNU Awk User's Guide}. @ifset FOR_PRINT SSC published two editions of the @value{DOCUMENT} under the -title @cite{Effective awk Programming}, and in O'Reilly published +title @cite{Effective awk Programming}, and O'Reilly published the third edition in 2001. @end ifset This edition maintains the basic structure of the previous editions. -For FSF edition 4.0, the content has been thoroughly reviewed -and updated. All references to @command{gawk} versions prior to 4.0 have been -removed. -Of significant note for this edition was @ref{Debugger}. +For FSF edition 4.0, the content was thoroughly reviewed and updated. All +references to @command{gawk} versions prior to 4.0 were removed. +Of significant note for that edition was @ref{Debugger}. For FSF edition @ifclear FOR_PRINT @@ -1862,8 +1886,7 @@ the content has been reorganized into parts, and the major new additions are @ref{Arbitrary Precision Arithmetic}, and @ref{Dynamic Extensions}. -This @value{DOCUMENT} will undoubtedly continue to evolve. An electronic -version comes with the @command{gawk} distribution from the FSF. If you +This @value{DOCUMENT} will undoubtedly continue to evolve. If you find an error in this @value{DOCUMENT}, please report it! @xref{Bugs}, for information on submitting problem reports electronically. @@ -1872,7 +1895,7 @@ for information on submitting problem reports electronically. @unnumberedsec How to Stay Current It may be you have a version of @command{gawk} which is newer than the -one described in this @value{DOCUMENT}. To find out what has changed, +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 each release. @@ -2044,15 +2067,24 @@ Andrew Schorr, Corinna Vinschen, and Eli Zaretskii (in alphabetical order) -make up the current -@command{gawk} ``crack portability team.'' Without their hard work and -help, @command{gawk} would not be nearly the fine program it is today. It -has been and continues to be a pleasure working with this team of fine -people. +make up the current @command{gawk} ``crack portability team.'' Without +their hard work and help, @command{gawk} would not be nearly the robust, +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. +@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. +@end ifset + +Thanks to Michael Brennan for the Foreword. + +@cindex Duman, Patrice +@cindex Berry, Karl Thanks to Patrice Dumas for the new @command{makeinfo} program. Thanks to Karl Berry who continues to work to keep the Texinfo markup language sane. @@ -2094,7 +2126,7 @@ take advantage of those opportunities. Arnold Robbins @* Nof Ayalon @* ISRAEL @* -May, 2014 +December, 2014 @end iftex @ifnotinfo @@ -2310,27 +2342,22 @@ For example, on OS/2, it is @kbd{Ctrl-z}.) As an example, the following program prints a friendly piece of advice (from Douglas Adams's @cite{The Hitchhiker's Guide to the Galaxy}), to keep you from worrying about the complexities of computer -programming (@code{BEGIN} is a feature we haven't discussed yet): +programming: @example -$ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} +$ @kbd{awk 'BEGIN @{ print "Don\47t Panic!" @}'} @print{} Don't Panic! @end example -@cindex shell quoting, double quote -@cindex double quote (@code{"}) in shell commands -@cindex @code{"} (double quote) in shell commands -@cindex @code{\} (backslash) in shell commands -@cindex backslash (@code{\}) in shell commands -This program does not read any input. The @samp{\} before each of the -inner double quotes is necessary because of the shell's quoting -rules---in particular because it mixes both single quotes and -double quotes.@footnote{Although we generally recommend the use of single -quotes around the program text, double quotes are needed here in order to -put the single quote into the message.} +@command{awk} executes statements associated with @code{BEGIN} before +reading any input. If there are no other statements in your program, +as is the case here, @command{awk} just stops, instead of trying to read +input it doesn't know how to process. +The @samp{\47} is a magic way (explained later) of getting a single quote into +the program, without having to engage in ugly shell quoting tricks. @quotation NOTE -As a side note, if you use Bash as your shell, you should execute the +If you use Bash as your shell, you should execute the command @samp{set +H} before running this program interactively, to disable the C shell-style command history, which treats @samp{!} as a special character. We recommend putting this command into your personal @@ -2360,7 +2387,7 @@ $ @kbd{awk '@{ print @}'} @cindex @command{awk} programs, running @cindex @command{awk} programs, lengthy @cindex files, @command{awk} programs in -Sometimes your @command{awk} programs can be very long. In this case, it is +Sometimes @command{awk} programs are very long. In these cases, it is more convenient to put the program into a separate file. In order to tell @command{awk} to use that file for its program, you type: @@ -2390,7 +2417,7 @@ awk -f advice does the same thing as this one: @example -awk "BEGIN @{ print \"Don't Panic!\" @}" +awk 'BEGIN @{ print "Don\47t Panic!" @}' @end example @cindex quoting in @command{gawk} command lines @@ -2402,6 +2429,8 @@ specify with @option{-f}, because most @value{FN}s don't contain any of the shel special characters. Notice that in @file{advice}, the @command{awk} program did not have single quotes around it. The quotes are only needed for programs that are provided on the @command{awk} command line. +(Also, placing the program in a file allows us to use a literal single quote in the program +text, instead of the magic @samp{\47}.) @c STARTOFRANGE sq1x @cindex single quote (@code{'}) in @command{gawk} command lines @@ -2434,16 +2463,7 @@ BEGIN @{ print "Don't Panic!" @} @noindent After making this file executable (with the @command{chmod} utility), simply type @samp{advice} -at the shell and the system arranges to run @command{awk}@footnote{The -line beginning with @samp{#!} lists the full @value{FN} of an interpreter -to run and a single optional initial command-line argument to pass to that -interpreter. The operating system then runs the interpreter with the given -argument and the full argument list of the executed program. The first argument -in the list is the full @value{FN} of the @command{awk} program. -The rest of the -argument list contains either options to @command{awk}, or @value{DF}s, -or both. Note that on many systems @command{awk} may be found in -@file{/usr/bin} instead of in @file{/bin}. Caveat Emptor.} as if you had +at the shell and the system arranges to run @command{awk} as if you had typed @samp{awk -f advice}: @example @@ -2461,9 +2481,27 @@ Self-contained @command{awk} scripts are useful when you want to write a program that users can invoke without their having to know that the program is written in @command{awk}. -@sidebar Portability Issues with @samp{#!} +@sidebar Understanding @samp{#!} @cindex portability, @code{#!} (executable scripts) +@command{awk} is an @dfn{interpreted} language. This means that the +@command{awk} utility reads your program and then processes your data +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. + +The line beginning with @samp{#!} lists the full @value{FN} of an +interpreter to run and a single optional initial command-line argument +to pass to that interpreter. The operating system then runs the +interpreter with the given argument and the full argument list of the +executed program. The first argument in the list is the full @value{FN} +of the @command{awk} program. The rest of the argument list contains +either options to @command{awk}, or @value{DF}s, or both. (Note that on +many systems @command{awk} may be found in @file{/usr/bin} instead of +in @file{/bin}.) + Some systems limit the length of the interpreter name to 32 characters. Often, this can be dealt with by using a symbolic link. @@ -2475,8 +2513,7 @@ of some sort from @command{awk}. @cindex @code{ARGC}/@code{ARGV} variables, portability and @cindex portability, @code{ARGV} variable -Finally, -the value of @code{ARGV[0]} +Finally, the value of @code{ARGV[0]} (@pxref{Built-in Variables}) varies depending upon your operating system. Some systems put @samp{awk} there, some put the full pathname @@ -2641,8 +2678,14 @@ Thus, the example seen @ifnotinfo previously @end ifnotinfo -in @ref{Read Terminal}, -is applicable: +in @ref{Read Terminal}: + +@example +awk 'BEGIN @{ print "Don\47t Panic!" @}' +@end example + +@noindent +could instead be written this way: @example $ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} @@ -2672,7 +2715,7 @@ awk -F"" '@var{program}' @var{files} # wrong! @end example @noindent -In the second case, @command{awk} will attempt to use the text of the program +In the second case, @command{awk} attempts to use the text of the program as the value of @code{FS}, and the first @value{FN} as the text of the program! This results in syntax errors at best, and confusing behavior at worst. @end itemize @@ -2737,6 +2780,9 @@ $ awk -v sq="'" 'BEGIN @{ print "Here is a single quote <" sq ">" @}' @print{} Here is a single quote <'> @end example +(Here, the two string constants and the value of @code{sq} are concatenated +into a single string which is printed by @code{print}.) + If you really need both single and double quotes in your @command{awk} program, it is probably best to move it into a separate file, where the shell won't be part of the picture, and you can say what you mean. @@ -2800,7 +2846,7 @@ The second @value{DF}, called @file{inventory-shipped}, contains information about monthly shipments. In both files, each line is considered to be one @dfn{record}. -In the @value{DF} @file{mail-list}, each record contains the name of a person, +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 with the author of the list. The columns are aligned using spaces. @@ -2838,6 +2884,7 @@ of green crates shipped, the number of red boxes shipped, the number of orange bags shipped, and the number of blue packages shipped, respectively. There are 16 entries, covering the 12 months of last year and the first four months of the current year. +An empty line separates the data for the two years. @example @c file eg/data/inventory-shipped @@ -2933,22 +2980,25 @@ you can come up with different ways to do the same things shown here: @itemize @value{BULLET} @item -Print the length of the longest input line: +Print every line that is longer than 80 characters: @example -awk '@{ if (length($0) > max) max = length($0) @} - END @{ print max @}' data +awk 'length($0) > 80' data @end example +The sole rule has a relational expression as its pattern and it has no +action---so it uses the default action, printing the record. + @item -Print every line that is longer than 80 characters: +Print the length of the longest input line: @example -awk 'length($0) > 80' data +awk '@{ if (length($0) > max) max = length($0) @} + END @{ print max @}' data @end example -The sole rule has a relational expression as its pattern and it has no -action---so it uses the default action, printing the record. +The code associated with @code{END} executes after all +input has been read; it's the other side of the coin to @code{BEGIN}. @cindex @command{expand} utility @item @@ -2956,10 +3006,10 @@ Print the length of the longest line in @file{data}: @example expand data | awk '@{ if (x < length($0)) x = length($0) @} - END @{ print "maximum line length is " x @}' + END @{ print "maximum line length is " x @}' @end example -This example differs slightly from the first example in this list: +This example differs slightly from the previous one: 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. @@ -2988,7 +3038,7 @@ Print the total number of bytes used by @var{files}: @example ls -l @var{files} | awk '@{ x += $5 @} - END @{ print "total bytes: " x @}' + END @{ print "total bytes: " x @}' @end example @item @@ -3032,7 +3082,7 @@ the program would print the odd-numbered lines. @cindex @command{awk} programs The @command{awk} utility reads the input files one line at a -time. For each line, @command{awk} tries the patterns of each of the rules. +time. For each line, @command{awk} tries the patterns of each rule. If several patterns match, then several actions execute in the order in which they appear in the @command{awk} program. If no patterns match, then no actions run. @@ -3040,7 +3090,7 @@ no actions run. After processing all the rules that match the line (and perhaps there are none), @command{awk} reads the next line. (However, @pxref{Next Statement}, -and also @pxref{Nextfile Statement}). +and also @pxref{Nextfile Statement}.) This continues until the program reaches the end of the file. For example, the following @command{awk} program contains two rules: @@ -3089,8 +3139,8 @@ features that haven't been covered yet, so don't worry if you don't understand all the details: @example -LC_ALL=C ls -l | awk '$6 == "Nov" @{ sum += $5 @} - END @{ print sum @}' +ls -l | awk '$6 == "Nov" @{ sum += $5 @} + END @{ print sum @}' @end example @cindex @command{ls} utility @@ -3114,13 +3164,12 @@ the file was last modified. Its output looks like this: @noindent @cindex line continuations, with C shell The first field contains read-write permissions, the second field contains -the number of links to the file, and the third field identifies the owner of -the file. The fourth field identifies the group of the file. -The fifth field contains the size of the file in bytes. The +the number of links to the file, and the third field identifies the file's owner. +The fourth field identifies the file's group. +The fifth field contains the file's size in bytes. The sixth, seventh, and eighth fields contain the month, day, and time, respectively, that the file was last modified. Finally, the ninth field -contains the @value{FN}.@footnote{The @samp{LC_ALL=C} is -needed to produce this traditional-style output from @command{ls}.} +contains the @value{FN}. @c @cindex automatic initialization @cindex initialization, automatic @@ -3308,7 +3357,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 +systematically in @ref{Built-in Variables}, and in @ref{Built-in}. @node When @@ -3343,9 +3392,7 @@ eight-bit microprocessors, 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. Even BWK @command{awk} -has fewer predefined limits, and those -that it has are much larger than they used to be. +of such complexity, modern versions are more capable. @cindex @command{awk} programs, complex If you find yourself writing @command{awk} scripts of more than, say, @@ -3359,11 +3406,16 @@ and Perl.} @node Intro Summary @section Summary +@c FIXME: Review this chapter for summary of builtin functions called. @itemize @value{BULLET} @item Programs in @command{awk} consist of @var{pattern}-@var{action} pairs. @item +An @var{action} without a @var{pattern} always runs. The default +@var{action} for a pattern without one is @samp{@{ print $0 @}}. + +@item Use either @samp{awk '@var{program}' @var{files}} or @@ -3521,13 +3573,13 @@ The @option{-v} option can only set one variable, but it can be used more than once, setting another variable each time, like this: @samp{awk @w{-v foo=1} @w{-v bar=2} @dots{}}. -@cindex built-in variables, @code{-v} option@comma{} setting with -@cindex variables, built-in, @code{-v} option@comma{} setting with +@cindex predefined variables, @code{-v} option@comma{} setting with +@cindex variables, predefined @code{-v} option@comma{} setting with @quotation CAUTION Using @option{-v} to set the values of the built-in variables may lead to surprising results. @command{awk} will reset the values of those variables as it needs to, possibly ignoring any -predefined value you may have given. +initial value you may have given. @end quotation @item -W @var{gawk-opt} @@ -3610,7 +3662,7 @@ Print the short version of the General Public License and then exit. @cindex variables, global, printing list of Print a sorted list of global variables, their types, and final values to @var{file}. If no @var{file} is provided, print this -list to the file named @file{awkvars.out} in the current directory. +list to a file named @file{awkvars.out} in the current directory. No space is allowed between the @option{-d} and @var{file}, if @var{file} is supplied. @@ -3706,7 +3758,7 @@ that @command{gawk} accepts and then exit. @cindex @option{-i} option @cindex @option{--include} option @cindex @command{awk} programs, location of -Read @command{awk} source library from @var{source-file}. This option +Read an @command{awk} source library from @var{source-file}. This option is completely equivalent to using the @code{@@include} directive inside your program. This option is very similar to the @option{-f} option, but there are two important differences. First, when @option{-i} is @@ -3730,7 +3782,7 @@ environment variable. The correct library suffix for your platform will be supplied by default, so it need not be specified in the extension name. The extension initialization routine should be named @code{dl_load()}. An alternative is to use the @code{@@load} keyword inside the program to load -a shared library. This feature is described in detail in @ref{Dynamic Extensions}. +a shared library. This advanced feature is described in detail in @ref{Dynamic Extensions}. @item @option{-L}[@var{value}] @itemx @option{--lint}[@code{=}@var{value}] @@ -3779,6 +3831,8 @@ values in input data @quotation CAUTION This option can severely break old programs. Use with care. + +This option may disappear in a future version of @command{gawk}. @end quotation @item @option{-N} @@ -3942,6 +3996,7 @@ 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. +The @option{-i} option is similar in this regard. (As mentioned in @ref{Definition Syntax}, function names must be unique.) @@ -4015,15 +4070,18 @@ Any additional arguments on the command line are normally treated as input files to be processed in the order specified. However, an argument that has the form @code{@var{var}=@var{value}}, assigns the value @var{value} to the variable @var{var}---it does not specify a -file at all. -(See -@ref{Assignment Options}.) +file at all. (See @ref{Assignment Options}.) In the following example, +@var{count=1} is a variable assignment, not a @value{FN}: + +@example +awk -f program.awk file1 count=1 file2 +@end example @cindex @command{gawk}, @code{ARGIND} variable in @cindex @code{ARGIND} variable, command-line arguments @cindex @code{ARGV} array, indexing into @cindex @code{ARGC}/@code{ARGV} variables, command-line arguments -All these arguments are made available to your @command{awk} program in the +All the command-line arguments are made available to your @command{awk} program in the @code{ARGV} array (@pxref{Built-in Variables}). Command-line options and the program text (if present) are omitted from @code{ARGV}. All other arguments, including variable assignments, are @@ -4031,6 +4089,11 @@ included. As each element of @code{ARGV} is processed, @command{gawk} sets the variable @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. +Changing @code{ARGC} and @code{ARGV} in your @command{awk} program lets +you control how @command{awk} processes the input files; this is described +in more detail in @ref{ARGC and ARGV}. + @cindex input files, variable assignments and @cindex variable assignments and input files The distinction between @value{FN} arguments and variable-assignment @@ -4149,15 +4212,15 @@ separated by colons@footnote{Semicolons on MS-Windows and MS-DOS.}. @command{ga @samp{.:/usr/local/share/awk}.@footnote{Your version of @command{gawk} may use a different directory; it will depend upon how @command{gawk} was built and installed. The actual -directory is the value of @samp{$(datadir)} generated when +directory is the value of @code{$(datadir)} generated when @command{gawk} was configured. You probably don't need to worry about this, though.} The search path feature is particularly helpful for building libraries of useful @command{awk} functions. The library files can be placed in a standard directory in the default path and then specified on -the command line with a short @value{FN}. Otherwise, the full @value{FN} -would have to be typed for each file. +the command line with a short @value{FN}. Otherwise, you would have to +type the full @value{FN} for each file. By using the @option{-i} option, or the @option{-e} and @option{-f} options, your command-line @command{awk} programs can use facilities in @command{awk} library files @@ -4166,25 +4229,23 @@ Path searching is not done if @command{gawk} is in compatibility mode. This is true for both @option{--traditional} and @option{--posix}. @xref{Options}. -If the source code is not found after the initial search, the path is searched +If the source code file is not found after the initial search, the path is searched again after adding the default @samp{.awk} suffix to the @value{FN}. -@quotation NOTE -@c 4/2014: -@c using @samp{.} to get quotes, since @file{} no longer supplies them. -To include -the current directory in the path, either place -@samp{.} explicitly in the path or write a null entry in the -path. (A null entry is indicated by starting or ending the path with a -colon or by placing two colons next to each other [@samp{::}].) -This path search mechanism is similar +@command{gawk}'s path search mechanism is similar to the shell's. (See @uref{http://www.gnu.org/software/bash/manual/, -@cite{The Bourne-Again SHell manual}.}) +@cite{The Bourne-Again SHell manual}}.) +It treats a null entry in the path as indicating the current +directory. +(A null entry is indicated by starting or ending the path with a +colon or by placing two colons next to each other [@samp{::}].) -However, @command{gawk} always looks in the current directory @emph{before} -searching @env{AWKPATH}, so there is no real reason to include -the current directory in the search path. +@quotation NOTE +@command{gawk} always looks in the current directory @emph{before} +searching @env{AWKPATH}. Thus, while you can include the current directory +in the search path, either explicitly or with a null entry, there is no +real reason to do so. @c Prior to 4.0, gawk searched the current directory after the @c path search, but it's not worth documenting it. @end quotation @@ -4225,16 +4286,6 @@ behavior, but they are more specialized. Those in the following list are meant to be used by regular users. @table @env -@item POSIXLY_CORRECT -Causes @command{gawk} to switch to POSIX compatibility -mode, disabling all traditional and GNU extensions. -@xref{Options}. - -@item GAWK_SOCK_RETRIES -Controls the number of times @command{gawk} attempts to -retry a two-way TCP/IP (socket) connection before giving up. -@xref{TCP/IP Networking}. - @item GAWK_MSEC_SLEEP Specifies the interval between connection retries, in milliseconds. On systems that do not support @@ -4245,6 +4296,16 @@ the value is rounded up to an integral number of seconds. Specifies the time, in milliseconds, for @command{gawk} to wait for input before returning with an error. @xref{Read Timeout}. + +@item GAWK_SOCK_RETRIES +Controls the number of times @command{gawk} attempts to +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 +mode, disabling all traditional and GNU extensions. +@xref{Options}. @end table The environment variables in the following list are meant @@ -4259,7 +4320,7 @@ file as the size of the memory buffer to allocate for I/O. Otherwise, the value should be a number, and @command{gawk} uses that number as the size of the buffer to allocate. (When this variable is not set, @command{gawk} uses the smaller of the file's size and the ``default'' -blocksize, which is usually the filesystems I/O blocksize.) +blocksize, which is usually the filesystem's I/O blocksize.) @item AWK_HASH If this variable exists with a value of @samp{gst}, @command{gawk} @@ -4274,10 +4335,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 source file -name and line number from which warning and/or fatal messages +If this variable exists, @command{gawk} includes the file +name 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 can be multiple places which produce the +message, since there are multiple places which produce the same warning or error message. @item GAWK_NO_DFA @@ -4293,11 +4355,11 @@ This specifies the amount by which @command{gawk} should grow its internal evaluation stack, when needed. @item INT_CHAIN_MAX -The average number of items @command{gawk} will maintain on a +The intended maximum number of items @command{gawk} will maintain on a hash chain for managing arrays indexed by integers. @item STR_CHAIN_MAX -The average number of items @command{gawk} will maintain on a +The intended maximum number of items @command{gawk} will maintain on a hash chain for managing arrays indexed by strings. @item TIDYMEM @@ -4332,6 +4394,9 @@ to @code{EXIT_FAILURE}. This @value{SECTION} describes a feature that is specific to @command{gawk}. +@cindex @code{@@include} directive +@cindex file inclusion, @code{@@include} directive +@cindex including files, @code{@@include} directive The @code{@@include} keyword can be used to read external @command{awk} source files. This gives you the ability to split large @command{awk} source files into smaller, more manageable pieces, and also lets you reuse common @command{awk} @@ -4367,8 +4432,8 @@ produces the following result: @example $ @kbd{gawk -f test2} -@print{} This is file test1. -@print{} This is file test2. +@print{} This is script test1. +@print{} This is script test2. @end example @code{gawk} runs the @file{test2} script which includes @file{test1} @@ -4398,9 +4463,9 @@ following results: @example $ @kbd{gawk -f test3} -@print{} This is file test1. -@print{} This is file test2. -@print{} This is file test3. +@print{} This is script test1. +@print{} This is script test2. +@print{} This is script test3. @end example The @value{FN} can, of course, be a pathname. For example: @@ -4451,6 +4516,9 @@ and this also applies to files named with @code{@@include}. This @value{SECTION} describes a feature that is specific to @command{gawk}. +@cindex @code{@@load} directive +@cindex loading extensions, @code{@@load} directive +@cindex extensions, loading, @code{@@load} directive 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 @@ -4484,6 +4552,7 @@ that requires access to an extension. @ref{Dynamic Extensions}, describes how to write extensions (in C or C++) that can be loaded with either @code{@@load} or the @option{-l} option. +It also describes the @code{ordchr} extension. @node Obsolete @section Obsolete Options and/or Features @@ -4552,15 +4621,15 @@ awk '@{ sum += $1 @} END @{ print sum @}' @end example @command{gawk} actually supports this but it is purposely undocumented -because it is considered bad style. The correct way to write such a program -is either +because it is bad style. The correct way to write such a program +is either: @example awk '@{ sum += $1 @} ; END @{ print sum @}' @end example @noindent -or +or: @example awk '@{ sum += $1 @} @@ -4568,8 +4637,7 @@ awk '@{ sum += $1 @} @end example @noindent -@xref{Statements/Lines}, for a fuller -explanation. +@xref{Statements/Lines}, for a fuller explanation. You can insert newlines after the @samp{;} in @code{for} loops. This seems to have been a long-undocumented feature in Unix @command{awk}. @@ -4609,7 +4677,8 @@ affects how @command{awk} processes input. @item You can use a single minus sign (@samp{-}) to refer to standard input -on the command line. +on the command line. @command{gawk} also lets you use the special +@value{FN} @file{/dev/stdin}. @item @command{gawk} pays attention to a number of environment variables. @@ -4652,7 +4721,7 @@ 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 -the three characters @samp{foo} @emph{anywhere} in the record. Other +the three adjacent characters @samp{foo} @emph{anywhere} in the record. Other kinds of regexps let you specify more complicated classes of strings. @ifnotinfo @@ -4666,10 +4735,10 @@ regular expressions work, we present more complicated instances. * Escape Sequences:: How to write nonprinting characters. * Regexp Operators:: Regular Expression Operators. * Bracket Expressions:: What can go between @samp{[...]}. -* GNU Regexp Operators:: Operators specific to GNU software. -* Case-sensitivity:: How to do case-insensitive matching. * Leftmost Longest:: How much text matches. * Computed Regexps:: Using Dynamic Regexps. +* GNU Regexp Operators:: Operators specific to GNU software. +* Case-sensitivity:: How to do case-insensitive matching. * Regexp Summary:: Regular expressions summary. @end menu @@ -4798,7 +4867,7 @@ such as TAB or newline. While there is nothing to stop you from entering most unprintable characters directly in a string constant or regexp constant, they may look ugly. -The following table lists +The following list presents all the escape sequences used in @command{awk} and what they represent. Unless noted otherwise, all these escape sequences apply to both string constants and regexp constants: @@ -4880,8 +4949,11 @@ However, using more than two hexadecimal digits produces @item \/ A literal slash (necessary for regexp constants only). This sequence is used when you want to write a regexp -constant that contains a slash. Because the regexp is delimited by -slashes, you need to escape the slash that is part of the pattern, +constant that contains a slash +(such as @code{/.*:\/home\/[[:alnum:]]+:.*/}; the @samp{[[:alnum:]]} +notation is discussed shortly, 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. @cindex @code{\} (backslash), @code{\"} escape sequence @@ -4889,8 +4961,10 @@ in order to tell @command{awk} to keep processing the rest of the regexp. @item \" A literal double quote (necessary for string constants only). This sequence is used when you want to write a string -constant that contains a double quote. Because the string is delimited by -double quotes, you need to escape the quote that is part of the string, +constant that contains a double quote +(such as @code{"He said \"hi!\" to her."}). +Because the string is delimited by +double quotes, you need to escape any quote that is part of the string, in order to tell @command{awk} to keep processing the rest of the string. @end table @@ -4909,13 +4983,13 @@ characters @samp{a+b}. @cindex @code{\} (backslash), in escape sequences @cindex portability For complete portability, do not use a backslash before any character not -shown in the previous list. +shown in the previous list and that is not an operator. To summarize: @itemize @value{BULLET} @item -The escape sequences in the table above are always processed first, +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. @@ -4999,13 +5073,13 @@ The escape sequences described @ifnotinfo earlier @end ifnotinfo -in @ref{Escape Sequences}, +in @DBREF{Escape Sequences} are valid inside a regexp. They are introduced by a @samp{\} and are recognized and converted into corresponding real characters as the very first step in processing regexps. Here is a list of metacharacters. All characters that are not escape -sequences and that are not listed in the table stand for themselves: +sequences and that are not listed in the following stand for themselves: @c Use @asis so the docbook comes out ok. Sigh. @table @asis @@ -5062,10 +5136,10 @@ with @samp{A}. @cindex POSIX @command{awk}, period (@code{.})@comma{} using In strict POSIX mode (@pxref{Options}), -@samp{.} does not match the @sc{nul} +@samp{.} does not match the @value{NUL} character, which is a character with all bits equal to zero. -Otherwise, @sc{nul} is just another character. Other versions of @command{awk} -may not be able to match the @sc{nul} character. +Otherwise, @value{NUL} is just another character. Other versions of @command{awk} +may not be able to match the @value{NUL} character. @cindex @code{[]} (square brackets), regexp operator @cindex square brackets (@code{[]}), regexp operator @@ -5096,12 +5170,11 @@ or @samp{k}. @cindex vertical bar (@code{|}) @item @code{|} This is the @dfn{alternation operator} and it is used to specify -alternatives. -The @samp{|} has the lowest precedence of all the regular -expression operators. -For example, @samp{^P|[[:digit:]]} -matches any string that matches either @samp{^P} or @samp{[[:digit:]]}. This -means it matches any string that starts with @samp{P} or contains a digit. +alternatives. The @samp{|} has the lowest precedence of all the regular +expression operators. For example, @samp{^P|[aeiouy]} matches any string +that matches either @samp{^P} or @samp{[aeiouy]}. This means it matches +any string that starts with @samp{P} or contains (anywhere within it) +a lowercase English vowel. The alternation applies to the largest possible regexps on either side. @@ -5125,14 +5198,15 @@ applies the @samp{*} symbol to the preceding @samp{h} and looks for matches of one @samp{p} followed by any number of @samp{h}s. This also matches just @samp{p} if no @samp{h}s are present. -The @samp{*} repeats the @emph{smallest} possible preceding expression. -(Use parentheses if you want to repeat a larger expression.) It finds -as many repetitions as possible. For example, -@samp{awk '/\(c[ad][ad]*r x\)/ @{ print @}' sample} -prints every record in @file{sample} containing a string of the form -@samp{(car x)}, @samp{(cdr x)}, @samp{(cadr x)}, and so on. -Notice the escaping of the parentheses by preceding them -with backslashes. +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. + +Second, @samp{*} finds as many repetitions as possible. If the text +to be matched is @samp{phhhhhhhhhhhhhhooey}, @samp{ph*} matches all of +the @samp{h}s. @cindex @code{+} (plus sign), regexp operator @cindex plus sign (@code{+}), regexp operator @@ -5141,12 +5215,6 @@ This symbol is similar to @samp{*}, except that the preceding expression must be matched at least once. This means that @samp{wh+y} would match @samp{why} and @samp{whhy}, but not @samp{wy}, whereas @samp{wh*y} would match all three. -The following is a simpler -way of writing the last @samp{*} example: - -@example -awk '/\(c[ad]+r x\)/ @{ print @}' sample -@end example @cindex @code{?} (question mark), regexp operator @cindex question mark (@code{?}), regexp operator @@ -5241,7 +5309,7 @@ Within a bracket expression, a @dfn{range expression} consists of two characters separated by a hyphen. It matches any single character that sorts between the two characters, based upon the system's native character set. For example, @samp{[0-9]} is equivalent to @samp{[0123456789]}. -(See @ref{Ranges and Locales}, for an explanation of how the POSIX +(See @DBREF{Ranges and Locales} for an explanation of how the POSIX standard and @command{gawk} have changed over time. This is mainly of historical interest.) @@ -5260,12 +5328,15 @@ bracket expression, put a @samp{\} in front of it. For example: @noindent matches either @samp{d} or @samp{]}. +Additionally, if you place @samp{]} right after the opening +@samp{[}, the closing bracket is treated as one of the +characters to be matched. @cindex POSIX @command{awk}, bracket expressions and @cindex Extended Regular Expressions (EREs) @cindex EREs (Extended Regular Expressions) @cindex @command{egrep} utility -This treatment of @samp{\} in bracket expressions +The treatment of @samp{\} in bracket expressions is compatible with other @command{awk} implementations and is also mandated by POSIX. The regular expressions in @command{awk} are a superset @@ -5371,6 +5442,160 @@ they do not recognize collating symbols or equivalence classes. @c maybe one day ... @c ENDOFRANGE charlist +@node Leftmost Longest +@section How Much Text Matches? + +@cindex regular expressions, leftmost longest match +@c @cindex matching, leftmost longest +Consider the following: + +@example +echo aaaabcd | awk '@{ sub(/a+/, "<A>"); print @}' +@end example + +This example uses the @code{sub()} function to make a change to the input +record. (@code{sub()} replaces the first instance of any text matched +by the first argument with the string provided as the second argument; +@pxref{String Functions}). Here, the regexp @code{/a+/} indicates ``one +or more @samp{a} characters,'' and the replacement text is @samp{<A>}. + +The input contains four @samp{a} characters. +@command{awk} (and POSIX) regular expressions always match +the leftmost, @emph{longest} sequence of input characters that can +match. Thus, all four @samp{a} characters are +replaced with @samp{<A>} in this example: + +@example +$ @kbd{echo aaaabcd | awk '@{ sub(/a+/, "<A>"); print @}'} +@print{} <A>bcd +@end example + +For simple match/no-match tests, this is not so important. But when doing +text matching and substitutions with the @code{match()}, @code{sub()}, @code{gsub()}, +and @code{gensub()} functions, it is very important. +@ifinfo +@xref{String Functions}, +for more information on these functions. +@end ifinfo +Understanding this principle is also important for regexp-based record +and field splitting (@pxref{Records}, +and also @pxref{Field Separators}). + +@node Computed Regexps +@section Using Dynamic Regexps + +@c STARTOFRANGE dregexp +@cindex regular expressions, computed +@c STARTOFRANGE regexpd +@cindex regular expressions, dynamic +@cindex @code{~} (tilde), @code{~} operator +@cindex tilde (@code{~}), @code{~} operator +@cindex @code{!} (exclamation point), @code{!~} operator +@cindex exclamation point (@code{!}), @code{!~} operator +@c @cindex operators, @code{~} +@c @cindex operators, @code{!~} +The righthand side of a @samp{~} or @samp{!~} operator need not be a +regexp constant (i.e., a string of characters between slashes). It may +be any expression. The expression is evaluated and converted to a string +if necessary; the contents of the string are then used as the +regexp. A regexp computed in this way is called a @dfn{dynamic +regexp} or a @dfn{computed regexp}: + +@example +BEGIN @{ digits_regexp = "[[:digit:]]+" @} +$0 ~ digits_regexp @{ print @} +@end example + +@noindent +This sets @code{digits_regexp} to a regexp that describes one or more digits, +and tests whether the input record matches this regexp. + +@quotation NOTE +When using the @samp{~} and @samp{!~} +operators, there is a difference between a regexp constant +enclosed in slashes and a string constant enclosed in double quotes. +If you are going to use a string constant, you have to understand that +the string is, in essence, scanned @emph{twice}: the first time when +@command{awk} reads your program, and the second time when it goes to +match the string on the lefthand side of the operator with the pattern +on the right. This is true of any string-valued expression (such as +@code{digits_regexp}, shown previously), not just string constants. +@end quotation + +@cindex regexp constants, slashes vs.@: quotes +@cindex @code{\} (backslash), in regexp constants +@cindex backslash (@code{\}), in regexp constants +@cindex @code{"} (double quote), in regexp constants +@cindex double quote (@code{"}), in regexp constants +What difference does it make if the string is +scanned twice? The answer has to do with escape sequences, and particularly +with backslashes. To get a backslash into a regular expression inside a +string, you have to type two backslashes. + +For example, @code{/\*/} is a regexp constant for a literal @samp{*}. +Only one backslash is needed. To do the same thing with a string, +you have to type @code{"\\*"}. The first backslash escapes the +second one so that the string actually contains the +two characters @samp{\} and @samp{*}. + +@cindex troubleshooting, regexp constants vs.@: string constants +@cindex regexp constants, vs.@: string constants +@cindex string constants, vs.@: regexp constants +Given that you can use both regexp and string constants to describe +regular expressions, which should you use? The answer is ``regexp +constants,'' for several reasons: + +@itemize @value{BULLET} +@item +String constants are more complicated to write and +more difficult to read. Using regexp constants makes your programs +less error-prone. Not understanding the difference between the two +kinds of constants is a common source of errors. + +@item +It is more efficient to use regexp constants. @command{awk} can note +that you have supplied a regexp and store it internally in a form that +makes pattern matching more efficient. When using a string constant, +@command{awk} must first convert the string into this internal form and +then perform the pattern matching. + +@item +Using regexp constants is better form; it shows clearly that you +intend a regexp match. +@end itemize + +@sidebar Using @code{\n} in Bracket Expressions of Dynamic Regexps +@cindex regular expressions, dynamic, with embedded newlines +@cindex newlines, in dynamic regexps + +Some older versions of @command{awk} do not allow the newline +character to be used inside a bracket expression for a dynamic regexp: + +@example +$ @kbd{awk '$0 ~ "[ \t\n]"'} +@error{} awk: newline in character class [ +@error{} ]... +@error{} source line number 1 +@error{} context is +@error{} $0 ~ "[ >>> \t\n]" <<< +@end example + +@cindex newlines, in regexp constants +But a newline in a regexp constant works with no problem: + +@example +$ @kbd{awk '$0 ~ /[ \t\n]/'} +@kbd{here is a sample line} +@print{} here is a sample line +@kbd{Ctrl-d} +@end example + +@command{gawk} does not have this problem, and it isn't likely to +occur often in practice, but it's worth noting for future reference. +@end sidebar +@c ENDOFRANGE dregexp +@c ENDOFRANGE regexpd + @node GNU Regexp Operators @section @command{gawk}-Specific Regexp Operators @@ -5534,7 +5759,7 @@ are allowed. Traditional Unix @command{awk} regexps are matched. 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} does support them. +as BWK @command{awk} supports them. Characters described by octal and hexadecimal escape sequences are treated literally, even if they represent regexp metacharacters. @@ -5646,160 +5871,6 @@ Case is always significant in compatibility mode. @c ENDOFRANGE csregexp @c ENDOFRANGE regexpcs -@node Leftmost Longest -@section How Much Text Matches? - -@cindex regular expressions, leftmost longest match -@c @cindex matching, leftmost longest -Consider the following: - -@example -echo aaaabcd | awk '@{ sub(/a+/, "<A>"); print @}' -@end example - -This example uses the @code{sub()} function (which we haven't discussed yet; -@pxref{String Functions}) -to make a change to the input record. Here, the regexp @code{/a+/} -indicates ``one or more @samp{a} characters,'' and the replacement -text is @samp{<A>}. - -The input contains four @samp{a} characters. -@command{awk} (and POSIX) regular expressions always match -the leftmost, @emph{longest} sequence of input characters that can -match. Thus, all four @samp{a} characters are -replaced with @samp{<A>} in this example: - -@example -$ @kbd{echo aaaabcd | awk '@{ sub(/a+/, "<A>"); print @}'} -@print{} <A>bcd -@end example - -For simple match/no-match tests, this is not so important. But when doing -text matching and substitutions with the @code{match()}, @code{sub()}, @code{gsub()}, -and @code{gensub()} functions, it is very important. -@ifinfo -@xref{String Functions}, -for more information on these functions. -@end ifinfo -Understanding this principle is also important for regexp-based record -and field splitting (@pxref{Records}, -and also @pxref{Field Separators}). - -@node Computed Regexps -@section Using Dynamic Regexps - -@c STARTOFRANGE dregexp -@cindex regular expressions, computed -@c STARTOFRANGE regexpd -@cindex regular expressions, dynamic -@cindex @code{~} (tilde), @code{~} operator -@cindex tilde (@code{~}), @code{~} operator -@cindex @code{!} (exclamation point), @code{!~} operator -@cindex exclamation point (@code{!}), @code{!~} operator -@c @cindex operators, @code{~} -@c @cindex operators, @code{!~} -The righthand side of a @samp{~} or @samp{!~} operator need not be a -regexp constant (i.e., a string of characters between slashes). It may -be any expression. The expression is evaluated and converted to a string -if necessary; the contents of the string are then used as the -regexp. A regexp computed in this way is called a @dfn{dynamic -regexp} or a @dfn{computed regexp}: - -@example -BEGIN @{ digits_regexp = "[[:digit:]]+" @} -$0 ~ digits_regexp @{ print @} -@end example - -@noindent -This sets @code{digits_regexp} to a regexp that describes one or more digits, -and tests whether the input record matches this regexp. - -@quotation NOTE -When using the @samp{~} and @samp{!~} -operators, there is a difference between a regexp constant -enclosed in slashes and a string constant enclosed in double quotes. -If you are going to use a string constant, you have to understand that -the string is, in essence, scanned @emph{twice}: the first time when -@command{awk} reads your program, and the second time when it goes to -match the string on the lefthand side of the operator with the pattern -on the right. This is true of any string-valued expression (such as -@code{digits_regexp}, shown previously), not just string constants. -@end quotation - -@cindex regexp constants, slashes vs.@: quotes -@cindex @code{\} (backslash), in regexp constants -@cindex backslash (@code{\}), in regexp constants -@cindex @code{"} (double quote), in regexp constants -@cindex double quote (@code{"}), in regexp constants -What difference does it make if the string is -scanned twice? The answer has to do with escape sequences, and particularly -with backslashes. To get a backslash into a regular expression inside a -string, you have to type two backslashes. - -For example, @code{/\*/} is a regexp constant for a literal @samp{*}. -Only one backslash is needed. To do the same thing with a string, -you have to type @code{"\\*"}. The first backslash escapes the -second one so that the string actually contains the -two characters @samp{\} and @samp{*}. - -@cindex troubleshooting, regexp constants vs.@: string constants -@cindex regexp constants, vs.@: string constants -@cindex string constants, vs.@: regexp constants -Given that you can use both regexp and string constants to describe -regular expressions, which should you use? The answer is ``regexp -constants,'' for several reasons: - -@itemize @value{BULLET} -@item -String constants are more complicated to write and -more difficult to read. Using regexp constants makes your programs -less error-prone. Not understanding the difference between the two -kinds of constants is a common source of errors. - -@item -It is more efficient to use regexp constants. @command{awk} can note -that you have supplied a regexp and store it internally in a form that -makes pattern matching more efficient. When using a string constant, -@command{awk} must first convert the string into this internal form and -then perform the pattern matching. - -@item -Using regexp constants is better form; it shows clearly that you -intend a regexp match. -@end itemize - -@sidebar Using @code{\n} in Bracket Expressions of Dynamic Regexps -@cindex regular expressions, dynamic, with embedded newlines -@cindex newlines, in dynamic regexps - -Some versions of @command{awk} do not allow the newline -character to be used inside a bracket expression for a dynamic regexp: - -@example -$ @kbd{awk '$0 ~ "[ \t\n]"'} -@error{} awk: newline in character class [ -@error{} ]... -@error{} source line number 1 -@error{} context is -@error{} >>> <<< -@end example - -@cindex newlines, in regexp constants -But a newline in a regexp constant works with no problem: - -@example -$ @kbd{awk '$0 ~ /[ \t\n]/'} -@kbd{here is a sample line} -@print{} here is a sample line -@kbd{Ctrl-d} -@end example - -@command{gawk} does not have this problem, and it isn't likely to -occur often in practice, but it's worth noting for future reference. -@end sidebar -@c ENDOFRANGE dregexp -@c ENDOFRANGE regexpd - @node Regexp Summary @section Summary @@ -5829,20 +5900,20 @@ Within bracket expressions, POSIX character classes let you specify certain groups of characters in a locale-independent fashion. @item -@command{gawk}'s @code{IGNORECASE} variable lets you control the -case sensitivity of regexp matching. In other @command{awk} -versions, use @code{tolower()} or @code{toupper()}. - -@item Regular expressions match the leftmost longest text in the string being matched. This matters for cases where you need to know the extent of 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 +Matching expressions may use dynamic regexps, that is, string values treated as regular expressions. +@item +@command{gawk}'s @code{IGNORECASE} variable lets you control the +case sensitivity of regexp matching. In other @command{awk} +versions, use @code{tolower()} or @code{toupper()}. + @end itemize @c ENDOFRANGE regexp @@ -5861,7 +5932,7 @@ standard input (by default, this is the keyboard, but often it is a pipe from an command) or from files whose names you specify on the @command{awk} command line. If you specify input files, @command{awk} reads them in order, processing all the data from one before going on to the next. -The name of the current input file can be found in the built-in variable +The name of the current input file can be found in the predefined variable @code{FILENAME} (@pxref{Built-in Variables}). @@ -5907,16 +5978,13 @@ used with it do not have to be named on the @command{awk} command line @cindex records, splitting input into @cindex @code{NR} variable @cindex @code{FNR} variable -The @command{awk} utility divides the input for your @command{awk} -program into records and fields. -@command{awk} keeps track of the number of records that have -been read -so far -from the current input file. This value is stored in a -built-in variable called @code{FNR}. It is reset to zero when a new -file is started. Another built-in 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. +@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. +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. @menu * awk split records:: How standard @command{awk} splits records. @@ -5932,7 +6000,7 @@ Records are separated by a character called the @dfn{record separator}. By default, the record separator is the newline character. This is why records are, by default, single lines. A different character can be used for the record separator by -assigning the character to the built-in variable @code{RS}. +assigning the character to the predefined variable @code{RS}. @cindex newlines, as record separators @cindex @code{RS} variable @@ -6043,7 +6111,8 @@ Using an unusual character such as @samp{/} is more likely to produce correct behavior in the majority of cases, but there are no guarantees. The moral is: Know Your Data. -There is one unusual case, that occurs when @command{gawk} is +When using regular characters as the record separator, +there is one unusual case that occurs when @command{gawk} is being fully POSIX-compliant (@pxref{Options}). Then, the following (extreme) pipeline prints a surprising @samp{1}: @@ -6132,7 +6201,7 @@ $ @kbd{echo record 1 AAAA record 2 BBBB record 3 |} @noindent The square brackets delineate the contents of @code{RT}, letting you -see the leading and trailing whitespace. The final value of @code{RT} +see the leading and trailing whitespace. The final value of @code{RT} is a newline. @xref{Simple Sed}, for a more useful example of @code{RS} as a regexp and @code{RT}. @@ -6151,7 +6220,7 @@ metacharacters match the beginning and end of a @emph{string}, and not 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 in it. +that happens to contain newline characters. It is thus best to avoid anchor characters in the value of @code{RS}. @end quotation @@ -6161,7 +6230,7 @@ variable are @command{gawk} extensions; they are not available in compatibility mode (@pxref{Options}). In compatibility mode, only the first character of the value of -@code{RS} is used to determine the end of the record. +@code{RS} determines the end of the record. @sidebar @code{RS = "\0"} Is Not Portable @cindex portability, data files as single record @@ -6171,7 +6240,7 @@ a value that you know doesn't occur in the input file. This is hard to do in a general way, such that a program always works for arbitrary input files. -You might think that for text files, the @sc{nul} character, which +You might think that for text files, the @value{NUL} character, which consists of a character with all bits equal to zero, is a good value to use for @code{RS} in this case: @@ -6180,27 +6249,28 @@ BEGIN @{ RS = "\0" @} # whole file becomes one record? @end example @cindex differences in @command{awk} and @command{gawk}, strings, storing -@command{gawk} in fact accepts this, and uses the @sc{nul} +@command{gawk} in fact accepts this, and uses the @value{NUL} character for the record separator. This works for certain special files, such as @file{/proc/environ} on -GNU/Linux systems, where the @sc{nul} character is in fact the record separator. +GNU/Linux systems, where the @value{NUL} character is in fact the record separator. However, this usage is @emph{not} portable to most other @command{awk} implementations. @cindex dark corner, strings, storing Almost all other @command{awk} implementations@footnote{At least that we know about.} store strings internally as C-style strings. C strings use the -@sc{nul} character as the string terminator. In effect, this means that +@value{NUL} character as the string terminator. In effect, this means that @samp{RS = "\0"} is the same as @samp{RS = ""}. @value{DARKCORNER} -It happens that recent versions of @command{mawk} can use the @sc{nul} +It happens that recent versions of @command{mawk} can use the @value{NUL} character as a record separator. However, this is a special case: -@command{mawk} does not allow embedded @sc{nul} characters in strings. +@command{mawk} does not allow embedded @value{NUL} characters in strings. +(This may change in a future version of @command{mawk}.) @cindex records, treating files as @cindex treating files, as single records -@xref{Readfile Function}, for an interesting, portable way to read +@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. @end sidebar @@ -6259,7 +6329,7 @@ field. @cindex @code{NF} variable @cindex fields, number of -@code{NF} is a built-in variable whose value is the number of fields +@code{NF} is a predefined variable whose value is the number of fields in the current record. @command{awk} automatically updates the value of @code{NF} each time it reads a record. No matter how many fields there are, the last field in a record can be represented by @code{$NF}. @@ -6281,15 +6351,11 @@ $ @kbd{awk '$1 ~ /li/ @{ print $0 @}' mail-list} @noindent This example prints each record in the file @file{mail-list} whose first -field contains the string @samp{li}. The operator @samp{~} is called a -@dfn{matching operator} -(@pxref{Regexp Usage}); -it tests whether a string (here, the field @code{$1}) matches a given regular -expression. +field contains the string @samp{li}. -By contrast, the following example -looks for @samp{li} in @emph{the entire record} and prints the first -field and the last field for each matching input record: +By contrast, the following example looks for @samp{li} in @emph{the +entire record} and prints the first and last fields for each matching +input record: @example $ @kbd{awk '/li/ @{ print $1, $NF @}' mail-list} @@ -6352,7 +6418,7 @@ implementations may behave differently.) As mentioned in @ref{Fields}, @command{awk} stores the current record's number of fields in the built-in -variable @code{NF} (also @pxref{Built-in Variables}). The expression +variable @code{NF} (also @pxref{Built-in Variables}). Thus, the expression @code{$NF} is not a special feature---it is the direct consequence of evaluating @code{NF} and using its value as a field number. @@ -6412,8 +6478,8 @@ It is also possible to also assign contents to fields that are out of range. For example: @example -$ awk '@{ $6 = ($5 + $4 + $3 + $2) -> print $6 @}' inventory-shipped +$ @kbd{awk '@{ $6 = ($5 + $4 + $3 + $2)} +> @kbd{ print $6 @}' inventory-shipped} @print{} 168 @print{} 297 @print{} 301 @@ -6502,7 +6568,7 @@ Here is an example: @example $ echo a b c d e f | awk '@{ print "NF =", NF; -> NF = 3; print $0 @}' +> NF = 3; print $0 @}' @print{} NF = 6 @print{} a b c @end example @@ -6510,7 +6576,7 @@ $ echo a b c d e f | awk '@{ print "NF =", NF; @cindex portability, @code{NF} variable@comma{} decrementing @quotation CAUTION Some versions of @command{awk} don't -rebuild @code{$0} when @code{NF} is decremented. Caveat emptor. +rebuild @code{$0} when @code{NF} is decremented. @end quotation Finally, there are times when it is convenient to force @@ -6541,7 +6607,7 @@ record, exactly as it was read from the input. This includes any leading or trailing whitespace, and the exact whitespace (or other characters) that separate the fields. -It is a not-uncommon error to try to change the field separators +It is a common error to try to change the field separators 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. @@ -6590,7 +6656,7 @@ is split into three fields: @samp{m}, @samp{@bullet{}g}, and Note the leading spaces in the values of the second and third fields. @cindex troubleshooting, @command{awk} uses @code{FS} not @code{IFS} -The field separator is represented by the built-in variable @code{FS}. +The field separator is represented by the predefined variable @code{FS}. Shell programmers take note: @command{awk} does @emph{not} use the name @code{IFS} that is used by the POSIX-compliant shells (such as the Unix Bourne shell, @command{sh}, or Bash). @@ -6744,9 +6810,10 @@ $ @kbd{echo ' a b c d' | awk '@{ print; $2 = $2; print @}'} The first @code{print} statement prints the record as it was read, with leading whitespace intact. The assignment to @code{$2} rebuilds @code{$0} by concatenating @code{$1} through @code{$NF} together, -separated by the value of @code{OFS}. Because the leading whitespace -was ignored when finding @code{$1}, it is not part of the new @code{$0}. -Finally, the last @code{print} statement prints the new @code{$0}. +separated by the value of @code{OFS} (which is a space by default). +Because the leading whitespace was ignored when finding @code{$1}, +it is not part of the new @code{$0}. Finally, the last @code{print} +statement prints the new @code{$0}. @cindex @code{FS}, containing @code{^} @cindex @code{^} (caret), in @code{FS} @@ -6768,7 +6835,7 @@ also works this way. For example: @example $ @kbd{echo 'xxAA xxBxx C' |} > @kbd{gawk -F '(^x+)|( +)' '@{ for (i = 1; i <= NF; i++)} -> @kbd{printf "-->%s<--\n", $i @}'} +> @kbd{ printf "-->%s<--\n", $i @}'} @print{} --><-- @print{} -->AA<-- @print{} -->xxBxx<-- @@ -6831,15 +6898,10 @@ awk -F, '@var{program}' @var{input-files} @noindent sets @code{FS} to the @samp{,} character. Notice that the option uses an uppercase @samp{F} instead of a lowercase @samp{f}. The latter -option (@option{-f}) specifies a file -containing an @command{awk} program. Case is significant in command-line -options: -the @option{-F} and @option{-f} options have nothing to do with each other. -You can use both options at the same time to set the @code{FS} variable -@emph{and} get an @command{awk} program from a file. +option (@option{-f}) specifies a file containing an @command{awk} program. The value used for the argument to @option{-F} is processed in exactly the -same way as assignments to the built-in variable @code{FS}. +same way as assignments to the predefined variable @code{FS}. Any special characters in the field separator must be escaped appropriately. For example, to use a @samp{\} as the field separator on the command line, you would have to type: @@ -6950,7 +7012,7 @@ to @code{FS} (the backslash is stripped). This creates a regexp meaning If instead you want fields to be separated by a literal period followed by any single character, use @samp{FS = "\\.."}. -The following table summarizes how fields are split, based on the value +The following list summarizes how fields are split, based on the value of @code{FS} (@samp{==} means ``is equal to''): @table @code @@ -6971,8 +7033,7 @@ 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 @command{gawk} extension; it is not specified by the -POSIX standard.) +(This is a common extension; it is not specified by the POSIX standard.) @end table @sidebar Changing @code{FS} Does Not Affect the Fields @@ -7424,7 +7485,7 @@ BEGIN @{ RS = "" ; FS = "\n" @} Running the program produces the following output: @example -$ awk -f addrs.awk addresses +$ @kbd{awk -f addrs.awk addresses} @print{} Name is: Jane Doe @print{} Address is: 123 Main Street @print{} City and State are: Anywhere, SE 12345-6789 @@ -7436,12 +7497,9 @@ $ awk -f addrs.awk addresses @dots{} @end example -@xref{Labels Program}, for a more realistic -program that deals with address lists. -The following -table -summarizes how records are split, based on the -value of +@xref{Labels Program}, for a more realistic program that deals with +address lists. The following list summarizes how records are split, +based on the value of @ifinfo @code{RS}. (@samp{==} means ``is equal to.'') @@ -7476,8 +7534,8 @@ POSIX standard.) @cindex @command{gawk}, @code{RT} variable in @cindex @code{RT} variable -In all cases, @command{gawk} sets @code{RT} to the input text that matched the -value specified by @code{RS}. +If not in compatibility mode (@pxref{Options}), @command{gawk} sets +@code{RT} to the input text that matched the value specified by @code{RS}. But if the input file ended without any text that matches @code{RS}, then @command{gawk} sets @code{RT} to the null string. @c ENDOFRANGE recm @@ -7523,7 +7581,7 @@ and have a good knowledge of how @command{awk} works. @cindex @code{getline} command, return values @cindex @option{--sandbox} option, input redirection with @code{getline} -The @code{getline} command returns one if it finds a record and zero if +The @code{getline} command returns 1 if it finds a record and 0 if it encounters the end of the file. If there is some error in getting a record, such as a file that cannot be opened, then @code{getline} returns @minus{}1. In this case, @command{gawk} sets the variable @@ -7563,32 +7621,56 @@ finished processing the current record, but want to do some special processing on the next record @emph{right now}. For example: @example +# Remove text between /* and */, inclusive @{ - if ((t = index($0, "/*")) != 0) @{ - # value of `tmp' will be "" if t is 1 - tmp = substr($0, 1, t - 1) - u = index(substr($0, t + 2), "*/") - offset = t + 2 - while (u == 0) @{ - if (getline <= 0) @{ - m = "unexpected EOF or error" - m = (m ": " ERRNO) - print m > "/dev/stderr" + if ((i = index($0, "/*")) != 0) @{ + out = substr($0, 1, i - 1) # leading part of the string + rest = substr($0, i + 2) # ... */ ... + j = index(rest, "*/") # is */ in trailing part? + if (j > 0) @{ + rest = substr(rest, j + 2) # remove comment + @} else @{ + while (j == 0) @{ + # get more text + if (getline <= 0) @{ + print("unexpected EOF or error:", ERRNO) > "/dev/stderr" exit - @} - u = index($0, "*/") - offset = 0 - @} - # substr() expression will be "" if */ - # occurred at end of line - $0 = tmp substr($0, offset + u + 2) - @} - print $0 + @} + # build up the line using string concatenation + rest = rest $0 + j = index(rest, "*/") # is */ in trailing part? + if (j != 0) @{ + rest = substr(rest, j + 2) + break + @} + @} + @} + # build up the output line using string concatenation + $0 = out rest + @} + print $0 @} @end example +@c 8/2014: Here is some sample input: +@ignore +mon/*comment*/key +rab/*commen +t*/bit +horse /*comment*/more text +part 1 /*comment*/part 2 /*comment*/part 3 +no comment +@end ignore + This @command{awk} program deletes C-style comments (@samp{/* @dots{} -*/}) from the input. By replacing the @samp{print $0} with other +*/}) from the input. +It uses a number of features we haven't covered yet, including +string concatenation +(@pxref{Concatenation}) +and the @code{index()} and @code{substr()} built-in +functions +(@pxref{String Functions}). +By replacing the @samp{print $0} with other statements, you could perform more complicated processing on the decommented input, such as searching for matches of a regular expression. (This program has a subtle problem---it does not work if one @@ -7710,7 +7792,7 @@ from the file @var{file}, and put it in the variable @var{var}. As above, @var{file} is a string-valued expression that specifies the file from which to read. -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. The only variable changed is @var{var}.@footnote{This is not quite true. @code{RT} could be changed if @code{RS} is a regular expression.} @@ -7820,7 +7902,7 @@ bletch @end example @noindent -Notice that this program ran the command @command{who} and printed the previous result. +Notice that this program ran the command @command{who} and printed the result. (If you try this program yourself, you will of course get different results, depending upon who is logged in on your system.) @@ -7845,7 +7927,7 @@ Unfortunately, @command{gawk} has not been consistent in its treatment of a construct like @samp{@w{"echo "} "date" | getline}. Most versions, including the current version, treat it at as @samp{@w{("echo "} "date") | getline}. -(This how BWK @command{awk} behaves.) +(This is also how BWK @command{awk} behaves.) Some versions changed and treated it as @samp{@w{"echo "} ("date" | getline)}. (This is how @command{mawk} behaves.) @@ -7872,8 +7954,8 @@ BEGIN @{ @} @end example -In this version of @code{getline}, none of the built-in variables are -changed and the record is not split into fields. +In this version of @code{getline}, none of the predefined variables are +changed and the record is not split into fields. However, @code{RT} is set. @ifinfo @c Thanks to Paul Eggert for initial wording here @@ -7934,7 +8016,7 @@ When you use @samp{@var{command} |& getline @var{var}}, the output from the coprocess @var{command} is sent through a two-way pipe to @code{getline} and into the variable @var{var}. -In this version of @code{getline}, none of the built-in variables are +In this version of @code{getline}, none of the predefined variables are changed and the record is not split into fields. The only variable changed is @var{var}. However, @code{RT} is set. @@ -7981,7 +8063,7 @@ causes @command{awk} to set the value of @code{FILENAME}. Normally, @code{FILENAME} does not have a value inside @code{BEGIN} rules, because you have not yet started to process the command-line @value{DF}s. @value{DARKCORNER} -(@xref{BEGIN/END}, +(See @ref{BEGIN/END}; also @pxref{Auto-set}.) @item @@ -7995,7 +8077,7 @@ probably by accident, and you should reconsider what it is you're trying to accomplish. @item -@ref{Getline Summary}, presents a table summarizing the +@DBREF{Getline Summary} presents a table summarizing the @code{getline} variants and which variables they can affect. It is worth noting that those variants which do not use redirection can cause @code{FILENAME} to be updated if they cause @@ -8028,7 +8110,7 @@ end of file is encountered, before the element in @code{a} is assigned? @command{gawk} treats @code{getline} like a function call, and evaluates the expression @samp{a[++c]} before attempting to read from @file{f}. However, some versions of @command{awk} only evaluate the expression once they -know that there is a string value to be assigned. Caveat Emptor. +know that there is a string value to be assigned. @end itemize @node Getline Summary @@ -8037,22 +8119,22 @@ know that there is a string value to be assigned. Caveat Emptor. @ref{table-getline-variants} summarizes the eight variants of @code{getline}, -listing which built-in variables are set by each one, +listing which predefined variables are set by each one, and whether the variant is standard or a @command{gawk} extension. -Note: for each variant, @command{gawk} sets the @code{RT} built-in variable. +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} @multitable @columnfractions .33 .38 .27 -@headitem Variant @tab Effect @tab Standard / Extension -@item @code{getline} @tab Sets @code{$0}, @code{NF}, @code{FNR}, @code{NR}, and @code{RT} @tab Standard -@item @code{getline} @var{var} @tab Sets @var{var}, @code{FNR}, @code{NR}, and @code{RT} @tab Standard -@item @code{getline <} @var{file} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab Standard -@item @code{getline @var{var} < @var{file}} @tab Sets @var{var} and @code{RT} @tab Standard -@item @var{command} @code{| getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab Standard -@item @var{command} @code{| getline} @var{var} @tab Sets @var{var} and @code{RT} @tab Standard -@item @var{command} @code{|& getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab Extension -@item @var{command} @code{|& getline} @var{var} @tab Sets @var{var} and @code{RT} @tab Extension +@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} +@item @code{getline} @var{var} @tab Sets @var{var}, @code{FNR}, @code{NR}, and @code{RT} @tab @command{awk} +@item @code{getline <} @var{file} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab @command{awk} +@item @code{getline @var{var} < @var{file}} @tab Sets @var{var} and @code{RT} @tab @command{awk} +@item @var{command} @code{| getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab @command{awk} +@item @var{command} @code{| getline} @var{var} @tab Sets @var{var} and @code{RT} @tab @command{awk} +@item @var{command} @code{|& getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab @command{gawk} +@item @var{command} @code{|& getline} @var{var} @tab Sets @var{var} and @code{RT} @tab @command{gawk} @end multitable @end float @c ENDOFRANGE getl @@ -8069,7 +8151,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 -in the @code{PROCINFO} (@pxref{Auto-set}) array: +in the @code{PROCINFO} array (@pxref{Auto-set}): @example PROCINFO["input_name", "READ_TIMEOUT"] = @var{timeout in milliseconds} @@ -8101,7 +8183,7 @@ while ((getline < "/dev/stdin") > 0) @command{gawk} terminates the read operation if input does not arrive after waiting for the timeout period, returns failure -and sets the @code{ERRNO} variable to an appropriate string value. +and sets @code{ERRNO} to an appropriate string value. A negative or zero value for the timeout is the same as specifying no timeout at all. @@ -8208,6 +8290,10 @@ The possibilities are as follows: @end multitable @item +@code{FNR} indicates how many records have been read from the current input file; +@code{NR} indicates how many records have been read in total. + +@item @command{gawk} sets @code{RT} to the text matched by @code{RS}. @item @@ -8218,7 +8304,7 @@ fields there are. The default way to split fields is between whitespace characters. @item -Fields may be referenced using a variable, as in @samp{$NF}. Fields +Fields may be referenced using a variable, as in @code{$NF}. Fields may also be assigned values, which causes the value of @code{$0} to be recomputed when it is later referenced. Assigning to a field with a number greater than @code{NF} creates the field and rebuilds the record, using @@ -8228,16 +8314,17 @@ thing. Decrementing @code{NF} throws away fields and rebuilds the record. @item Field splitting is more complicated than record splitting. -@multitable @columnfractions .40 .40 .20 +@multitable @columnfractions .40 .45 .15 @headitem Field separator value @tab Fields are split @dots{} @tab @command{awk} / @command{gawk} @item @code{FS == " "} @tab On runs of whitespace @tab @command{awk} @item @code{FS == @var{any single character}} @tab On that character @tab @command{awk} @item @code{FS == @var{regexp}} @tab On text matching the regexp @tab @command{awk} @item @code{FS == ""} @tab Each individual character is a separate field @tab @command{gawk} @item @code{FIELDWIDTHS == @var{list of columns}} @tab Based on character position @tab @command{gawk} -@item @code{FPAT == @var{regexp}} @tab On text around text matching the regexp @tab @command{gawk} +@item @code{FPAT == @var{regexp}} @tab On the text surrounding text matching the regexp @tab @command{gawk} @end multitable +@item Using @samp{FS = "\n"} causes the entire record to be a single field (assuming that newlines separate records). @@ -8246,11 +8333,11 @@ Using @samp{FS = "\n"} causes the entire record to be a single field This can also be done using command-line variable assignment. @item -@code{PROCINFO["FS"]} can be used to see how fields are being split. +Use @code{PROCINFO["FS"]} to see how fields are being split. @item Use @code{getline} in its various forms to read additional records, -from the default input stream, from a file, or from a pipe or co-process. +from the default input stream, from a file, or from a pipe or coprocess. @item Use @code{PROCINFO[@var{file}, "READ_TIMEOUT"]} to cause reads to timeout @@ -8262,6 +8349,7 @@ Directories on the command line are fatal for standard @command{awk}; @end itemize +@c EXCLUDE START @node Input Exercises @section Exercises @@ -8278,9 +8366,10 @@ including abstentions, for each item. comments (@samp{/* @dots{} */}) from the input. That program does not work if one comment ends on one line and another one starts later on the same line. -Write a program that does handle multiple comments on the line. +That can be fixed by making one simple change. What is it? @end enumerate +@c EXCLUDE END @node Printing @chapter Printing Output @@ -8317,18 +8406,19 @@ and discusses the @code{close()} built-in function. * Printf:: The @code{printf} statement. * Redirection:: How to redirect output to multiple files and pipes. +* Special FD:: Special files for I/O. * Special Files:: File name interpretation in @command{gawk}. @command{gawk} allows access to inherited file descriptors. * Close Files And Pipes:: Closing Input and Output Files and Pipes. * Output Summary:: Output summary. -* Output exercises:: Exercises. +* Output Exercises:: Exercises. @end menu @node Print @section The @code{print} Statement -The @code{print} statement is used for producing output with simple, standardized +Use the @code{print} statement to produce output with simple, standardized formatting. You specify only the strings or numbers to print, in a list separated by commas. They are output, separated by single spaces, followed by a newline. The statement looks like this: @@ -8352,7 +8442,7 @@ expression. Numeric values are converted to strings and then printed. @cindex text, printing The simple statement @samp{print} with no items is equivalent to @samp{print $0}: it prints the entire current record. To print a blank -line, use @samp{print ""}, where @code{""} is the empty string. +line, use @samp{print ""}. To print a fixed piece of text, use a string constant, such as @w{@code{"Don't Panic"}}, as one item. If you forget to use the double-quote characters, your text is taken as an @command{awk} @@ -8360,8 +8450,8 @@ expression, and you will probably get an error. Keep in mind that a space is printed between any two items. Note that the @code{print} statement is a statement and not an -expression---you can't use it the pattern part of a pattern-action -statement, for example. +expression---you can't use it in the pattern part of a +@var{pattern}-@var{action} statement, for example. @node Print Examples @section @code{print} Statement Examples @@ -8372,9 +8462,22 @@ newline, the newline is output along with the rest of the string. A single @code{print} statement can make any number of lines this way. @cindex newlines, printing -The following is an example of printing a string that contains embedded newlines +The following is an example of printing a string that contains embedded +@ifinfo +newlines +(the @samp{\n} is an escape sequence, used to represent the newline +character; @pxref{Escape Sequences}): +@end ifinfo +@ifhtml +newlines (the @samp{\n} is an escape sequence, used to represent the newline character; @pxref{Escape Sequences}): +@end ifhtml +@ifnotinfo +@ifnothtml +newlines: +@end ifnothtml +@end ifnotinfo @example $ @kbd{awk 'BEGIN @{ print "line one\nline two\nline three" @}'} @@ -8478,7 +8581,7 @@ of items 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 @dfn{output field separator} by setting the -built-in variable @code{OFS}. The initial value of this variable +predefined variable @code{OFS}. The initial value of this variable is the string @w{@code{" "}}---that is, a single space. The output from an entire @code{print} statement is called an @@ -8554,13 +8657,13 @@ more fully in @cindexawkfunc{sprintf} @cindex @code{OFMT} variable @cindex output, format specifier@comma{} @code{OFMT} -The built-in variable @code{OFMT} contains the default format specification +The predefined variable @code{OFMT} contains the format specification that @code{print} uses with @code{sprintf()} when it wants to convert a number to a string for printing. The default value of @code{OFMT} is @code{"%.6g"}. The way @code{print} prints numbers can be changed -by supplying different format specifications -as the value of @code{OFMT}, as shown in the following example: +by supplying a different format specification +for the value of @code{OFMT}, as shown in the following example: @example $ @kbd{awk 'BEGIN @{} @@ -8590,9 +8693,7 @@ With @code{printf} you can specify the width to use for each item, as well as various formatting choices for numbers (such as what output base to use, whether to print an exponent, whether to print a sign, and how many digits to print -after the decimal point). You do this by supplying a string, called -the @dfn{format string}, that controls how and where to print the other -arguments. +after the decimal point). @menu * Basic Printf:: Syntax of the @code{printf} statement. @@ -8612,10 +8713,10 @@ printf @var{format}, @var{item1}, @var{item2}, @dots{} @end example @noindent -The entire list of arguments may optionally be enclosed in parentheses. 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}). +As print @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}). @cindex format specifiers The difference between @code{printf} and @code{print} is the @var{format} @@ -8638,10 +8739,10 @@ on @code{printf} statements. For example: @example $ @kbd{awk 'BEGIN @{} > @kbd{ORS = "\nOUCH!\n"; OFS = "+"} -> @kbd{msg = "Dont Panic!"} +> @kbd{msg = "Don\47t Panic!"} > @kbd{printf "%s\n", msg} > @kbd{@}'} -@print{} Dont Panic! +@print{} Don't Panic! @end example @noindent @@ -8663,7 +8764,7 @@ the field width. Here is a list of the format-control letters: @c @asis for docbook to come out right @table @asis @item @code{%c} -Print a number as an ASCII character; thus, @samp{printf "%c", +Print a number as a character; thus, @samp{printf "%c", 65} outputs the letter @samp{A}. The output for a string value is the first character of the string. @@ -8689,7 +8790,7 @@ a single byte (0--255). @item @code{%d}, @code{%i} Print a decimal integer. The two control letters are equivalent. -(The @samp{%i} specification is for compatibility with ISO C.) +(The @code{%i} specification is for compatibility with ISO C.) @item @code{%e}, @code{%E} Print a number in scientific (exponential) notation; @@ -8704,7 +8805,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}.) -@samp{%E} uses @samp{E} instead of @samp{e} in the output. +@code{%E} uses @samp{E} instead of @samp{e} in the output. @item @code{%f} Print a number in floating-point notation. @@ -8730,16 +8831,16 @@ The special ``not a number'' value formats as @samp{-nan} or @samp{nan} (@pxref{Math Definitions}). @item @code{%F} -Like @samp{%f} but the infinity and ``not a number'' values are spelled +Like @code{%f} but the infinity and ``not a number'' values are spelled using uppercase letters. -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. +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. @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, @samp{%G} uses @samp{E} instead of @samp{e}. +scientific notation, @code{%G} uses @samp{E} instead of @samp{e}. @item @code{%o} Print an unsigned octal integer @@ -8755,7 +8856,7 @@ are floating-point; it is provided primarily for compatibility with C.) @item @code{%x}, @code{%X} Print an unsigned hexadecimal integer; -@samp{%X} uses the letters @samp{A} through @samp{F} +@code{%X} uses the letters @samp{A} through @samp{F} instead of @samp{a} through @samp{f} (@pxref{Nondecimal-numbers}). @@ -8770,7 +8871,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 @samp{%g} format specifier. If @option{--lint} is provided on the +the @code{%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. @@ -8786,7 +8887,7 @@ values or do something else entirely. A format specification can also include @dfn{modifiers} that can control how much of the item's value is printed, as well as how much space it gets. The modifiers come between the @samp{%} and the format-control letter. -We will use the bullet symbol ``@bullet{}'' in the following examples to +We use the bullet symbol ``@bullet{}'' in the following examples to represent spaces in the output. Here are the possible modifiers, in the order in which they may appear: @@ -8817,7 +8918,7 @@ It is in fact a @command{gawk} extension, intended for use in translating messages at runtime. @xref{Printf Ordering}, which describes how and why to use positional specifiers. -For now, we will not use them. +For now, we ignore them. @item - The minus sign, used before the width modifier (see later on in @@ -8845,15 +8946,15 @@ to format is positive. The @samp{+} overrides the space modifier. @item # Use an ``alternate 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 +For @code{%o}, supply a leading zero. +For @code{%x} and @code{%X}, supply a leading @code{0x} or @samp{0X} for a nonzero result. -For @samp{%e}, @samp{%E}, @samp{%f}, and @samp{%F}, the result always +For @code{%e}, @code{%E}, @code{%f}, and @code{%F}, the result always contains a decimal point. -For @samp{%g} and @samp{%G}, trailing zeros are not removed from the result. +For @code{%g} and @code{%G}, trailing zeros are not removed from the result. @item 0 -A leading @samp{0} (zero) acts as a flag that indicates that output should be +A leading @samp{0} (zero) acts as a flag indicating that output should be padded with zeros instead of spaces. This applies only to the numeric output formats. This flag only has an effect when the field width is wider than the @@ -9039,7 +9140,7 @@ the @command{awk} program: @example awk 'BEGIN @{ print "Name Number" print "---- ------" @} - @{ printf "%-10s %s\n", $1, $2 @}' mail-list + @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example The above example mixes @code{print} and @code{printf} statements in @@ -9049,7 +9150,7 @@ same results: @example awk 'BEGIN @{ printf "%-10s %s\n", "Name", "Number" printf "%-10s %s\n", "----", "------" @} - @{ printf "%-10s %s\n", $1, $2 @}' mail-list + @{ printf "%-10s %s\n", $1, $2 @}' mail-list @end example @noindent @@ -9064,7 +9165,7 @@ emphasized by storing it in a variable, like this: awk 'BEGIN @{ format = "%-10s %s\n" printf format, "Name", "Number" printf format, "----", "------" @} - @{ printf format, $1, $2 @}' mail-list + @{ printf format, $1, $2 @}' mail-list @end example @c ENDOFRANGE printfs @@ -9085,7 +9186,7 @@ This is called @dfn{redirection}. @quotation NOTE When @option{--sandbox} is specified (@pxref{Options}), -redirecting output to files and pipes is disabled. +redirecting output to files, pipes and coprocesses is disabled. @end quotation A redirection appears after the @code{print} or @code{printf} statement. @@ -9182,17 +9283,11 @@ in an @command{awk} script run periodically for system maintenance: @example report = "mail bug-system" -print "Awk script failed:", $0 | report -m = ("at record number " FNR " of " FILENAME) -print m | report +print("Awk script failed:", $0) | report +print("at record number", FNR, "of", FILENAME) | report close(report) @end example -The message is built using string concatenation and saved in the variable -@code{m}. It's then sent down the pipeline to the @command{mail} program. -(The parentheses group the items to concatenate---see -@ref{Concatenation}.) - 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}, @@ -9293,27 +9388,15 @@ uppercase characters converted to lowercase 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 +command lines to be fed to the shell. @end sidebar @c ENDOFRANGE outre @c ENDOFRANGE reout -@node Special Files -@section Special @value{FFN}s in @command{gawk} -@c STARTOFRANGE gfn -@cindex @command{gawk}, file names in - -@command{gawk} provides a number of special @value{FN}s that it interprets -internally. These @value{FN}s provide access to standard file descriptors -and TCP/IP networking. - -@menu -* Special FD:: Special files for I/O. -* Special Network:: Special files for network communications. -* Special Caveats:: Things to watch out for. -@end menu - @node Special FD -@subsection Special Files for Standard Descriptors +@section Special Files for Standard Pre-Opened Data Streams @cindex standard input @cindex input, standard @cindex standard output @@ -9324,9 +9407,12 @@ and TCP/IP networking. @cindex files, descriptors, See file descriptors Running programs conventionally have three input and output streams -already available to them for reading and writing. These are known as -the @dfn{standard input}, @dfn{standard output}, and @dfn{standard error -output}. These streams are, by default, connected to your keyboard and screen, but +already available to them for reading and writing. These are known +as the @dfn{standard input}, @dfn{standard output}, and @dfn{standard +error output}. These open streams (and any other open file or pipe) +are often referred to by the technical term @dfn{file descriptors}. + +These streams are, by default, connected to your keyboard and screen, but they are often redirected with the shell, via the @samp{<}, @samp{<<}, @samp{>}, @samp{>>}, @samp{>&}, and @samp{|} operators. Standard error is typically used for writing error messages; the reason there are two separate @@ -9335,7 +9421,7 @@ redirected separately. @cindex differences in @command{awk} and @command{gawk}, error messages @cindex error handling -In other implementations of @command{awk}, the only way to write an error +In traditional implementations of @command{awk}, the only way to write an error message to standard error in an @command{awk} program is as follows: @example @@ -9361,19 +9447,19 @@ that is connected to your keyboard and screen. It represents the ``terminal,''@footnote{The ``tty'' in @file{/dev/tty} stands for ``Teletype,'' a serial terminal.} which on modern systems is a keyboard and screen, not a serial console.) -This usually has the same effect but not always: although the +This generally has the same effect but not always: although the standard error stream is usually the screen, it can be redirected; when that happens, writing to the screen is not correct. In fact, if @command{awk} is run from a background job, it may not have a terminal at all. Then opening @file{/dev/tty} fails. -@command{gawk} provides special @value{FN}s for accessing the three standard -streams. @value{COMMONEXT} It also provides syntax for accessing -any other inherited open files. If the @value{FN} matches -one of these special names when @command{gawk} redirects input or output, -then it directly uses the stream that the @value{FN} stands for. -These special @value{FN}s work for all operating systems that @command{gawk} +@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 +the descriptor that the @value{FN} stands for. These special +@value{FN}s work for all operating systems that @command{gawk} has been ported to, not just those that are POSIX-compliant: @cindex common extensions, @code{/dev/stdin} special file @@ -9395,19 +9481,10 @@ The standard output (file descriptor 1). @item /dev/stderr The standard error output (file descriptor 2). - -@item /dev/fd/@var{N} -The file associated with file descriptor @var{N}. Such a file must -be opened by the program initiating the @command{awk} execution (typically -the shell). Unless special pains are taken in the shell from which -@command{gawk} is invoked, only descriptors 0, 1, and 2 are available. @end table -The @value{FN}s @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} -are aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and @file{/dev/fd/2}, -respectively. However, they are more self-explanatory. -The proper way to write an error message in a @command{gawk} program -is to use @file{/dev/stderr}, like this: +With these facilities, +the proper way to write an error message then becomes: @example print "Serious error detected!" > "/dev/stderr" @@ -9419,14 +9496,51 @@ Like any other redirection, the value must be a string. It is a common error to omit the quotes, which leads to confusing results. -Finally, using the @code{close()} function on a @value{FN} of the +@command{gawk} does not treat these @value{FN}s as special when +in POSIX compatibility mode. However, since BWK @command{awk} +supports them, @command{gawk} does support them even when +invoked with the @option{--traditional} option (@pxref{Options}). + +@node Special Files +@section Special @value{FFN}s in @command{gawk} +@c STARTOFRANGE gfn +@cindex @command{gawk}, file names in + +Besides access to standard input, stanard 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. + +@menu +* Other Inherited Files:: Accessing other open files with + @command{gawk}. +* Special Network:: Special files for network communications. +* Special Caveats:: Things to watch out for. +@end menu + +@node Other Inherited Files +@subsection Accessing Other Open Files With @command{gawk} + +Besides the @code{/dev/stdin}, @code{/dev/stdout}, and @code{/dev/stderr} +special @value{FN}s mentioned earlier, @command{gawk} provides syntax +for accessing any other inherited open file: + +@table @file +@item /dev/fd/@var{N} +The file associated with file descriptor @var{N}. Such a file must +be opened by the program initiating the @command{awk} execution (typically +the shell). Unless special pains are taken in the shell from which +@command{gawk} is invoked, only descriptors 0, 1, and 2 are available. +@end table + +The @value{FN}s @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} +are essentially aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and +@file{/dev/fd/2}, respectively. However, those names are more self-explanatory. + +Note that using @code{close()} on a @value{FN} of the form @code{"/dev/fd/@var{N}"}, for file descriptor numbers above two, does actually close the given file descriptor. -The @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr} -special files are also recognized internally by several other -versions of @command{awk}. - @node Special Network @subsection Special Files for Network Communications @cindex networks, support for @@ -9455,15 +9569,20 @@ Full discussion is delayed until @node Special Caveats @subsection Special @value{FFN} Caveats -Here is a list of things to bear in mind when using the +Here are some things to bear in mind when using the special @value{FN}s that @command{gawk} provides: @itemize @value{BULLET} @cindex compatibility mode (@command{gawk}), file names @cindex file names, in compatibility mode @item -Recognition of these special @value{FN}s is disabled if @command{gawk} is in -compatibility mode (@pxref{Options}). +Recognition of the @value{FN}s for the three standard pre-opened +files is disabled only in POSIX mode. + +@item +Recognition of the other special @value{FN}s is disabled if @command{gawk} is in +compatibility mode (either @option{--traditional} or @option{--posix}; +@pxref{Options}). @item @command{gawk} @emph{always} @@ -9633,7 +9752,8 @@ to a string indicating the error. Note also that @samp{close(FILENAME)} has no ``magic'' effects on the implicit loop that reads through the files named on the command line. It is, more likely, a close of a file that was never opened with a -redirection, so @command{awk} silently does nothing. +redirection, so @command{awk} silently does nothing, except return +a negative value. @cindex @code{|} (vertical bar), @code{|&} operator (I/O), pipes@comma{} closing When using the @samp{|&} operator to communicate with a coprocess, @@ -9645,10 +9765,10 @@ the first argument is the name of the command or special file used to start the coprocess. The second argument should be a string, with either of the values @code{"to"} or @code{"from"}. Case does not matter. -As this is an advanced feature, a more complete discussion is +As this is an advanced feature, discussion is delayed until @ref{Two-way I/O}, -which discusses it in more detail and gives an example. +which describes it in more detail and gives an example. @sidebar Using @code{close()}'s Return Value @cindex dark corner, @code{close()} function @@ -9674,7 +9794,7 @@ retval = close(command) # syntax error in many Unix awks The return value is @minus{}1 if the argument names something that was never opened with a redirection, or if there is a system problem closing the file or process. -In these cases, @command{gawk} sets the built-in variable +In these cases, @command{gawk} sets the predefined variable @code{ERRNO} to a string describing the problem. In @command{gawk}, @@ -9720,20 +9840,21 @@ that modify the behavior of the format control letters. @item Output from both @code{print} and @code{printf} may be redirected to -files, pipes, and co-processes. +files, pipes, and coprocesses. @item @command{gawk} provides special file names for access to standard input, output and error, and for network communications. @item -Use @code{close()} to close open file, pipe and co-process redirections. -For co-processes, it is possible to close only one direction of the +Use @code{close()} to close open file, pipe and coprocess redirections. +For coprocesses, it is possible to close only one direction of the communications. @end itemize -@node Output exercises +@c EXCLUDE START +@node Output Exercises @section Exercises @enumerate @@ -9762,6 +9883,7 @@ BEGIN @{ print "Serious error detected!" > /dev/stderr @} @end example @end enumerate +@c EXCLUDE END @c ENDOFRANGE prnt @@ -9860,7 +9982,7 @@ double-quotation marks. For example: @cindex strings, length limitations represents the string whose contents are @samp{parrot}. Strings in @command{gawk} can be of any length, and they can contain any of the possible -eight-bit ASCII characters including ASCII @sc{nul} (character code zero). +eight-bit ASCII characters including ASCII @value{NUL} (character code zero). Other @command{awk} implementations may have difficulty with some character codes. @@ -9976,7 +10098,8 @@ A regexp constant is a regular expression description enclosed in slashes, such as @code{@w{/^beginning and end$/}}. Most regexps used in @command{awk} programs are constant, but the @samp{~} and @samp{!~} matching operators can also match computed or dynamic regexps -(which are just ordinary strings or variables that contain a regexp). +(which are typically just ordinary strings or variables that contain a regexp, +but could be a more complex expression). @c ENDOFRANGE cnst @node Using Constant Regexps @@ -10010,7 +10133,7 @@ if (/barfly/ || /camelot/) @noindent are exactly equivalent. One rather bizarre consequence of this rule is that the following -Boolean expression is valid, but does not do what the user probably +Boolean expression is valid, but does not do what its author probably intended: @example @@ -10056,10 +10179,9 @@ Modern implementations of @command{awk}, including @command{gawk}, allow the third argument of @code{split()} to be a regexp constant, but some older implementations do not. @value{DARKCORNER} -This can lead to confusion when attempting to use regexp constants -as arguments to user-defined functions -(@pxref{User-defined}). -For example: +Because some built-in functions accept regexp constants as arguments, +it can be confusing when attempting to use regexp constants as arguments +to user-defined functions (@pxref{User-defined}). For example: @example function mysub(pat, repl, str, global) @@ -10114,7 +10236,11 @@ on the @command{awk} command line. Variables let you give names to values and refer to them later. Variables have already been used in many of the examples. The name of a variable must be a sequence of letters, digits, or underscores, and it may not begin -with a digit. Case is significant in variable names; @code{a} and @code{A} +with a digit. +Here, a @dfn{letter} is any one of the 52 upper- and lowercase +English letters. Other characters that may be defined as letters +in non-English locales are not valid in variable names. +Case is significant in variable names; @code{a} and @code{A} are distinct variables. A variable name is a valid expression by itself; it represents the @@ -10123,24 +10249,24 @@ 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{patsplit()} -and @code{split()} functions can change the contents of their +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}. @cindex variables, built-in @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 built-in variables. -These built-in variables can be used and assigned just like all other +record). @xref{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 built-in variables' names are entirely uppercase. +@command{awk}. All predefined variables' names are entirely uppercase. Variables in @command{awk} can be assigned either numeric or string values. The kind of value a variable holds can change over the life of a program. By default, variables are initialized to the empty string, which is zero if converted to a number. There is no need to explicitly -``initialize'' a variable in @command{awk}, +initialize a variable in @command{awk}, which is what you would do in C and in most other traditional languages. @node Assignment Options @@ -10260,7 +10386,7 @@ Strings that can't be interpreted as valid numbers convert to zero. @cindex @code{CONVFMT} variable The exact manner in which numbers are converted into strings is controlled -by the @command{awk} built-in variable @code{CONVFMT} (@pxref{Built-in Variables}). +by the @command{awk} predefined variable @code{CONVFMT} (@pxref{Built-in Variables}). Numbers are converted using the @code{sprintf()} function with @code{CONVFMT} as the format specifier @@ -10348,8 +10474,8 @@ $ @kbd{echo 4,321 | LC_ALL=en_DK.utf-8 gawk '@{ print $1 + 1 @}'} @noindent The @code{en_DK.utf-8} locale is for English in Denmark, where the comma acts as the decimal point separator. In the normal @code{"C"} locale, @command{gawk} -treats @samp{4,321} as @samp{4}, while in the Danish locale, it's treated -as the full number, 4.321. +treats @samp{4,321} as 4, while in the Danish locale, it's treated +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 @@ -10900,7 +11026,7 @@ awk '/[=]=/' /dev/null @end example @command{gawk} does not have this problem; BWK @command{awk} -and @command{mawk} also do not (@pxref{Other Versions}). +and @command{mawk} also do not. @end sidebar @c ENDOFRANGE exas @c ENDOFRANGE opas @@ -11153,7 +11279,7 @@ attribute. @item Fields, @code{getline} input, @code{FILENAME}, @code{ARGV} elements, @code{ENVIRON} elements, and the elements of an array created by -@code{patsplit()}, @code{split()} and @code{match()} 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. @@ -11308,22 +11434,23 @@ Thus, the six-character input string @w{@samp{ +3.14}} receives the The following examples print @samp{1} when the comparison between the two different constants is true, @samp{0} otherwise: +@c 22.9.2014: Tested with mawk and BWK awk, got same results. @example -$ @kbd{echo ' +3.14' | gawk '@{ print $0 == " +3.14" @}'} @ii{True} +$ @kbd{echo ' +3.14' | awk '@{ print($0 == " +3.14") @}'} @ii{True} @print{} 1 -$ @kbd{echo ' +3.14' | gawk '@{ print $0 == "+3.14" @}'} @ii{False} +$ @kbd{echo ' +3.14' | awk '@{ print($0 == "+3.14") @}'} @ii{False} @print{} 0 -$ @kbd{echo ' +3.14' | gawk '@{ print $0 == "3.14" @}'} @ii{False} +$ @kbd{echo ' +3.14' | awk '@{ print($0 == "3.14") @}'} @ii{False} @print{} 0 -$ @kbd{echo ' +3.14' | gawk '@{ print $0 == 3.14 @}'} @ii{True} +$ @kbd{echo ' +3.14' | awk '@{ print($0 == 3.14) @}'} @ii{True} @print{} 1 -$ @kbd{echo ' +3.14' | gawk '@{ print $1 == " +3.14" @}'} @ii{False} +$ @kbd{echo ' +3.14' | awk '@{ print($1 == " +3.14") @}'} @ii{False} @print{} 0 -$ @kbd{echo ' +3.14' | gawk '@{ print $1 == "+3.14" @}'} @ii{True} +$ @kbd{echo ' +3.14' | awk '@{ print($1 == "+3.14") @}'} @ii{True} @print{} 1 -$ @kbd{echo ' +3.14' | gawk '@{ print $1 == "3.14" @}'} @ii{False} +$ @kbd{echo ' +3.14' | awk '@{ print($1 == "3.14") @}'} @ii{False} @print{} 0 -$ @kbd{echo ' +3.14' | gawk '@{ print $1 == 3.14 @}'} @ii{True} +$ @kbd{echo ' +3.14' | awk '@{ print($1 == 3.14) @}'} @ii{True} @print{} 1 @end example @@ -11397,9 +11524,8 @@ part of the test always succeeds. Because the operators are so similar, this kind of error is very difficult to spot when scanning the source code. -@cindex @command{gawk}, comparison operators and -The following table of expressions illustrates the kind of comparison -@command{gawk} performs, as well as what the result of the comparison is: +The following list of expressions illustrates the kinds of comparisons +@command{awk} performs, as well as what the result of each comparison is: @table @code @item 1.5 <= 2.0 @@ -11472,7 +11598,7 @@ dynamic regexp (@pxref{Regexp Usage}; also @cindex @command{awk}, regexp constants and @cindex regexp constants -In modern implementations of @command{awk}, a constant regular +A constant regular expression in slashes by itself is also an expression. The regexp @code{/@var{regexp}/} is an abbreviation for the following comparison expression: @@ -11492,7 +11618,7 @@ where this is discussed in more detail. The POSIX standard says that string comparison is performed based on the locale's @dfn{collating order}. This is the order in which characters sort, as defined by the locale (for more discussion, -@pxref{Ranges and Locales}). This order is usually very different +@pxref{Locales}). This order is usually very different from the results obtained when doing straight character-by-character comparison.@footnote{Technically, string comparison is supposed to behave the same way as if the strings are compared with the C @@ -11572,7 +11698,7 @@ no substring @samp{foo} in the record. True if at least one of @var{boolean1} or @var{boolean2} is true. For example, the following statement prints all records in the input that contain @emph{either} @samp{edu} or -@samp{li} or both: +@samp{li}: @example if ($0 ~ /edu/ || $0 ~ /li/) print @@ -11581,6 +11707,9 @@ if ($0 ~ /edu/ || $0 ~ /li/) print The subexpression @var{boolean2} is evaluated only if @var{boolean1} is false. This can make a difference when @var{boolean2} contains expressions that have side effects. +(Thus, this test never really distinguishes records that contain both +@samp{edu} and @samp{li}---as soon as @samp{edu} is matched, +the full test succeeds.) @item ! @var{boolean} True if @var{boolean} is false. For example, @@ -11590,7 +11719,7 @@ variable is not defined: @example BEGIN @{ if (! ("HOME" in ENVIRON)) - print "no home!" @} + print "no home!" @} @end example (The @code{in} operator is described in @@ -11609,7 +11738,7 @@ is ``short-circuited'' if the result can be determined part way through its evaluation. @cindex line continuations -Statements that use @samp{&&} or @samp{||} can be continued simply +Statements that end with @samp{&&} or @samp{||} can be continued simply by putting a newline after them. But you cannot put a newline in front of either of these operators without using backslash continuation (@pxref{Statements/Lines}). @@ -11628,7 +11757,7 @@ program is one way to print lines in between special bracketing lines: @example $1 == "START" @{ interested = ! interested; next @} -interested == 1 @{ print @} +interested @{ print @} $1 == "END" @{ interested = ! interested; next @} @end example @@ -11648,6 +11777,16 @@ bogus input data, but the point is to illustrate the use of `!', so we'll leave well enough alone. @end ignore +Most commonly, the @samp{!} operator is used in the conditions of +@code{if} and @code{while} statements, where it often makes more +sense to phrase the logic in the negative: + +@example +if (! @var{some condition} || @var{some other condition}) @{ + @var{@dots{} do whatever processing @dots{}} +@} +@end example + @cindex @code{next} statement @quotation NOTE The @code{next} statement is discussed in @@ -11879,7 +12018,7 @@ expression because the first @samp{$} has higher precedence than the @samp{++}; to avoid the problem the expression can be rewritten as @samp{$($0++)--}. -This table presents @command{awk}'s operators, in order of highest +This list presents @command{awk}'s operators, in order of highest to lowest precedence: @c @asis for docbook to come out right @@ -12036,8 +12175,8 @@ system about the local character set and language. The ISO C standard defines a default @code{"C"} locale, which is an environment that is typical of what many C programmers are used to. -Once upon a time, the locale setting used to affect regexp matching -(@pxref{Ranges and Locales}), but this is no longer true. +Once upon a time, the locale setting used to affect regexp matching, +but this is no longer true (@pxref{Ranges and Locales}). Locales can affect record splitting. For the normal case of @samp{RS = "\n"}, the locale is largely irrelevant. For other single-character @@ -12049,7 +12188,7 @@ 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 @samp{%x} +Europe, however, it is abbreviated ``4.9.15.'' Thus, the @code{%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}. @@ -12091,7 +12230,8 @@ Locales can influence the conversions. @item @command{awk} provides the usual arithmetic operators (addition, subtraction, multiplication, division, modulus), and unary plus and minus. -It also provides comparison operators, boolean operators, and regexp +It also provides comparison operators, boolean operators, array membership +testing, and regexp matching operators. String concatenation is accomplished by placing two expressions next to each other; there is no explicit operator. The three-operand @samp{?:} operator provides an ``if-else'' test within @@ -12106,7 +12246,7 @@ In @command{awk}, a value is considered to be true if it is non-zero @emph{or} non-null. Otherwise, the value is false. @item -A value's type is set upon each assignment and may change over its +A variable's type is set upon each assignment and may change over its lifetime. The type determines how it behaves in comparisons (string or numeric). @@ -12138,7 +12278,7 @@ program, and occasionally the format for data read as input. As you have already seen, each @command{awk} statement consists of a pattern with an associated action. This @value{CHAPTER} describes how you build patterns and actions, what kinds of things you can do within -actions, and @command{awk}'s built-in variables. +actions, and @command{awk}'s predefined variables. The pattern-action rules and the statements available for use within actions form the core of @command{awk} programming. @@ -12153,7 +12293,7 @@ building something useful. * Action Overview:: What goes into an action. * Statements:: Describes the various control statements in detail. -* Built-in Variables:: Summarizes the built-in variables. +* Built-in Variables:: Summarizes the predefined variables. * Pattern Action Summary:: Patterns and Actions summary. @end menu @@ -12186,7 +12326,7 @@ is nonzero (if a number) or non-null (if a string). (@xref{Expression Patterns}.) @item @var{begpat}, @var{endpat} -A pair of patterns separated by a comma, specifying a range of records. +A pair of patterns separated by a comma, specifying a @dfn{range} of records. The range includes both the initial record that matches @var{begpat} and the final record that matches @var{endpat}. (@xref{Ranges}.) @@ -12268,7 +12408,7 @@ Contrast this with the following regular expression match, which accepts any record with a first field that contains @samp{li}: @example -$ @kbd{awk '$1 ~ /foo/ @{ print $2 @}' mail-list} +$ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @print{} 555-5553 @print{} 555-6699 @end example @@ -12276,8 +12416,8 @@ $ @kbd{awk '$1 ~ /foo/ @{ 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 @code{/li/} has the value one if @samp{li} -appears in the current input record. Thus, as a pattern, @code{/li/} +pattern. The expression @samp{/li/} has the value one if @samp{li} +appears in the current input record. Thus, as a pattern, @samp{/li/} matches any record containing @samp{li}. @cindex Boolean expressions, as patterns @@ -12459,7 +12599,7 @@ input is read. For example: @example $ @kbd{awk '} > @kbd{BEGIN @{ print "Analysis of \"li\"" @}} -> @kbd{/li/ @{ ++n @}} +> @kbd{/li/ @{ ++n @}} > @kbd{END @{ print "\"li\" appears in", n, "records." @}' mail-list} @print{} Analysis of "li" @print{} "li" appears in 4 records. @@ -12539,9 +12679,10 @@ The POSIX standard specifies that @code{NF} is available in an @code{END} rule. It contains the number of fields from the last input record. Most probably due to an oversight, the standard does not say that @code{$0} is also preserved, although logically one would think that it should be. -In fact, @command{gawk} does preserve the value of @code{$0} for use in -@code{END} rules. Be aware, however, that BWK @command{awk}, and possibly -other implementations, do not. +In fact, all of BWK @command{awk}, @command{mawk}, and @command{gawk} +preserve the value of @code{$0} for use in @code{END} rules. Be aware, +however, that some other implementations and many older versions +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: @@ -12636,8 +12777,8 @@ level of the @command{awk} program. @cindex @code{next} statement, @code{BEGINFILE}/@code{ENDFILE} patterns and The @code{next} statement (@pxref{Next Statement}) is not allowed inside -either a @code{BEGINFILE} or and @code{ENDFILE} rule. The @code{nextfile} -statement (@pxref{Nextfile Statement}) is allowed only inside a +either a @code{BEGINFILE} or an @code{ENDFILE} rule. The @code{nextfile} +statement is allowed only inside a @code{BEGINFILE} rule, but not inside an @code{ENDFILE} rule. @cindex @code{getline} statement, @code{BEGINFILE}/@code{ENDFILE} patterns and @@ -12701,7 +12842,7 @@ There are two ways to get the value of the shell variable into the body of the @command{awk} program. @cindex shells, quoting -The most common method is to use shell quoting to substitute +A common method is to use shell quoting to substitute the variable's value into the program inside the script. For example, consider the following program: @@ -12958,20 +13099,21 @@ If the @var{condition} is true, it executes the statement @var{body}. is not zero and not a null string.) @end ifinfo After @var{body} has been executed, -@var{condition} is tested again, and if it is still true, @var{body} is -executed again. This process repeats until the @var{condition} is no longer -true. If the @var{condition} is initially false, the body of the loop is -never executed and @command{awk} continues with the statement following +@var{condition} is tested again, and if it is still true, @var{body} +executes again. This process repeats until the @var{condition} is no longer +true. If the @var{condition} is initially false, the body of the loop +never executes and @command{awk} continues with the statement following the loop. This example prints the first three fields of each record, one per line: @example -awk '@{ - i = 1 - while (i <= 3) @{ - print $i - i++ - @} +awk ' +@{ + i = 1 + while (i <= 3) @{ + print $i + i++ + @} @}' inventory-shipped @end example @@ -13005,14 +13147,14 @@ do while (@var{condition}) @end example -Even if the @var{condition} is false at the start, the @var{body} is -executed at least once (and only once, unless executing @var{body} +Even if the @var{condition} is false at the start, the @var{body} +executes at least once (and only once, unless executing @var{body} makes @var{condition} true). Contrast this with the corresponding @code{while} statement: @example while (@var{condition}) - @var{body} + @var{body} @end example @noindent @@ -13022,11 +13164,11 @@ The following is an example of a @code{do} statement: @example @{ - i = 1 - do @{ - print $0 - i++ - @} while (i <= 10) + i = 1 + do @{ + print $0 + i++ + @} while (i <= 10) @} @end example @@ -13063,9 +13205,10 @@ compares it against the desired number of iterations. For example: @example -awk '@{ - for (i = 1; i <= 3; i++) - print $i +awk ' +@{ + for (i = 1; i <= 3; i++) + print $i @}' inventory-shipped @end example @@ -13093,7 +13236,7 @@ between 1 and 100: @example for (i = 1; i <= 100; i *= 2) - print i + print i @end example If there is nothing to be done, any of the three expressions in the @@ -13384,9 +13527,8 @@ the beginning, in the following manner: @example NF != 4 @{ - err = sprintf("%s:%d: skipped: NF != 4\n", FILENAME, FNR) - print err > "/dev/stderr" - next + printf("%s:%d: skipped: NF != 4\n", FILENAME, FNR) > "/dev/stderr" + next @} @end example @@ -13414,7 +13556,7 @@ The @code{next} statement is not allowed inside @code{BEGINFILE} and @cindex functions, user-defined, @code{next}/@code{nextfile} statements and According to the POSIX standard, the behavior is undefined if the @code{next} statement is used in a @code{BEGIN} or @code{END} rule. -@command{gawk} treats it as a syntax error. Although POSIX permits it, +@command{gawk} treats it as a syntax error. Although POSIX does not disallow it, most other @command{awk} implementations don't allow the @code{next} statement inside function bodies (@pxref{User-defined}). Just as with any other @code{next} statement, a @code{next} statement inside a function @@ -13440,7 +13582,8 @@ starts over with the first rule in the program. If the @code{nextfile} statement causes the end of the input to be reached, then the code in any @code{END} rules is executed. An exception to this is when @code{nextfile} is invoked during execution of any statement in an -@code{END} rule; In this case, it causes the program to stop immediately. @xref{BEGIN/END}. +@code{END} rule; in this case, it causes the program to stop immediately. +@xref{BEGIN/END}. The @code{nextfile} statement is useful when there are many @value{DF}s to process but it isn't necessary to process every record in every file. @@ -13450,13 +13593,10 @@ would have to continue scanning the unwanted records. The @code{nextfile} statement accomplishes this much more efficiently. In @command{gawk}, execution of @code{nextfile} causes additional things -to happen: -any @code{ENDFILE} rules are executed except in the case as -mentioned below, -@code{ARGIND} is incremented, -and -any @code{BEGINFILE} rules are executed. -(@code{ARGIND} hasn't been introduced yet. @xref{Built-in Variables}.) +to happen: any @code{ENDFILE} rules are executed if @command{gawk} is +not currently in an @code{END} or @code{BEGINFILE} rule, @code{ARGIND} is +incremented, and any @code{BEGINFILE} rules are executed. (@code{ARGIND} +hasn't been introduced yet. @xref{Built-in Variables}.) With @command{gawk}, @code{nextfile} is useful inside a @code{BEGINFILE} rule to skip over a file that would otherwise cause @command{gawk} @@ -13471,7 +13611,7 @@ opened with redirections. It is not related to the main processing that @quotation NOTE For many years, @code{nextfile} was a -@command{gawk} extension. As of 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 @@ -13480,8 +13620,8 @@ See @uref{http://austingroupbugs.net/view.php?id=607, the Austin Group website}. @cindex @code{nextfile} statement, user-defined functions and @cindex Brian Kernighan's @command{awk} @cindex @command{mawk} utility -The current version of BWK @command{awk}, and @command{mawk} (@pxref{Other -Versions}) also support @code{nextfile}. However, they don't allow the +The current version of BWK @command{awk}, and @command{mawk} +also support @code{nextfile}. However, they don't allow the @code{nextfile} statement inside function bodies (@pxref{User-defined}). @command{gawk} does; a @code{nextfile} inside a function body reads the next record and starts processing it with the first rule in the program, @@ -13513,8 +13653,8 @@ the program to stop immediately. An @code{exit} statement that is not part of a @code{BEGIN} or @code{END} rule stops the execution of any further automatic rules for the current record, skips reading any remaining input records, and executes the -@code{END} rule if there is one. -Any @code{ENDFILE} rules are also skipped; they are not executed. +@code{END} rule if there is one. @command{gawk} also skips +any @code{ENDFILE} rules; they do not execute. In such a case, if you don't want the @code{END} rule to do its job, set a variable @@ -13562,11 +13702,11 @@ results across different operating systems. @c ENDOFRANGE accs @node Built-in Variables -@section Built-in Variables +@section Predefined Variables @c STARTOFRANGE bvar -@cindex built-in variables +@cindex predefined variables @c STARTOFRANGE varb -@cindex variables, built-in +@cindex variables, predefined Most @command{awk} variables are available to use for your own purposes; they never change unless your program assigns values to @@ -13577,8 +13717,8 @@ to tell @command{awk} how to do certain things. Others are set automatically by @command{awk}, so that they carry information from the internal workings of @command{awk} to your program. -@cindex @command{gawk}, built-in variables and -This @value{SECTION} documents all of @command{gawk}'s built-in variables, +@cindex @command{gawk}, predefined variables and +This @value{SECTION} documents all of @command{gawk}'s predefined variables, most of which are also documented in the @value{CHAPTER}s describing their areas of activity. @@ -13593,7 +13733,7 @@ their areas of activity. @node User-modified @subsection Built-in Variables That Control @command{awk} @c STARTOFRANGE bvaru -@cindex built-in variables, user-modifiable +@cindex predefined variables, user-modifiable @c STARTOFRANGE nmbv @cindex user-modifiable variables @@ -13622,7 +13762,7 @@ respectively, should use binary I/O. A string value of @code{"rw"} or @code{"wr"} indicates that all files should use binary I/O. Any other string value is treated the same as @code{"rw"}, but causes @command{gawk} to generate a warning message. @code{BINMODE} is described in more -detail in @ref{PC Using}. @command{mawk} @pxref{Other Versions}), +detail in @ref{PC Using}. @command{mawk} (@pxref{Other Versions}), also supports this variable, but only using numeric values. @cindex @code{CONVFMT} variable @@ -13749,7 +13889,7 @@ printing with the @code{print} statement. It works by being passed as the first argument to the @code{sprintf()} function (@pxref{String Functions}). Its default value is @code{"%.6g"}. Earlier versions of @command{awk} -also used @code{OFMT} to specify the format for converting numbers to +used @code{OFMT} to specify the format for converting numbers to strings in general expressions; this is now done by @code{CONVFMT}. @cindex @code{sprintf()} function, @code{OFMT} variable and @@ -13830,9 +13970,9 @@ The default value of @code{TEXTDOMAIN} is @code{"messages"}. @subsection Built-in Variables That Convey Information @c STARTOFRANGE bvconi -@cindex built-in variables, conveying information +@cindex predefined variables, conveying information @c STARTOFRANGE vbconi -@cindex variables, built-in, conveying information +@cindex variables, predefined conveying information The following is an alphabetical list of variables that @command{awk} sets automatically on certain occasions in order to provide information to your program. @@ -13901,8 +14041,8 @@ successive instances of the same @value{FN} on the command line. @cindex file names, distinguishing While you can change the value of @code{ARGIND} within your @command{awk} -program, @command{gawk} automatically sets it to a new value when the -next file is opened. +program, @command{gawk} automatically sets it to a new value when it +opens the next file. @cindex @code{ENVIRON} array @cindex environment variables, in @code{ENVIRON} array @@ -13967,10 +14107,10 @@ can give @code{FILENAME} a value. @cindex @code{FNR} variable @item @code{FNR} -The current record number in the current file. @code{FNR} is -incremented each time a new record is read -(@pxref{Records}). It is reinitialized -to zero each time a new input file is started. +The current record number in the current file. @command{awk} increments +@code{FNR} each time it reads a new record (@pxref{Records}). +@command{awk} resets @code{FNR} to zero each time it starts a new +input file. @cindex @code{NF} variable @item @code{NF} @@ -13989,7 +14129,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 user-defined or 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} @@ -14002,7 +14142,7 @@ array causes a fatal error. Any attempt to assign to an element of The number of input records @command{awk} has processed since the beginning of the program's execution (@pxref{Records}). -@code{NR} is incremented each time a new record is read. +@command{awk} increments @code{NR} each time it reads a new record. @cindex @command{gawk}, @code{PROCINFO} array in @cindex @code{PROCINFO} array @@ -14030,16 +14170,22 @@ or @code{"FPAT"} if field matching with @code{FPAT} is in effect. @item PROCINFO["identifiers"] @cindex program identifiers -A subarray, indexed by the names of all identifiers used in the -text of the AWK program. For each identifier, the value of the element is one of the following: +A subarray, indexed by the names of all identifiers used in the text of +the AWK program. An @dfn{identifier} is simply the name of a variable +(be it scalar or array), built-in function, user-defined function, or +extension function. For each identifier, the value of the element is +one of the following: @table @code @item "array" The identifier is an array. +@item "builtin" +The identifier is a built-in function. + @item "extension" The identifier is an extension function loaded via -@code{@@load}. +@code{@@load} or @option{-l}. @item "scalar" The identifier is a scalar. @@ -14076,7 +14222,7 @@ The parent process ID of the current process. @item PROCINFO["sorted_in"] If this element exists in @code{PROCINFO}, its value controls the order in which array indices will be processed by -@samp{for (@var{index} in @var{array})} loops. +@samp{for (@var{indx} in @var{array})} loops. Since this is an advanced feature, we defer the full description until later; see @ref{Scanning an Array}. @@ -14097,7 +14243,7 @@ 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 numbers +if your version of @command{gawk} supports arbitrary precision arithmetic (@pxref{Arbitrary Precision Arithmetic}): @table @code @@ -14146,14 +14292,14 @@ The @code{PROCINFO} array has the following additional uses: @itemize @value{BULLET} @item -It may be used to cause coprocesses to communicate over pseudo-ttys -instead of through two-way pipes; this is discussed further in -@ref{Two-way I/O}. - -@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. + +@item +It may be used to cause coprocesses to communicate over pseudo-ttys +instead of through two-way pipes; this is discussed further in +@ref{Two-way I/O}. @end itemize @cindex @code{RLENGTH} variable @@ -14184,9 +14330,13 @@ the record separator. It is set every time a record is read. @cindex @code{SYMTAB} array @cindex differences in @command{awk} and @command{gawk}, @code{SYMTAB} variable @item @code{SYMTAB #} -An array whose indices are the names of all currently defined -global variables and arrays in the program. The array may be used -for indirect access to read or write the value of a variable: +An array whose indices are the names of all defined global variables and +arrays in the program. @code{SYMTAB} makes @command{gawk}'s symbol table +visible to the @command{awk} programmer. It is built as @command{gawk} +parses the program and is complete before the program starts to run. + +The array may be used for indirect access to read or write the value of +a variable: @example foo = 5 @@ -14273,7 +14423,7 @@ changed. @cindex arguments, command-line @cindex command line, arguments -@ref{Auto-set}, +@DBREF{Auto-set} presented the following program describing the information contained in @code{ARGC} and @code{ARGV}: @@ -14395,6 +14545,12 @@ following @option{-v} are passed on to the @command{awk} program. (@xref{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 +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}). + @node Pattern Action Summary @section Summary @@ -14429,7 +14585,7 @@ input and output statements, and deletion statements. The control statements in @command{awk} are @code{if}-@code{else}, @code{while}, @code{for}, and @code{do}-@code{while}. @command{gawk} adds the @code{switch} statement. There are two flavors of @code{for} -statement: one for for performing general looping, and the other iterating +statement: one for performing general looping, and the other for iterating through an array. @item @@ -14446,12 +14602,17 @@ The @code{exit} statement terminates your program. When executed from an action (or function body) it transfers control to the @code{END} statements. From an @code{END} statement body, it exits immediately. You may pass an optional numeric value to be used -at @command{awk}'s exit status. +as @command{awk}'s exit status. @item -Some built-in variables provide control over @command{awk}, mainly for I/O. +Some predefined variables provide control over @command{awk}, mainly for I/O. Other variables convey information from @command{awk} to your program. +@item +@code{ARGC} and @code{ARGV} make the command-line arguments available +to your program. Manipulating them from a @code{BEGIN} rule lets you +control how @command{awk} will process the provided @value{DF}s. + @end itemize @node Arrays @@ -14472,24 +14633,13 @@ The @value{CHAPTER} moves on to discuss @command{gawk}'s facility for sorting arrays, and ends with a brief description of @command{gawk}'s ability to support true arrays of arrays. -@cindex variables, names of -@cindex functions, names of -@cindex arrays, names of, and names of functions/variables -@cindex names, arrays/variables -@cindex namespace issues -@command{awk} maintains a single set -of names that may be used for naming variables, arrays, and functions -(@pxref{User-defined}). -Thus, you cannot have a variable and an array with the same name in the -same @command{awk} program. - @menu * Array Basics:: The basics of arrays. -* Delete:: The @code{delete} statement removes an element - from an array. * Numeric Array Subscripts:: How to use numbers as subscripts in @command{awk}. * Uninitialized Subscripts:: Using Uninitialized variables as subscripts. +* Delete:: The @code{delete} statement removes an element + from an array. * Multidimensional:: Emulating multidimensional arrays in @command{awk}. * Arrays of Arrays:: True multidimensional arrays. @@ -14535,7 +14685,7 @@ as a variable) in the same @command{awk} program. Arrays in @command{awk} superficially resemble arrays in other programming languages, but there are fundamental differences. In @command{awk}, it isn't necessary to specify the size of an array before starting to use it. -Additionally, any number or string in @command{awk}, not just consecutive integers, +Additionally, any number or string, not just consecutive integers, may be used as an array index. In most other languages, arrays must be @dfn{declared} before use, @@ -14648,7 +14798,10 @@ array element value: @end docbook @noindent -The pairs are shown in jumbled order because their order is irrelevant. +The pairs are shown in jumbled order because their order is +irrelevant.@footnote{The ordering will vary among @command{awk} +implementations, which typically use hash tables to store array elements +and values.} One advantage of associative arrays is that new pairs can be added at any time. For example, suppose a tenth element is added to the array @@ -14770,8 +14923,9 @@ English to French: Here we decided to translate the number one in both spelled-out and numeric form---thus illustrating that a single array can have both numbers and strings as indices. -(In fact, array subscripts are always strings; this is discussed -in more detail in +(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 @ref{Numeric Array Subscripts}.) Here, the number @code{1} isn't double-quoted, since @command{awk} automatically converts it to a string. @@ -14858,6 +15012,8 @@ 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 +function.) For example, this statement tests whether the array @code{frequencies} contains the index @samp{2}: @@ -14911,14 +15067,14 @@ begin with a number: @example @c file eg/misc/arraymax.awk @{ - if ($1 > max) - max = $1 - arr[$1] = $0 + if ($1 > max) + max = $1 + arr[$1] = $0 @} END @{ - for (x = 1; x <= max; x++) - print arr[x] + for (x = 1; x <= max; x++) + print arr[x] @} @c endfile @end example @@ -14958,9 +15114,9 @@ program's @code{END} rule, as follows: @example END @{ - for (x = 1; x <= max; x++) - if (x in arr) - print arr[x] + for (x = 1; x <= max; x++) + if (x in arr) + print arr[x] @} @end example @@ -14982,7 +15138,7 @@ an array: @example for (@var{var} in @var{array}) - @var{body} + @var{body} @end example @noindent @@ -15055,7 +15211,7 @@ BEGIN @{ @} @end example -Here is what happens when run with @command{gawk}: +Here is what happens when run with @command{gawk} (and @command{mawk}): @example $ @kbd{gawk -f loopcheck.awk} @@ -15173,7 +15329,8 @@ does not affect the loop. For example: @example -$ @kbd{gawk 'BEGIN @{} +$ @kbd{gawk '} +> @kbd{BEGIN @{} > @kbd{ a[4] = 4} > @kbd{ a[3] = 3} > @kbd{ for (i in a)} @@ -15181,7 +15338,8 @@ $ @kbd{gawk 'BEGIN @{} > @kbd{@}'} @print{} 4 4 @print{} 3 3 -$ @kbd{gawk 'BEGIN @{} +$ @kbd{gawk '} +> @kbd{BEGIN @{} > @kbd{ PROCINFO["sorted_in"] = "@@ind_str_asc"} > @kbd{ a[4] = 4} > @kbd{ a[3] = 3} @@ -15230,118 +15388,6 @@ the @code{delete} statement. In addition, @command{gawk} provides built-in functions for sorting arrays; see @ref{Array Sorting Functions}. -@node Delete -@section The @code{delete} Statement -@cindex @code{delete} statement -@cindex deleting elements in arrays -@cindex arrays, elements, deleting -@cindex elements in arrays, deleting - -To remove an individual element of an array, use the @code{delete} -statement: - -@example -delete @var{array}[@var{index-expression}] -@end example - -Once an array element has been deleted, any value the element once -had is no longer available. It is as if the element had never -been referred to or been given a value. -The following is an example of deleting elements in an array: - -@example -for (i in frequencies) - delete frequencies[i] -@end example - -@noindent -This example removes all the elements from the array @code{frequencies}. -Once an element is deleted, a subsequent @code{for} statement to scan the array -does not report that element and the @code{in} operator to check for -the presence of that element returns zero (i.e., false): - -@example -delete foo[4] -if (4 in foo) - print "This will never be printed" -@end example - -@cindex null strings, and deleting array elements -It is important to note that deleting an element is @emph{not} the -same as assigning it a null value (the empty string, @code{""}). -For example: - -@example -foo[4] = "" -if (4 in foo) - print "This is printed, even though foo[4] is empty" -@end example - -@cindex lint checking, array elements -It is not an error to delete an element that does not exist. -However, if @option{--lint} is provided on the command line -(@pxref{Options}), -@command{gawk} issues a warning message when an element that -is not in the array is deleted. - -@cindex common extensions, @code{delete} to delete entire arrays -@cindex extensions, common@comma{} @code{delete} to delete entire arrays -@cindex arrays, deleting entire contents -@cindex deleting entire arrays -@cindex @code{delete} @var{array} -@cindex differences in @command{awk} and @command{gawk}, array elements, deleting -All the elements of an array may be deleted with a single statement -by leaving off the subscript in the @code{delete} statement, -as follows: - - -@example -delete @var{array} -@end example - -Using this version of the @code{delete} statement is about three times -more efficient than the equivalent loop that deletes each element one -at a time. - -@cindex Brian Kernighan's @command{awk} -@quotation NOTE -For many years, -using @code{delete} without a subscript was a @command{gawk} extension. -As of September, 2012, it was accepted for -inclusion into the POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=544, -the Austin Group website}. This form of the @code{delete} statement is also supported -by BWK @command{awk} and @command{mawk}, as well as -by a number of other implementations (@pxref{Other Versions}). -@end quotation - -@cindex portability, deleting array elements -@cindex Brennan, Michael -The following statement provides a portable but nonobvious way to clear -out an array:@footnote{Thanks to Michael Brennan for pointing this out.} - -@example -split("", array) -@end example - -@cindex @code{split()} function, array elements@comma{} deleting -The @code{split()} function -(@pxref{String Functions}) -clears out the target array first. This call asks it to split -apart the null string. Because there is no data to split out, the -function simply clears the array and then returns. - -@quotation CAUTION -Deleting an array does not change its type; you cannot -delete an array and then use the array's name as a scalar -(i.e., a regular variable). For example, the following does not work: - -@example -a[1] = 3 -delete a -a = 3 -@end example -@end quotation - @node Numeric Array Subscripts @section Using Numbers to Subscript Arrays @@ -15353,7 +15399,7 @@ An important aspect to remember about arrays is that @emph{array subscripts are always strings}. When a numeric value is used as a subscript, it is converted to a string value before being used for subscripting (@pxref{Conversion}). -This means that the value of the built-in variable @code{CONVFMT} can +This means that the value of the predefined variable @code{CONVFMT} can affect how your program accesses elements of an array. For example: @example @@ -15382,7 +15428,7 @@ since @code{"12.15"} is different from @code{"12.153"}. @cindex integer array indices According to the rules for conversions (@pxref{Conversion}), integer -values are always converted to strings as integers, no matter what the +values always convert to strings as integers, no matter what the value of @code{CONVFMT} may happen to be. So the usual case of the following works: @@ -15405,7 +15451,7 @@ and all refer to the same element! As with many things in @command{awk}, the majority of the time -things work as one would expect them to. But it is useful to have a precise +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 effect on your programs. @@ -15426,7 +15472,7 @@ $ @kbd{echo 'line 1} > @kbd{line 2} > @kbd{line 3' | awk '@{ l[lines] = $0; ++lines @}} > @kbd{END @{} -> @kbd{for (i = lines-1; i >= 0; --i)} +> @kbd{for (i = lines - 1; i >= 0; i--)} > @kbd{print l[i]} > @kbd{@}'} @print{} line 3 @@ -15450,7 +15496,7 @@ The following version of the program works correctly: @example @{ l[lines++] = $0 @} END @{ - for (i = lines - 1; i >= 0; --i) + for (i = lines - 1; i >= 0; i--) print l[i] @} @end example @@ -15469,6 +15515,119 @@ Even though it is somewhat unusual, the null string if @option{--lint} is provided on the command line (@pxref{Options}). +@node Delete +@section The @code{delete} Statement +@cindex @code{delete} statement +@cindex deleting elements in arrays +@cindex arrays, elements, deleting +@cindex elements in arrays, deleting + +To remove an individual element of an array, use the @code{delete} +statement: + +@example +delete @var{array}[@var{index-expression}] +@end example + +Once an array element has been deleted, any value the element once +had is no longer available. It is as if the element had never +been referred to or been given a value. +The following is an example of deleting elements in an array: + +@example +for (i in frequencies) + delete frequencies[i] +@end example + +@noindent +This example removes all the elements from the array @code{frequencies}. +Once an element is deleted, a subsequent @code{for} statement to scan the array +does not report that element and the @code{in} operator to check for +the presence of that element returns zero (i.e., false): + +@example +delete foo[4] +if (4 in foo) + print "This will never be printed" +@end example + +@cindex null strings, and deleting array elements +It is important to note that deleting an element is @emph{not} the +same as assigning it a null value (the empty string, @code{""}). +For example: + +@example +foo[4] = "" +if (4 in foo) + print "This is printed, even though foo[4] is empty" +@end example + +@cindex lint checking, array elements +It is not an error to delete an element that does not exist. +However, if @option{--lint} is provided on the command line +(@pxref{Options}), +@command{gawk} issues a warning message when an element that +is not in the array is deleted. + +@cindex common extensions, @code{delete} to delete entire arrays +@cindex extensions, common@comma{} @code{delete} to delete entire arrays +@cindex arrays, deleting entire contents +@cindex deleting entire arrays +@cindex @code{delete} @var{array} +@cindex differences in @command{awk} and @command{gawk}, array elements, deleting +All the elements of an array may be deleted with a single statement +by leaving off the subscript in the @code{delete} statement, +as follows: + + +@example +delete @var{array} +@end example + +Using this version of the @code{delete} statement is about three times +more efficient than the equivalent loop that deletes each element one +at a time. + +This form of the @code{delete} statement is also supported +by BWK @command{awk} and @command{mawk}, as well as +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 +POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=544, +the Austin Group website}. +@end quotation + +@cindex portability, deleting array elements +@cindex Brennan, Michael +The following statement provides a portable but nonobvious way to clear +out an array:@footnote{Thanks to Michael Brennan for pointing this out.} + +@example +split("", array) +@end example + +@cindex @code{split()} function, array elements@comma{} deleting +The @code{split()} function +(@pxref{String Functions}) +clears out the target array first. This call asks it to split +apart the null string. Because there is no data to split out, the +function simply clears the array and then returns. + +@quotation CAUTION +Deleting all the elements from an array does not change its type; you cannot +clear an array and then use the array's name as a scalar +(i.e., a regular variable). For example, the following does not work: + +@example +a[1] = 3 +delete a +a = 3 +@end example +@end quotation + @node Multidimensional @section Multidimensional Arrays @@ -15480,7 +15639,7 @@ on the command line (@pxref{Options}). @cindex arrays, multidimensional 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 most +two-dimensional array requires two indices. The usual way (in many languages, including @command{awk}) to refer to an element of a two-dimensional array named @code{grid} is with @code{grid[@var{x},@var{y}]}. @@ -15655,8 +15814,9 @@ a[1][3][1, "name"] = "barney" Each subarray and the main array can be of different length. In fact, the elements of an array or its subarray do not all have to have the same type. This means that the main array and any of its subarrays can be -non-rectangular, or jagged in structure. One can assign a scalar value to -the index @code{4} of the main array @code{a}: +non-rectangular, or jagged in structure. You can assign a scalar value to +the index @code{4} of the main array @code{a}, even though @code{a[1]} +is itself an array and not a scalar: @example a[4] = "An element in a jagged array" @@ -15738,6 +15898,8 @@ for (i in array) @{ print array[i][j] @} @} + else + print array[i] @} @end example @@ -16022,8 +16184,9 @@ Often random integers are needed instead. Following is a user-defined function that can be used to obtain a random non-negative integer less than @var{n}: @example -function randint(n) @{ - return int(n * rand()) +function randint(n) +@{ + return int(n * rand()) @} @end example @@ -16043,8 +16206,7 @@ function roll(n) @{ return 1 + int(rand() * n) @} # Roll 3 six-sided dice and # print total number of points. @{ - printf("%d points\n", - roll(6)+roll(6)+roll(6)) + printf("%d points\n", roll(6) + roll(6) + roll(6)) @} @end example @@ -16133,7 +16295,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 in alphabetic order. +towards the end since 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 @@ -16177,6 +16339,7 @@ When comparing strings, @code{IGNORECASE} affects the sorting (@pxref{Array Sorting Functions}). If the @var{source} array contains subarrays as values (@pxref{Arrays of Arrays}), they will come last, after all scalar values. +Subarrays are @emph{not} recursively sorted. For example, if the contents of @code{a} are as follows: @@ -16313,7 +16476,10 @@ $ @kbd{awk 'BEGIN @{ print index("peanut", "an") @}'} @noindent If @var{find} is not found, @code{index()} returns zero. -It is a fatal error to use a regexp constant for @var{find}. +With BWK @command{awk} and @command{gawk}, +it is a fatal error to use a regexp constant for @var{find}. +Other implementations allow it, simply treating the regexp +constant as an expression meaning @samp{$0 ~ /regexp/}. @value{DARKCORNER}. @item @code{length(}[@var{string}]@code{)} @cindexawkfunc{length} @@ -16417,8 +16583,8 @@ for @code{match()}, the order is the same as for the @samp{~} operator: @cindex @code{RSTART} variable, @code{match()} function and @cindex @code{RLENGTH} variable, @code{match()} function and @cindex @code{match()} function, @code{RSTART}/@code{RLENGTH} variables -The @code{match()} function sets the built-in variable @code{RSTART} to -the index. It also sets the built-in variable @code{RLENGTH} to the +The @code{match()} function sets the predefined variable @code{RSTART} to +the index. It also sets the predefined variable @code{RLENGTH} to the length in characters of the matched substring. If no match is found, @code{RSTART} is set to zero, and @code{RLENGTH} to @minus{}1. @@ -16427,13 +16593,12 @@ For example: @example @c file eg/misc/findpat.awk @{ - if ($1 == "FIND") - regex = $2 - else @{ - where = match($0, regex) - if (where != 0) - print "Match of", regex, "found at", - where, "in", $0 + if ($1 == "FIND") + regex = $2 + else @{ + where = match($0, regex) + if (where != 0) + print "Match of", regex, "found at", where, "in", $0 @} @} @c endfile @@ -16529,7 +16694,7 @@ Any leading separator will be in @code{@var{seps}[0]}. The @code{patsplit()} function splits strings into pieces in a manner similar to the way input lines are split into fields using @code{FPAT} -(@pxref{Splitting By Content}. +(@pxref{Splitting By Content}). Before splitting the string, @code{patsplit()} deletes any previously existing elements in the arrays @var{array} and @var{seps}. @@ -16542,8 +16707,7 @@ and store the pieces in @var{array} and the separator strings in the @code{@var{array}[1]}, the second piece in @code{@var{array}[2]}, and so forth. The string value of the third argument, @var{fieldsep}, is a regexp describing where to split @var{string} (much as @code{FS} can -be a regexp describing where to split input records; -@pxref{Regexp Field Splitting}). +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}]} @@ -16838,6 +17002,26 @@ Nonalphabetic characters are left unchanged. For example, @code{toupper("MiXeD cAsE 123")} returns @code{"MIXED CASE 123"}. @end table +@sidebar Matching the Null String +@cindex matching, null strings +@cindex null strings, matching +@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching +@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching + +In @command{awk}, the @samp{*} operator can match the null string. +This is particularly important for the @code{sub()}, @code{gsub()}, +and @code{gensub()} functions. For example: + +@example +$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'} +@print{} XaXbXcX +@end example + +@noindent +Although this makes a certain amount of sense, it can be surprising. +@end sidebar + + @node Gory Details @subsubsection More About @samp{\} and @samp{&} with @code{sub()}, @code{gsub()}, and @code{gensub()} @@ -16851,7 +17035,7 @@ Nonalphabetic characters are left unchanged. For example, @cindex ampersand (@code{&}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @quotation CAUTION -This section has been known to cause headaches. +This subsubsection has been reported to cause headaches. You might want to skip it upon first reading. @end quotation @@ -17142,25 +17326,6 @@ and the special cases for @code{sub()} and @code{gsub()}, we recommend the use of @command{gawk} and @code{gensub()} when you have to do substitutions. -@sidebar Matching the Null String -@cindex matching, null strings -@cindex null strings, matching -@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching -@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching - -In @command{awk}, the @samp{*} operator can match the null string. -This is particularly important for the @code{sub()}, @code{gsub()}, -and @code{gensub()} functions. For example: - -@example -$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'} -@print{} XaXbXcX -@end example - -@noindent -Although this makes a certain amount of sense, it can be surprising. -@end sidebar - @node I/O Functions @subsection Input/Output Functions @cindex input/output functions @@ -17213,10 +17378,9 @@ buffers its output and the @code{fflush()} function forces @cindex extensions, common@comma{} @code{fflush()} function @cindex Brian Kernighan's @command{awk} -@code{fflush()} was added to BWK @command{awk} in -April of 1992. For two decades, it was not part of the POSIX standard. -As of December, 2012, it was accepted for inclusion into the POSIX -standard. +Brian Kernighan added @code{fflush()} to his @command{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 @uref{http://austingroupbugs.net/view.php?id=634, the Austin Group website}. POSIX standardizes @code{fflush()} as follows: If there @@ -17485,7 +17649,7 @@ is out of range, @code{mktime()} returns @minus{}1. @cindex @command{gawk}, @code{PROCINFO} array in @cindex @code{PROCINFO} array -@item @code{strftime(} [@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag}] ] ]@code{)} +@item @code{strftime(}[@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag}] ] ]@code{)} @c STARTOFRANGE strf @cindexgawkfunc{strftime} @cindex format time string @@ -17591,7 +17755,7 @@ of its ISO week number is 2013, even though its year is 2012. The full year of the ISO week number, as a decimal number. @item %h -Equivalent to @samp{%b}. +Equivalent to @code{%b}. @item %H The hour (24-hour clock) as a decimal number (00--23). @@ -17660,7 +17824,7 @@ The locale's ``appropriate'' date representation. @item %X The locale's ``appropriate'' time representation. -(This is @samp{%T} in the @code{"C"} locale.) +(This is @code{%T} in the @code{"C"} locale.) @item %y The year modulo 100 as a decimal number (00--99). @@ -17681,7 +17845,7 @@ 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 (@samp{%c}, @samp{%C}, +that use only the second letter (@code{%c}, @code{%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. @@ -17752,7 +17916,7 @@ the string. For example: @example $ date '+Today is %A, %B %d, %Y.' -@print{} Today is Monday, May 05, 2014. +@print{} Today is Monday, September 22, 2014. @end example Here is the @command{gawk} version of the @command{date} utility. @@ -17944,19 +18108,18 @@ For example, if you have a bit string @samp{10111001} and you shift it right by three bits, you end up with @samp{00010111}.@footnote{This example shows that 0's come in on the left side. For @command{gawk}, this is always true, but in some languages, it's possible to have the left side -fill with 1's. Caveat emptor.} +fill with 1's.} @c Purposely decided to use 0's and 1's here. 2/2001. -If you start over -again with @samp{10111001} and shift it left by three bits, you end up -with @samp{11001000}. -@command{gawk} provides built-in functions that implement the -bitwise operations just described. They are: +If you start over again with @samp{10111001} and shift it left by three +bits, you end up with @samp{11001000}. The following list describes +@command{gawk}'s built-in functions that implement the bitwise operations. +Optional parameters are enclosed in square brackets ([ ]): @cindex @command{gawk}, bitwise operations in @table @code @cindexgawkfunc{and} @cindex bitwise AND -@item @code{and(@var{v1}, @var{v2}} [@code{,} @dots{}]@code{)} +@item @code{and(}@var{v1}@code{,} @var{v2} [@code{,} @dots{}]@code{)} Return the bitwise AND of the arguments. There must be at least two. @cindexgawkfunc{compl} @@ -17971,7 +18134,7 @@ Return the value of @var{val}, shifted left by @var{count} bits. @cindexgawkfunc{or} @cindex bitwise OR -@item @code{or(@var{v1}, @var{v2}} [@code{,} @dots{}]@code{)} +@item @code{or(}@var{v1}@code{,} @var{v2} [@code{,} @dots{}]@code{)} Return the bitwise OR of the arguments. There must be at least two. @cindexgawkfunc{rshift} @@ -17981,7 +18144,7 @@ Return the value of @var{val}, shifted right by @var{count} bits. @cindexgawkfunc{xor} @cindex bitwise XOR -@item @code{xor(@var{v1}, @var{v2}} [@code{,} @dots{}]@code{)} +@item @code{xor(}@var{v1}@code{,} @var{v2} [@code{,} @dots{}]@code{)} Return the bitwise XOR of the arguments. There must be at least two. @end table @@ -18104,7 +18267,7 @@ results of the @code{compl()}, @code{lshift()}, and @code{rshift()} functions. @command{gawk} provides a single function that lets you distinguish an array from a scalar variable. This is necessary for writing code -that traverses every element of an array of arrays. +that traverses every element of an array of arrays (@pxref{Arrays of Arrays}). @table @code @@ -18120,12 +18283,14 @@ an array or not. The second is inside the body of a user-defined function (not discussed yet; @pxref{User-defined}), to test if a parameter is an array or not. -Note, however, that using @code{isarray()} at the global level to test +@quotation NOTE +Using @code{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 @command{gawk} works, if you pass the name of a variable that has not been previously used to @code{isarray()}, @command{gawk} -will end up turning it into a scalar. +ends up turning it into a scalar. +@end quotation @node I18N Functions @subsection String-Translation Functions @@ -18202,6 +18367,12 @@ them, i.e., to tell @command{awk} what they should do. @node Definition Syntax @subsection Function Definition Syntax +@quotation +@i{It's entirely fair to say that the @command{awk} syntax for local +variable definitions is appallingly awful.} +@author Brian Kernighan +@end quotation + @c STARTOFRANGE fdef @cindex functions, defining Definitions of functions can appear anywhere between the rules of an @@ -18228,6 +18399,8 @@ The definition of a function named @var{name} looks like this: Here, @var{name} is the name of the function to define. A valid function name is like a valid variable name: a sequence of letters, digits, and underscores that doesn't start with a digit. +Here too, only the 52 upper- and lowercase English letters may +be used in a function name. Within a single @command{awk} program, any particular name can only be used as a variable, array, or function. @@ -18239,9 +18412,9 @@ the call. A function cannot have two parameters with the same name, nor may it have a parameter with the same name as the function itself. In addition, according to the POSIX standard, function parameters -cannot have the same name as one of the special built-in variables +cannot have the same name as one of the special predefined variables (@pxref{Built-in Variables}). Not all versions of @command{awk} enforce -this restriction.) +this restriction. Local variables act like the empty string if referenced where a string value is required, and like zero if referenced where a numeric value @@ -18378,7 +18551,7 @@ extra whitespace signifies the start of the local variable list): function delarray(a, i) @{ for (i in a) - delete a[i] + delete a[i] @} @end example @@ -18389,7 +18562,7 @@ Instead of having to repeat this loop everywhere that you need to clear out an array, your program can just call @code{delarray}. (This guarantees portability. The use of @samp{delete @var{array}} to delete -the contents of an entire array is a recent@footnote{Late in 2012.} +the contents of an entire array is a relatively recent@footnote{Late in 2012.} addition to the POSIX standard.) The following is an example of a recursive function. It takes a string @@ -18419,7 +18592,7 @@ $ @kbd{echo "Don't Panic!" |} @print{} !cinaP t'noD @end example -The C @code{ctime()} function takes a timestamp and returns it in a string, +The C @code{ctime()} function takes a timestamp and returns it as a string, formatted in a well-known fashion. The following example uses the built-in @code{strftime()} function (@pxref{Time Functions}) @@ -18434,13 +18607,19 @@ to create an @command{awk} version of @code{ctime()}: function ctime(ts, format) @{ - format = PROCINFO["strftime"] + format = "%a %b %e %H:%M:%S %Z %Y" + if (ts == 0) ts = systime() # use current time as default return strftime(format, ts) @} @c endfile @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 +supposed to return the time formatted in a standard fashion, and user-level +code could have changed @code{PROCINFO["strftime"]}. @c ENDOFRANGE fdef @node Function Caveats @@ -18876,7 +19055,7 @@ being aware of them. @cindex pointers to functions @cindex differences in @command{awk} and @command{gawk}, indirect function calls -This section describes a @command{gawk}-specific extension. +This section describes an advanced, @command{gawk}-specific extension. Often, you may wish to defer the choice of function to call until runtime. For example, you may have different kinds of records, each of which @@ -18922,8 +19101,11 @@ To process the data, you might write initially: @noindent This style of programming works, but can be awkward. With @dfn{indirect} function calls, you tell @command{gawk} to use the @emph{value} of a -variable as the name of the function to call. +variable as the @emph{name} of the function to call. +@cindex @code{@@}-notation for indirect function calls +@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{@@} @@ -18981,7 +19163,6 @@ Otherwise they perform the expected computations and are not unusual. @example @c file eg/prog/indirectcall.awk # For each record, print the class name and the requested statistics - @{ class_name = $1 gsub(/_/, " ", class_name) # Replace _ with spaces @@ -19010,7 +19191,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 @samp{%s} as the format specifier so that we +(The @code{printf} format string uses @code{%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.) @@ -19087,7 +19268,7 @@ function quicksort(data, left, right, less_than, i, last) # quicksort_swap --- helper function for quicksort, should really be inline -function quicksort_swap(data, i, j, temp) +function quicksort_swap(data, i, j, temp) @{ temp = data[i] data[i] = data[j] @@ -19208,12 +19389,77 @@ $ @kbd{gawk -f quicksort.awk -f indirectcall.awk class_data2} @print{} rsort: <100.0 95.6 93.4 87.1> @end example +Another example where indirect functions calls are useful can be found in +processing arrays. @DBREF{Walking Arrays} presented a simple function +for ``walking'' an array of arrays. That function simply printed the +name and value of each scalar array element. However, it is easy to +generalize that function, by passing in the name of a function to call +when walking an array. The modified function looks like this: + +@example +@c file eg/lib/processarray.awk +function process_array(arr, name, process, do_arrays, i, new_name) +@{ + for (i in arr) @{ + new_name = (name "[" i "]") + if (isarray(arr[i])) @{ + if (do_arrays) + @@process(new_name, arr[i]) + process_array(arr[i], new_name, process, do_arrays) + @} else + @@process(new_name, arr[i]) + @} +@} +@c endfile +@end example + +The arguments are as follows: + +@table @code +@item arr +The array. + +@item name +The name of the array (a string). + +@item process +The name of the function to call. + +@item do_arrays +If this is true, the function can handle elements that are subarrays. +@end table + +If subarrays are to be processed, that is done before walking them further. + +When run with the following scaffolding, the function produces the same +results as does the earlier @code{walk_array()} function: + +@example +BEGIN @{ + a[1] = 1 + a[2][1] = 21 + a[2][2] = 22 + a[3] = 3 + a[4][1][1] = 411 + a[4][2] = 42 + + process_array(a, "a", "do_print", 0) +@} + +function do_print(name, element) +@{ + printf "%s = %s\n", name, element +@} +@end example + Remember that you must supply a leading @samp{@@} in front of an indirect function call. -Unfortunately, indirect function calls cannot be used with the built-in functions. However, -you can generally write ``wrapper'' functions which call the built-in ones, and those can -be called indirectly. (Other than, perhaps, the mathematical functions, there is not a lot -of reason to try to call the built-in functions indirectly.) +Starting with @value{PVERSION} 4.1.2 of @command{gawk}, indirect function +calls may also be used with built-in functions and with extension functions +(@pxref{Dynamic Extensions}). The only thing you cannot do is pass a regular +expression constant to a built-in function through an indirect function +call.@footnote{This may change in a future version; recheck the documentation that +comes with your version of @command{gawk} to see if it has.} @command{gawk} does its best to make indirect function calls efficient. For example, in the following case: @@ -19224,7 +19470,7 @@ for (i = 1; i <= n; i++) @end example @noindent -@code{gawk} will look up the actual function to call only once. +@code{gawk} looks up the actual function to call only once. @node Functions Summary @section Summary @@ -19236,10 +19482,11 @@ functions. @item POSIX @command{awk} provides three kinds of built-in functions: numeric, -string, and I/O. @command{gawk} provides functions that work with values -representing time, do bit manipulation, sort arrays, and internationalize -and localize programs. @command{gawk} also provides several extensions to -some of standard functions, typically in the form of additional arguments. +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. +@command{gawk} also provides several extensions to some of standard +functions, typically in the form of additional arguments. @item Functions accept zero or more arguments and return a value. The @@ -19264,6 +19511,8 @@ from the real parameters by extra whitespace. User-defined functions may call other user-defined (and built-in) functions and may call themselves recursively. Function parameters ``hide'' any global variables of the same names. +You cannot use the name of a reserved variable (such as @code{ARGC}) +as the name of a parameter in user-defined functions. @item Scalar values are passed to user-defined functions by value. Array @@ -19282,7 +19531,7 @@ either scalar or array. @item @command{gawk} provides indirect function calls using a special syntax. -By setting a variable to the name of a user-defined function, you can +By setting a variable to the name of a function, you can determine at runtime what function will be called at that point in the program. This is equivalent to function pointers in C and C++. @@ -19317,7 +19566,7 @@ It contains the following chapters: @c STARTOFRANGE fudlib @cindex functions, user-defined, library of -@ref{User-defined}, describes how to write +@DBREF{User-defined} describes how to write your own @command{awk} functions. Writing functions is important, because it allows you to encapsulate algorithms and program tasks in a single place. It simplifies programming, making program development more @@ -19350,7 +19599,7 @@ use these functions. The functions are presented here in a progression from simple to complex. @cindex Texinfo -@ref{Extract Program}, +@DBREF{Extract Program} presents a program that you can use to extract the source code for these example library functions and programs from the Texinfo source for this @value{DOCUMENT}. @@ -19414,7 +19663,7 @@ comparisons use only lowercase letters. * Group Functions:: Functions for getting group information. * Walking Arrays:: A function to walk arrays of arrays. * Library Functions Summary:: Summary of library functions. -* Library exercises:: Exercises. +* Library Exercises:: Exercises. @end menu @node Library Names @@ -19474,7 +19723,7 @@ example, @code{getopt()}'s @code{Opterr} and @code{Optind} variables (@pxref{Getopt Function}). The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the variable is -not one of @command{awk}'s built-in variables, such as @code{FS}. +not one of @command{awk}'s predefined variables, such as @code{FS}. @cindex @option{--dump-variables} option, using for library functions It is also important that @emph{all} variables in library @@ -19488,8 +19737,9 @@ are very difficult to track down: function lib_func(x, y, l1, l2) @{ @dots{} - @var{use variable} some_var # some_var should be local - @dots{} # but is not by oversight + # some_var should be local but by oversight is not + @var{use variable} some_var + @dots{} @} @end example @@ -19501,7 +19751,7 @@ A different convention, common in the Tcl community, is to use a single associative array to hold the values needed by the library function(s), or ``package.'' This significantly decreases the number of actual global names in use. For example, the functions described in -@ref{Passwd Functions}, +@DBREF{Passwd Functions} might have used array elements @code{@w{PW_data["inited"]}}, @code{@w{PW_data["total"]}}, @code{@w{PW_data["count"]}}, and @code{@w{PW_data["awklib"]}}, instead of @code{@w{_pw_inited}}, @code{@w{_pw_awklib}}, @code{@w{_pw_total}}, @@ -19530,6 +19780,7 @@ programming use. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the shell. @end menu @node Strtonum Function @@ -19562,8 +19813,9 @@ function mystrtonum(str, ret, n, i, k, c) ret = 0 for (i = 1; i <= n; i++) @{ c = substr(str, i, 1) - if ((k = index("01234567", c)) > 0) - k-- # adjust for 1-basing in awk + # index() returns 0 if c not in string, + # includes c == "0" + k = index("1234567", c) ret = ret * 8 + k @} @@ -19575,6 +19827,8 @@ function mystrtonum(str, ret, n, i, k, c) for (i = 1; i <= n; i++) @{ c = substr(str, i, 1) c = tolower(c) + # index() returns 0 if c not in string, + # includes c == "0" k = index("123456789abcdef", c) ret = ret * 16 + k @@ -19597,7 +19851,7 @@ function mystrtonum(str, ret, n, i, k, c) # a[5] = "123.45" # a[6] = "1.e3" # a[7] = "1.32" -# a[7] = "1.32E2" +# a[8] = "1.32E2" # # for (i = 1; i in a; i++) # print a[i], strtonum(a[i]), mystrtonum(a[i]) @@ -19608,9 +19862,12 @@ function mystrtonum(str, ret, n, i, k, c) The function first looks for C-style octal numbers (base 8). If the input string matches a regular expression describing octal numbers, then @code{mystrtonum()} loops through each character in the -string. It sets @code{k} to the index in @code{"01234567"} of the current -octal digit. Since the return value is one-based, the @samp{k--} -adjusts @code{k} so it can be used in computing the return value. +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 +only octal values are converted. Similar logic applies to the code that checks for and converts a hexadecimal value, which starts with @samp{0x} or @samp{0X}. @@ -19643,7 +19900,7 @@ that a condition or set of conditions is true. Before proceeding with a particular computation, you make a statement about what you believe to be the case. Such a statement is known as an @dfn{assertion}. The C language provides an @code{<assert.h>} header file -and corresponding @code{assert()} macro that the programmer can use to make +and corresponding @code{assert()} macro that a programmer can use to make assertions. If an assertion fails, the @code{assert()} macro arranges to print a diagnostic message describing the condition that should have been true but was not, and then it kills the program. In C, using @@ -19976,8 +20233,7 @@ function chr(c) @c endfile #### test code #### -# BEGIN \ -# @{ +# BEGIN @{ # for (;;) @{ # printf("enter a character: ") # if (getline var <= 0) @@ -20062,7 +20318,7 @@ more difficult than they really need to be.} @cindex timestamps, formatted @cindex time, managing The @code{systime()} and @code{strftime()} functions described in -@ref{Time Functions}, +@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 formats are not necessarily easy to remember or intuitively obvious when @@ -20114,7 +20370,7 @@ function getlocaltime(time, ret, now, i) now = systime() # return date(1)-style output - ret = strftime(PROCINFO["strftime"], now) + ret = strftime("%a %b %e %H:%M:%S %Z %Y", now) # clear out target array delete time @@ -20148,7 +20404,7 @@ function getlocaltime(time, ret, now, i) The string indices are easier to use and read than the various formats required by @code{strftime()}. The @code{alarm} program presented in -@ref{Alarm Program}, +@DBREF{Alarm Program} uses this function. A more general design for the @code{getlocaltime()} function would have allowed the user to supply an optional timestamp value to use instead @@ -20229,6 +20485,87 @@ if (length(contents) == 0) This tests the result to see if it is empty or not. An equivalent test would be @samp{contents == ""}. +@xref{Extension Sample Readfile}, for an extension function that +also reads an entire file into memory. + +@node Shell Quoting +@subsection Quoting Strings to Pass to The Shell + +@c included by permission +@ignore +Date: Sun, 27 Jul 2014 17:16:16 -0700 +Message-ID: <CAKuGj+iCF_obaCLDUX60aSAgbfocFVtguG39GyeoNxTFby5sqQ@mail.gmail.com> +Subject: Useful awk function +From: Mike Brennan <mike@madronabluff.com> +To: Arnold Robbins <arnold@skeeve.com> +@end ignore + +Michael Brennan offers the following programming pattern, +which he uses frequently: + +@example +#! /bin/sh + +awkp=' + @dots{} + ' + +@var{input_program} | awk "$awkp" | /bin/sh +@end example + +For example, a program of his named @command{flac-edit} has this form: + +@example +$ @kbd{flac-edit -song="Whoope! That's Great" file.flac} +@end example + +It generates the following output, which is to be piped to +the shell (@file{/bin/sh}): + +@example +chmod +w file.flac +metaflac --remove-tag=TITLE file.flac +LANG=en_US.88591 metaflac --set-tag=TITLE='Whoope! That'"'"'s Great' file.flac +chmod -w file.flac +@end example + +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{"\"'\""}. + +@example +@c file eg/lib/shellquote.awk +# shell_quote --- quote an argument for passing to the shell +@c endfile +@ignore +@c file eg/lib/shellquote.awk +# +# Michael Brennan +# brennan@@madronabluff.com +# September 2014 +@c endfile +@end ignore +@c file eg/lib/shellquote.awk + +function shell_quote(s, # parameter + SINGLE, QSINGLE, i, X, n, ret) # locals +@{ + if (s == "") + return "\"\"" + + SINGLE = "\x27" # single quote + QSINGLE = "\"\x27\"" + n = split(s, X, SINGLE) + + ret = SINGLE X[1] SINGLE + for (i = 2; i <= n; i++) + ret = ret QSINGLE SINGLE X[i] SINGLE + + return ret +@} +@c endfile +@end example + @node Data File Management @section @value{DDF} Management @@ -20286,15 +20623,14 @@ Besides solving the problem in only nine(!) lines of code, it does so @c # Arnold Robbins, arnold@@skeeve.com, Public Domain @c # January 1992 -FILENAME != _oldfilename \ -@{ +FILENAME != _oldfilename @{ if (_oldfilename != "") endfile(_oldfilename) _oldfilename = FILENAME beginfile(FILENAME) @} -END @{ endfile(FILENAME) @} +END @{ endfile(FILENAME) @} @end example This file must be loaded before the user's ``main'' program, so that the @@ -20347,11 +20683,11 @@ FNR == 1 @{ beginfile(FILENAME) @} -END @{ endfile(_filename_) @} +END @{ endfile(_filename_) @} @c endfile @end example -@ref{Wc Program}, +@DBREF{Wc Program} shows how this library function can be used and how it simplifies writing the main program. @@ -20417,24 +20753,12 @@ function rewind( i) @c endfile @end example -This code relies on the @code{ARGIND} variable -(@pxref{Auto-set}), -which is specific to @command{gawk}. -If you are not using -@command{gawk}, you can use ideas presented in -@ifnotinfo -the previous @value{SECTION} -@end ifnotinfo -@ifinfo -@ref{Filetrans Function}, -@end ifinfo -to either update @code{ARGIND} on your own -or modify this code as appropriate. - -The @code{rewind()} function 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!) +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!) @node File Checking @subsection Checking for Readable @value{DDF}s @@ -20467,7 +20791,7 @@ the following program to your @command{awk} program: BEGIN @{ for (i = 1; i < ARGC; i++) @{ - if (ARGV[i] ~ /^[[:alpha:]_][[:alnum:]_]*=.*/ \ + if (ARGV[i] ~ /^[a-zA-Z_][a-zA-Z0-9_]*=.*/ \ || ARGV[i] == "-" || ARGV[i] == "/dev/stdin") continue # assignment or standard input else if ((getline junk < ARGV[i]) < 0) # unreadable @@ -20485,6 +20809,11 @@ Removing the element from @code{ARGV} with @code{delete} skips the file (since it's no longer in the list). See also @ref{ARGC and ARGV}. +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 @@ -20581,7 +20910,7 @@ a library file does the trick: function disable_assigns(argc, argv, i) @{ for (i = 1; i < argc; i++) - if (argv[i] ~ /^[[:alpha:]_][[:alnum:]_]*=.*/) + if (argv[i] ~ /^[a-zA-Z_][a-zA-Z0-9_]*=.*/) argv[i] = ("./" argv[i]) @} @@ -20822,8 +21151,7 @@ it is not an option, and it ends option processing. Continuing on: i = index(options, thisopt) if (i == 0) @{ if (Opterr) - printf("%c -- invalid option\n", - thisopt) > "/dev/stderr" + printf("%c -- invalid option\n", thisopt) > "/dev/stderr" if (_opti >= length(argv[Optind])) @{ Optind++ _opti = 0 @@ -20954,12 +21282,18 @@ In both runs, the first @option{--} terminates the arguments to etc., as its own options. @quotation NOTE -After @code{getopt()} is through, it is the responsibility of the -user level code to clear out all the elements of @code{ARGV} from 1 +After @code{getopt()} is through, +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 +further options +(@pxref{Executable Scripts}, and @pxref{Options}). + Several of the sample programs presented in @ref{Sample Programs}, use @code{getopt()} to process their arguments. @@ -21204,13 +21538,14 @@ The @code{BEGIN} rule sets a private variable to the directory where routine, we have chosen to put it in @file{/usr/local/libexec/awk}; however, you might want it to be in a different directory on your system. -The function @code{_pw_init()} keeps three copies of the user information -in three associative arrays. The arrays are indexed by username +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()} needs to be called only once. +@cindex @code{PROCINFO} array, testing the field splitting @cindex @code{getline} command, @code{_pw_init()} function 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}. @@ -21218,13 +21553,8 @@ 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 from anywhere within a user's program, and the user may have his -or her -own way of splitting records and fields. - -@cindex @code{PROCINFO} array, testing the field splitting -The @code{using_fw} variable checks @code{PROCINFO["FS"]}, which -is @code{"FIELDWIDTHS"} if field splitting is being done with -@code{FIELDWIDTHS}. This makes it possible to restore the correct +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 @command{gawk}. It is false if using @code{FS} or @code{FPAT}, or on some other @command{awk} implementation. @@ -21326,7 +21656,7 @@ once. If you are worried about squeezing every last cycle out of your this is not necessary, since most @command{awk} programs are I/O-bound, and such a change would clutter up the code. -The @command{id} program in @ref{Id Program}, +The @command{id} program in @DBREF{Id Program} uses these functions. @c ENDOFRANGE libfudata @c ENDOFRANGE flibudata @@ -21352,7 +21682,7 @@ uses these functions. @cindex group file @cindex files, group Much of the discussion presented in -@ref{Passwd Functions}, +@DBREF{Passwd Functions} applies to the group database as well. Although there has traditionally been a well-known file (@file{/etc/group}) in a well-known format, the POSIX standard only provides a set of C library routines @@ -21505,8 +21835,7 @@ There are several, modeled after the C library functions of the same names: @c line break on _gr_init for smallbook @c file eg/lib/groupawk.in -BEGIN \ -@{ +BEGIN @{ # Change to suit your system _gr_awklib = "/usr/local/libexec/awk/" @} @@ -21539,8 +21868,7 @@ function _gr_init( oldfs, oldrs, olddol0, grcat, n = split($4, a, "[ \t]*,[ \t]*") for (i = 1; i <= n; i++) if (a[i] in _gr_groupsbyuser) - _gr_groupsbyuser[a[i]] = \ - _gr_groupsbyuser[a[i]] " " $1 + _gr_groupsbyuser[a[i]] = gr_groupsbyuser[a[i]] " " $1 else _gr_groupsbyuser[a[i]] = $1 @@ -21692,13 +22020,13 @@ Most of the work is in scanning the database and building the various associative arrays. The functions that the user calls are themselves very simple, relying on @command{awk}'s associative arrays to do work. -The @command{id} program in @ref{Id Program}, +The @command{id} program in @DBREF{Id Program} uses these functions. @node Walking Arrays @section Traversing Arrays of Arrays -@ref{Arrays of Arrays}, described how @command{gawk} +@DBREF{Arrays of Arrays} described how @command{gawk} provides arrays of arrays. In particular, any element of an array may be either a scalar, or another array. The @code{isarray()} function (@pxref{Type Functions}) @@ -21748,12 +22076,12 @@ When run, the program produces the following output: @example $ @kbd{gawk -f walk_array.awk} -@print{} a[4][1][1] = 411 -@print{} a[4][2] = 42 @print{} a[1] = 1 @print{} a[2][1] = 21 @print{} a[2][2] = 22 @print{} a[3] = 3 +@print{} a[4][1][1] = 411 +@print{} a[4][2] = 42 @end example @c ENDOFRANGE libfgdata @@ -21767,8 +22095,8 @@ $ @kbd{gawk -f walk_array.awk} @itemize @value{BULLET} @item Reading programs is an excellent way to learn Good Programming. -The functions provided in this @value{CHAPTER} and the next are intended -to serve that purpose. +The functions and programs provided in this @value{CHAPTER} and the next +are intended to serve that purpose. @item When writing general-purpose library functions, put some thought into how @@ -21804,7 +22132,8 @@ A simple function to traverse an array of arrays to any depth. @end itemize -@node Library exercises +@c EXCLUDE START +@node Library Exercises @section Exercises @enumerate @@ -21852,7 +22181,7 @@ As a related challenge, revise that code to handle the case where an intervening value in @code{ARGV} is a variable assignment. @item -@ref{Walking Arrays}, presented a function that walked a multidimensional +@DBREF{Walking Arrays} presented a function that walked a multidimensional array to print it out. However, walking an array and processing each element is a general-purpose operation. Generalize the @code{walk_array()} function by adding an additional parameter named @@ -21870,6 +22199,7 @@ Test your new version by printing the array; you should end up with output identical to that of the original version. @end enumerate +@c EXCLUDE END @c ENDOFRANGE flib @c ENDOFRANGE fudlib @@ -22053,22 +22383,16 @@ supplied: # Requires getopt() and join() library functions @group -function usage( e1, e2) +function usage() @{ - e1 = "usage: cut [-f list] [-d c] [-s] [files...]" - e2 = "usage: cut [-c list] [files...]" - print e1 > "/dev/stderr" - print e2 > "/dev/stderr" + print("usage: cut [-f list] [-d c] [-s] [files...]") > "/dev/stderr" + print("usage: cut [-c list] [files...]") > "/dev/stderr" exit 1 @} @end group @c endfile @end example -@noindent -The variables @code{e1} and @code{e2} are used so that the function -fits nicely on the @value{PAGE}. - @cindex @code{BEGIN} pattern, running @command{awk} programs and @cindex @code{FS} variable, running @command{awk} programs and Next comes a @code{BEGIN} rule that parses the command-line options. @@ -22083,8 +22407,7 @@ string: @example @c file eg/prog/cut.awk -BEGIN \ -@{ +BEGIN @{ FS = "\t" # default OFS = FS while ((c = getopt(ARGC, ARGV, "sf:c:d:")) != -1) @{ @@ -22364,7 +22687,7 @@ and the file transition library program The program begins with a descriptive comment and then a @code{BEGIN} rule that processes the command-line arguments with @code{getopt()}. The @option{-i} (ignore case) option is particularly easy with @command{gawk}; we just use the -@code{IGNORECASE} built-in variable +@code{IGNORECASE} predefined variable (@pxref{Built-in Variables}): @cindex @code{egrep.awk} program @@ -22559,8 +22882,7 @@ there are no matches, the exit status is one; otherwise it is zero: @example @c file eg/prog/egrep.awk -END \ -@{ +END @{ exit (total == 0) @} @c endfile @@ -22571,30 +22893,15 @@ and then exits: @example @c file eg/prog/egrep.awk -function usage( e) +function usage() @{ - e = "Usage: egrep [-csvil] [-e pat] [files ...]" - e = e "\n\tegrep [-csvil] pat [files ...]" - print e > "/dev/stderr" + print("Usage: egrep [-csvil] [-e pat] [files ...]") > "/dev/stderr" + print("\n\tegrep [-csvil] pat [files ...]") > "/dev/stderr" exit 1 @} @c endfile @end example -The variable @code{e} is used so that the function fits nicely -on the printed page. - -@cindex @code{END} pattern, backslash continuation and -@cindex @code{\} (backslash), continuing lines and -@cindex backslash (@code{\}), continuing lines and -Just a note on programming style: you may have noticed that the @code{END} -rule uses backslash continuation, with the open brace on a line by -itself. This is so that it more closely resembles the way functions -are written. Many of the examples -in this @value{CHAPTER} -use this style. You can decide for yourself if you like writing -your @code{BEGIN} and @code{END} rules this way -or not. @c ENDOFRANGE regexps @c ENDOFRANGE sfregexp @c ENDOFRANGE fsregexp @@ -22652,6 +22959,7 @@ numbers: # May 1993 # Revised February 1996 # Revised May 2014 +# Revised September 2014 @c endfile @end ignore @@ -22661,8 +22969,7 @@ numbers: # egid=5(blat) groups=9(nine),2(two),1(one) @group -BEGIN \ -@{ +BEGIN @{ uid = PROCINFO["uid"] euid = PROCINFO["euid"] gid = PROCINFO["gid"] @@ -22671,26 +22978,22 @@ BEGIN \ printf("uid=%d", uid) pw = getpwuid(uid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (euid != uid) @{ printf(" euid=%d", euid) pw = getpwuid(euid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) @} printf(" gid=%d", gid) pw = getgrgid(gid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (egid != gid) @{ printf(" egid=%d", egid) pw = getgrgid(egid) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) @} for (i = 1; ("group" i) in PROCINFO; i++) @{ @@ -22699,8 +23002,7 @@ BEGIN \ group = PROCINFO["group" i] printf("%d", group) pw = getgrgid(group) - if (pw != "") - pr_first_field(pw) + pr_first_field(pw) if (("group" (i+1)) in PROCINFO) printf(",") @} @@ -22710,8 +23012,10 @@ BEGIN \ function pr_first_field(str, a) @{ - split(str, a, ":") - printf("(%s)", a[1]) + if (str != "") @{ + split(str, a, ":") + printf("(%s)", a[1]) + @} @} @c endfile @end example @@ -22734,7 +23038,8 @@ tested, and the loop body never executes. The @code{pr_first_field()} function simply isolates out some code that is used repeatedly, making the whole program -slightly shorter and cleaner. +shorter and cleaner. In particular, moving the check for +the empty string into this function saves several lines of code. @c ENDOFRANGE id @@ -22861,24 +23166,25 @@ The @code{usage()} function simply prints an error message and exits: @example @c file eg/prog/split.awk -function usage( e) +function usage() @{ - e = "usage: split [-num] [file] [outname]" - print e > "/dev/stderr" + print("usage: split [-num] [file] [outname]") > "/dev/stderr" exit 1 @} @c endfile @end example -@noindent -The variable @code{e} is used so that the function -fits nicely on the @value{PAGE}. - This program is a bit sloppy; it relies on @command{awk} to automatically close the last file instead of doing it in an @code{END} rule. It also assumes that letters are contiguous in the character set, which isn't true for EBCDIC systems. +@ifset FOR_PRINT +You might want to consider how to eliminate the use of +@code{ord()} and @code{chr()}; this can be done in such a +way as to solve the EBCDIC issue as well. +@end ifset + @c ENDOFRANGE filspl @c ENDOFRANGE split @@ -22932,8 +23238,7 @@ Finally, @command{awk} is forced to read the standard input by setting @c endfile @end ignore @c file eg/prog/tee.awk -BEGIN \ -@{ +BEGIN @{ for (i = 1; i < ARGC; i++) copy[i] = ARGV[i] @@ -22995,8 +23300,7 @@ Finally, the @code{END} rule cleans up by closing all the output files: @example @c file eg/prog/tee.awk -END \ -@{ +END @{ for (i in copy) close(copy[i]) @} @@ -23028,10 +23332,10 @@ The options for @command{uniq} are: @table @code @item -d -Print only repeated lines. +Print only repeated (duplicated) lines. @item -u -Print only nonrepeated lines. +Print only nonrepeated (unique) lines. @item -c Count lines. This option overrides @option{-d} and @option{-u}. Both repeated @@ -23100,10 +23404,9 @@ standard output, @file{/dev/stdout}: @end ignore @c file eg/prog/uniq.awk -function usage( e) +function usage() @{ - e = "Usage: uniq [-udc [-n]] [+n] [ in [ out ]]" - print e > "/dev/stderr" + print("Usage: uniq [-udc [-n]] [+n] [ in [ out ]]") > "/dev/stderr" exit 1 @} @@ -23113,8 +23416,7 @@ function usage( e) # -n skip n fields # +n skip n characters, skip fields first -BEGIN \ -@{ +BEGIN @{ count = 1 outputfile = "/dev/stdout" opts = "udc0:1:2:3:4:5:6:7:8:9:" @@ -23126,7 +23428,7 @@ BEGIN \ else if (c == "c") do_count++ else if (index("0123456789", c) != 0) @{ - # getopt requires args to options + # getopt() requires args to options # this messes us up for things like -5 if (Optarg ~ /^[[:digit:]]+$/) fcount = (c Optarg) + 0 @@ -23158,22 +23460,20 @@ BEGIN \ @end example The following function, @code{are_equal()}, compares the current line, -@code{$0}, to the -previous line, @code{last}. It handles skipping fields and characters. -If no field count and no character count are specified, @code{are_equal()} -simply returns one or zero depending upon the result of a simple string -comparison of @code{last} and @code{$0}. Otherwise, things get more -complicated. -If fields have to be skipped, each line is broken into an array using -@code{split()} -(@pxref{String Functions}); -the desired fields are then joined back into a line using @code{join()}. -The joined lines are stored in @code{clast} and @code{cline}. -If no fields are skipped, @code{clast} and @code{cline} are set to -@code{last} and @code{$0}, respectively. -Finally, if characters are skipped, @code{substr()} is used to strip off the -leading @code{charcount} characters in @code{clast} and @code{cline}. The -two strings are then compared and @code{are_equal()} returns the result: +@code{$0}, to the previous line, @code{last}. It handles skipping fields +and characters. If no field count and no character count are specified, +@code{are_equal()} returns one or zero depending upon the result of a +simple string comparison of @code{last} and @code{$0}. + +Otherwise, things get more complicated. If fields have to be skipped, +each line is broken into an array using @code{split()} (@pxref{String +Functions}); the desired fields are then joined back into a line +using @code{join()}. The joined lines are stored in @code{clast} and +@code{cline}. If no fields are skipped, @code{clast} and @code{cline} +are set to @code{last} and @code{$0}, respectively. Finally, if +characters are skipped, @code{substr()} is used to strip off the leading +@code{charcount} characters in @code{clast} and @code{cline}. The two +strings are then compared and @code{are_equal()} returns the result: @example @c file eg/prog/uniq.awk @@ -23263,6 +23563,29 @@ END @{ @} @c endfile @end example + +@c FIXME: Include this? +@ignore +This program does not follow our recommended convention of naming +global variables with a leading capital letter. Doing that would +make the program a little easier to follow. +@end ignore + +@ifset FOR_PRINT +The logic for choosing which lines to print represents a @dfn{state +machine}, which is ``a device that can be in one of a set number of stable +conditions depending on its previous condition and on the present values +of its inputs.''@footnote{This is the definition returned from entering +@code{define: state machine} into Google.} +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 +suggestion. +@end ifset + + @c ENDOFRANGE prunt @c ENDOFRANGE tpul @c ENDOFRANGE uniq @@ -23293,7 +23616,7 @@ one or more input files. Its usage is as follows: If no files are specified on the command line, @command{wc} reads its standard input. If there are multiple files, it also prints total counts for all -the files. The options and their meanings are shown in the following list: +the files. The options and their meanings are as follows: @table @code @item -l @@ -23633,8 +23956,7 @@ Here is the program: @c file eg/prog/alarm.awk # usage: alarm time [ "message" [ count [ delay ] ] ] -BEGIN \ -@{ +BEGIN @{ # Initial argument sanity checking usage1 = "usage: alarm time ['message' [count [delay]]]" usage2 = sprintf("\t(%s) time ::= hh:mm", ARGV[1]) @@ -23775,8 +24097,8 @@ character of the ``to'' list is used for the remaining characters in the Once upon a time, @c early or mid-1989! -a user proposed that a transliteration function should -be added to @command{gawk}. +a user proposed adding a transliteration function +to @command{gawk}. @c Wishing to avoid gratuitous new features, @c at least theoretically The following program was written to @@ -23784,15 +24106,12 @@ prove that character transliteration could be done with a user-level function. This program is not as complete as the system @command{tr} utility but it does most of the job. -The @command{translate} program demonstrates one of the few weaknesses -of standard @command{awk}: dealing with individual characters is very -painful, requiring repeated use of the @code{substr()}, @code{index()}, -and @code{gsub()} built-in functions -(@pxref{String Functions}).@footnote{This -program was written before @command{gawk} acquired the ability to -split each character in a string into separate array elements.} -There are two functions. The first, @code{stranslate()}, takes three -arguments: +The @command{translate} program was written long before @command{gawk} +acquired the ability to split each character in a string into separate +array elements. Thus, it makes repeated use of the @code{substr()}, +@code{index()}, and @code{gsub()} built-in functions (@pxref{String +Functions}). There are two functions. The first, @code{stranslate()}, +takes three arguments: @table @code @item from @@ -23811,7 +24130,7 @@ loop goes through @code{from}, one character at a time. For each character in @code{from}, if the character appears in @code{target}, it is replaced with the corresponding @code{to} character. -The @code{translate()} function simply calls @code{stranslate()} using @code{$0} +The @code{translate()} function calls @code{stranslate()} using @code{$0} as the target. The main program sets two global variables, @code{FROM} and @code{TO}, from the command line, and then changes @code{ARGV} so that @command{awk} reads from the standard input. @@ -23897,6 +24216,12 @@ An obvious improvement to this program would be to set up the @code{t_ar} array only once, in a @code{BEGIN} rule. However, this assumes that the ``from'' and ``to'' lists will never change throughout the lifetime of the program. + +Another obvious improvement is to enable the use of ranges, +such as @samp{a-z}, as allowed by the @command{tr} utility. +Look at the code for @file{cut.awk} (@pxref{Cut Program}) +for inspiration. + @c ENDOFRANGE chtra @c ENDOFRANGE tr @@ -23940,7 +24265,7 @@ of lines on the page Most of the work is done in the @code{printpage()} function. The label lines are stored sequentially in the @code{line} array. But they have to print horizontally; @code{line[1]} next to @code{line[6]}, -@code{line[2]} next to @code{line[7]}, and so on. Two loops are used to +@code{line[2]} next to @code{line[7]}, and so on. Two loops accomplish this. The outer loop, controlled by @code{i}, steps through every 10 lines of data; this is each row of labels. The inner loop, controlled by @code{j}, goes through the lines within the row. @@ -24029,8 +24354,7 @@ function printpage( i, j) Count++ @} -END \ -@{ +END @{ printpage() @} @c endfile @@ -24055,7 +24379,7 @@ in a useful format. At first glance, a program like this would seem to do the job: @example -# Print list of word frequencies +# wordfreq-first-try.awk --- print list of word frequencies @{ for (i = 1; i <= NF; i++) @@ -24272,16 +24596,16 @@ Texinfo input file into separate files. This @value{DOCUMENT} is written in @uref{http://www.gnu.org/software/texinfo/, Texinfo}, the GNU project's document formatting language. A single Texinfo source file can be used to produce both -printed and online documentation. +printed documentation, with @TeX{}, and online documentation. @ifnotinfo -Texinfo is fully documented in the book +(Texinfo is fully documented in the book @cite{Texinfo---The GNU Documentation Format}, available from the Free Software Foundation, -and also available @uref{http://www.gnu.org/software/texinfo/manual/texinfo/, online}. +and also available @uref{http://www.gnu.org/software/texinfo/manual/texinfo/, online}.) @end ifnotinfo @ifinfo -The Texinfo language is described fully, starting with -@inforef{Top, , Texinfo, texinfo,Texinfo---The GNU Documentation Format}. +(The Texinfo language is described fully, starting with +@inforef{Top, , Texinfo, texinfo,Texinfo---The GNU Documentation Format}.) @end ifinfo For our purposes, it is enough to know three things about Texinfo input @@ -24359,8 +24683,7 @@ exits with a zero exit status, signifying OK: @cindex @code{extract.awk} program @example @c file eg/prog/extract.awk -# extract.awk --- extract files and run programs -# from texinfo files +# extract.awk --- extract files and run programs from texinfo files @c endfile @ignore @c file eg/prog/extract.awk @@ -24374,8 +24697,7 @@ exits with a zero exit status, signifying OK: BEGIN @{ IGNORECASE = 1 @} -/^@@c(omment)?[ \t]+system/ \ -@{ +/^@@c(omment)?[ \t]+system/ @{ if (NF < 3) @{ e = ("extract: " FILENAME ":" FNR) e = (e ": badly formed `system' line") @@ -24432,8 +24754,7 @@ line. That line is then printed to the output file: @example @c file eg/prog/extract.awk -/^@@c(omment)?[ \t]+file/ \ -@{ +/^@@c(omment)?[ \t]+file/ @{ if (NF != 3) @{ e = ("extract: " FILENAME ":" FNR ": badly formed `file' line") print e > "/dev/stderr" @@ -24493,7 +24814,7 @@ The @code{END} rule handles the final cleanup, closing the open file: function unexpected_eof() @{ printf("extract: %s:%d: unexpected EOF or error\n", - FILENAME, FNR) > "/dev/stderr" + FILENAME, FNR) > "/dev/stderr" exit 1 @} @end group @@ -24521,7 +24842,7 @@ While @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 -command1 < orig.data | sed 's/old/new/g' | command2 > result +@var{command1} < orig.data | sed 's/old/new/g' | @var{command2} > result @end example Here, @samp{s/old/new/g} tells @command{sed} to look for the regexp @@ -24753,6 +25074,7 @@ should be the @command{awk} program. If there are no command-line arguments left, @command{igawk} prints an error message and exits. Otherwise, the first argument is appended to @code{program}. In any case, after the arguments have been processed, +the shell variable @code{program} contains the complete text of the original @command{awk} program. @@ -24875,8 +25197,8 @@ the path, and an attempt is made to open the generated @value{FN}. The only way to test if a file can be read in @command{awk} is to go ahead and try to read it with @code{getline}; this is what @code{pathto()} does.@footnote{On some very old versions of @command{awk}, the test -@samp{getline junk < t} can loop forever if the file exists but is empty. -Caveat emptor.} If the file can be read, it is closed and the @value{FN} +@samp{getline junk < t} can loop forever if the file exists but is empty.} +If the file can be read, it is closed and the @value{FN} is returned: @ignore @@ -25076,12 +25398,10 @@ in C or C++, and it is frequently easier to do certain kinds of string and argument manipulation using the shell than it is in @command{awk}. Finally, @command{igawk} shows that it is not always necessary to add new -features to a program; they can often be layered on top. -@ignore -With @command{igawk}, -there is no real reason to build @code{@@include} processing into -@command{gawk} itself. -@end ignore +features to a program; they can often be layered on top.@footnote{@command{gawk} +does @code{@@include} processing itself in order to support the use +of @command{awk} programs as Web CGI scripts.} + @c ENDOFRANGE libfex @c ENDOFRANGE flibex @c ENDOFRANGE awkpex @@ -25099,12 +25419,11 @@ One word is an anagram of another if both words contain the same letters (for example, ``babbling'' and ``blabbing''). -An elegant algorithm is presented in Column 2, Problem C of -Jon Bentley's @cite{Programming Pearls}, second edition. -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. +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 @@ -25338,7 +25657,7 @@ BEGIN { @itemize @value{BULLET} @item -The functions provided in this @value{CHAPTER} and the previous one +The programs provided in this @value{CHAPTER} continue on the theme that reading programs is an excellent way to learn Good Programming. @@ -25369,13 +25688,14 @@ mailing labels, and finding anagrams. @end itemize +@c EXCLUDE START @node Programs Exercises @section Exercises @enumerate @item Rewrite @file{cut.awk} (@pxref{Cut Program}) -using @code{split()} with @code{""} as the seperator. +using @code{split()} with @code{""} as the separator. @item In @ref{Egrep Program}, we mentioned that @samp{egrep -i} could be @@ -25392,17 +25712,27 @@ information is printed. Modify the @command{awk} version same way. @item -The @code{split.awk} program (@pxref{Split Program}) uses -the @code{chr()} and @code{ord()} functions to move through the -letters of the alphabet. -Modify the program to instead use only the @command{awk} -built-in functions, such as @code{index()} and @code{substr()}. - -@item The @code{split.awk} program (@pxref{Split Program}) assumes that letters are contiguous in the character set, which isn't true for EBCDIC systems. Fix this problem. +(Hint: Consider a different way to work through the alphabet, +without relying on @code{ord()} and @code{chr()}.) + +@item +In @file{uniq.awk} (@pxref{Uniq Program}, the +logic for choosing which lines to print represents a @dfn{state +machine}, which is ``a device that can be in one of a set number of stable +conditions depending on its previous condition and on the present values +of its inputs.''@footnote{This is the definition returned from entering +@code{define: state machine} into Google.} +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 +suggestion. + @item Why can't the @file{wc.awk} program (@pxref{Wc Program}) just @@ -25498,6 +25828,7 @@ Modify @file{anagram.awk} (@pxref{Anagram Program}), to avoid the use of the external @command{sort} utility. @end enumerate +@c EXCLUDE END @ifnotinfo @part @value{PART3}Moving Beyond Standard @command{awk} With @command{gawk} @@ -25603,13 +25934,11 @@ discusses the ability to dynamically add new built-in functions to @cindex constants, nondecimal If you run @command{gawk} with the @option{--non-decimal-data} option, -you can have nondecimal constants in your input data: +you can have nondecimal values in your input data: -@c line break here for small book format @example $ @kbd{echo 0123 123 0x123 |} -> @kbd{gawk --non-decimal-data '@{ printf "%d, %d, %d\n",} -> @kbd{$1, $2, $3 @}'} +> @kbd{gawk --non-decimal-data '@{ printf "%d, %d, %d\n", $1, $2, $3 @}'} @print{} 83, 123, 291 @end example @@ -25650,6 +25979,8 @@ Instead, use the @code{strtonum()} function to convert your data (@pxref{String Functions}). This makes your programs easier to write and easier to read, and leads to less surprising results. + +This option may disappear in a future version of @command{gawk}. @end quotation @node Array Sorting @@ -25679,12 +26010,14 @@ Often, though, it is desirable to be able to loop over the elements in a particular order that you, the programmer, choose. @command{gawk} lets you do this. -@ref{Controlling Scanning}, describes how you can assign special, +@DBREF{Controlling Scanning} describes how you can assign special, pre-defined values to @code{PROCINFO["sorted_in"]} in order to control the order in which @command{gawk} traverses an array during a @code{for} loop. -In addition, the value of @code{PROCINFO["sorted_in"]} can be a function name. +In addition, the value of @code{PROCINFO["sorted_in"]} can be a +function name.@footnote{This is why the predefined sorting orders +start with an @samp{@@} character, which cannot be part of an identifier.} This lets you traverse an array based on any custom criterion. The array elements are ordered according to the return value of this function. The comparison function should be defined with at least @@ -25816,7 +26149,7 @@ according to login name. The following program sorts records by a specific field position and can be used for this purpose: @example -# sort.awk --- simple program to sort by field position +# passwd-sort.awk --- simple program to sort by field position # field position is specified by the global variable POS function cmp_field(i1, v1, i2, v2) @@ -25875,7 +26208,7 @@ As mentioned above, 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 -may change during the next loop traversal, if other elements are added or +may change the next time the array is traversed, if other elements are added or removed from the array. One way to resolve ties when comparing elements with otherwise equal values is to include the indices in the comparison rules. Note that doing this may make the loop traversal less efficient, @@ -26044,7 +26377,6 @@ 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 @command{gawk} extensions, they are not available in that case.} -Caveat Emptor. @node Two-way I/O @section Two-Way Communications with Another Process @@ -26110,7 +26442,7 @@ for example, @file{/tmp} will not do, as another user might happen to be using a temporary file with the same name.@footnote{Michael Brennan suggests the use of @command{rand()} to generate unique @value{FN}s. This is a valid point; nevertheless, temporary files -remain more difficult than two-way pipes.} @c 8/2014 +remain more difficult to use than two-way pipes.} @c 8/2014 @cindex coprocesses @cindex input/output, two-way @@ -26247,13 +26579,27 @@ using regular pipes. @cindex @code{/inet6/@dots{}} special files (@command{gawk}) @cindex files, @code{/inet6/@dots{}} (@command{gawk}) @cindex @code{EMISTERED} +@ifnotdocbook @quotation -@code{EMISTERED}:@* +@code{EMRED}:@* @ @ @ @ @i{A host is a host from coast to coast,@* -@ @ @ @ and no-one can talk to host that's close,@* +@ @ @ @ and nobody talks to a host that's close,@* @ @ @ @ unless the host that isn't close@* -@ @ @ @ is busy hung or dead.} +@ @ @ @ is busy, hung, or dead.} +@author Mike O'Brien (aka Mr.@: Protocol) @end quotation +@end ifnotdocbook + +@docbook +<blockquote> +<attribution>Mike O'Brien (aka Mr. Protocol)</attribution> +<literallayout class="normal"><literal>EMISTERED</literal>: + <emphasis>A host is a host from coast to coast,</emphasis> + <emphasis>and no-one can talk to host that's close,</emphasis> + <emphasis>unless the host that isn't close</emphasis> + <emphasis>is busy, hung, or dead.</emphasis></literallayout> +</blockquote> +@end docbook In addition to being able to open a two-way pipeline to a coprocess on the same system @@ -26282,7 +26628,7 @@ the system default, most likely IPv4. @item protocol The protocol to use over IP. This must be either @samp{tcp}, or @samp{udp}, for a TCP or UDP IP connection, -respectively. The use of TCP is recommended for most applications. +respectively. TCP should be used for most applications. @item local-port @cindex @code{getaddrinfo()} function (C library) @@ -26315,10 +26661,10 @@ Consider the following very simple example: @example BEGIN @{ - Service = "/inet/tcp/0/localhost/daytime" - Service |& getline - print $0 - close(Service) + Service = "/inet/tcp/0/localhost/daytime" + Service |& getline + print $0 + close(Service) @} @end example @@ -26421,9 +26767,9 @@ in the morning to work.) @cindex @code{BEGIN} pattern, and profiling @cindex @code{END} pattern, and profiling @example - # gawk profile, created Thu Feb 27 05:16:21 2014 + # gawk profile, created Mon Sep 29 05:16:21 2014 - # BEGIN block(s) + # BEGIN rule(s) BEGIN @{ 1 print "First BEGIN rule" @@ -26450,7 +26796,7 @@ in the morning to work.) @} @} - # END block(s) + # END rule(s) END @{ 1 print "First END rule" @@ -26560,8 +26906,7 @@ The profiled version of your program may not look exactly like what you typed when you wrote it. This is because @command{gawk} creates the profiled version by ``pretty printing'' its internal representation of the program. The advantage to this is that @command{gawk} can produce -a standard representation. The disadvantage is that all source-code -comments are lost. +a standard representation. Also, things such as: @example @@ -26578,7 +26923,7 @@ come out as: @end example @noindent -which is correct, but possibly surprising. +which is correct, but possibly unexpected. @cindex profiling @command{awk} programs, dynamically @cindex @command{gawk} program, dynamic profiling @@ -26610,7 +26955,7 @@ $ @kbd{kill -USR1 13992} @noindent As usual, the profiled version of the program is written to -@file{awkprof.out}, or to a different file if one specified with +@file{awkprof.out}, or to a different file if one was specified with the @option{--profile} option. Along with the regular profile, as shown earlier, the profile file @@ -26658,6 +27003,23 @@ When called this way, @command{gawk} ``pretty prints'' the program into Once upon a time, the @option{--pretty-print} option would also run your program. This is is no longer the case. @end quotation + +There is a significant difference between the output created when +profiling, and that created when pretty-printing. Pretty-printed output +preserves the original comments that were in the program, although their +placement may not correspond exactly to their original locations in the +source code. + +However, as a deliberate design decision, profiling output @emph{omits} +the original program's comments. This allows you to focus on the +execution count data and helps you avoid the temptation to use the +profiler for pretty-printing. + +Additionally, pretty-printed output does not have the leading indentation +that the profiling output does. This makes it easy to pretty-print your +code once development is completed, and then use the result as the final +version of your program. + @c ENDOFRANGE awkp @c ENDOFRANGE proawk @@ -26670,6 +27032,7 @@ The @option{--non-decimal-data} option causes @command{gawk} to treat octal- and hexadecimal-looking input data as octal and hexadecimal. This option should be used with caution or not at all; use of @code{strtonum()} is preferable. +Note that this option may disappear in a future version of @command{gawk}. @item You can take over complete control of sorting in @samp{for (@var{indx} in @var{array})} @@ -26683,15 +27046,15 @@ those functions sort arrays. Or you may provide one of the predefined control strings that work for @code{PROCINFO["sorted_in"]}. @item -You can use the @samp{|&} operator to create a two-way pipe to a co-process. -You read from the co-process with @code{getline} and write to it with @code{print} -or @code{printf}. Use @code{close()} to close off the co-process completely, or +You can use the @samp{|&} operator to create a two-way pipe to a coprocess. +You read from the coprocess with @code{getline} and write to it with @code{print} +or @code{printf}. Use @code{close()} to close off the coprocess completely, or optionally, close off one side of the two-way communications. @item -By using special ``@value{FN}s'' with the @samp{|&} operator, you can open a +By using special @value{FN}s with the @samp{|&} operator, you can open a TCP/IP (or UDP/IP) connection to remote hosts in the Internet. @command{gawk} -supports both IPv4 an IPv6. +supports both IPv4 and IPv6. @item You can generate statement count profiles of your program. This can help you @@ -26929,7 +27292,7 @@ In June 2001 Bruno Haible wrote: This information is accessed via the POSIX character classes in regular expressions, such as @code{/[[:alnum:]]/} -(@pxref{Regexp Operators}). +(@pxref{Bracket Expressions}). @cindex monetary information, localization @cindex currency symbols, localization @@ -27012,7 +27375,7 @@ default arguments. Return the plural form used for @var{number} of the translation of @var{string1} and @var{string2} in text domain @var{domain} for locale category @var{category}. @var{string1} is the -English singular variant of a message, and @var{string2} the English plural +English singular variant of a message, and @var{string2} is the English plural variant of the same message. The default value for @var{domain} is the current value of @code{TEXTDOMAIN}. The default value for @var{category} is @code{"LC_MESSAGES"}. @@ -27100,9 +27463,11 @@ This example would be better done with @code{dcngettext()}: @example if (groggy) - message = dcngettext("%d customer disturbing me\n", "%d customers disturbing me\n", "adminprog") + message = dcngettext("%d customer disturbing me\n", + "%d customers disturbing me\n", "adminprog") else - message = dcngettext("enjoying %d customer\n", "enjoying %d customers\n", "adminprog") + message = dcngettext("enjoying %d customer\n", + "enjoying %d customers\n", "adminprog") printf(message, ncustomers) @end example @@ -27174,7 +27539,7 @@ First, use the @option{--gen-pot} command-line option to create the initial @file{.pot} file: @example -$ @kbd{gawk --gen-pot -f guide.awk > guide.pot} +gawk --gen-pot -f guide.awk > guide.pot @end example @cindex @code{xgettext} utility @@ -27238,11 +27603,11 @@ example, @samp{string} is the first argument and @samp{length(string)} is the se @example $ @kbd{gawk 'BEGIN @{} -> @kbd{string = "Dont Panic"} +> @kbd{string = "Don\47t Panic"} > @kbd{printf "%2$d characters live in \"%1$s\"\n",} > @kbd{string, length(string)} > @kbd{@}'} -@print{} 10 characters live in "Dont Panic" +@print{} 11 characters live in "Don't Panic" @end example If present, positional specifiers come first in the format specification, @@ -27454,7 +27819,8 @@ msgstr "Like, the scoop is" @cindex GNU/Linux 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. +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. 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: @@ -27475,8 +27841,8 @@ $ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES} The @command{msgfmt} utility does the conversion from human-readable @file{.po} file to machine-readable @file{.mo} file. By default, @command{msgfmt} creates a file named @file{messages}. -This file must be renamed and placed in the proper directory so that -@command{gawk} can find it: +This file must be renamed and placed in the proper directory (using +the @option{-o} option) so that @command{gawk} can find it: @example $ @kbd{msgfmt guide-mellow.po -o en_US.UTF-8/LC_MESSAGES/guide.mo} @@ -27519,8 +27885,8 @@ complete detail in @cite{GNU gettext tools}}.) @end ifnotinfo As of this writing, the latest version of GNU @command{gettext} is -@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.1.tar.gz, -@value{PVERSION} 0.19.1}. +@uref{ftp://ftp.gnu.org/gnu/gettext/gettext-0.19.2.tar.gz, +@value{PVERSION} 0.19.2}. If a translation of @command{gawk}'s messages exists, then @command{gawk} produces usage messages, warnings, @@ -27608,7 +27974,7 @@ the discussion of debugging in @command{gawk}. @subsection Debugging in General (If you have used debuggers in other languages, you may want to skip -ahead to the next section on the specific features of the @command{awk} +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 @@ -27648,7 +28014,7 @@ is going wrong (or, for that matter, to better comprehend a perfectly functional program that you or someone else wrote). @node Debugging Terms -@subsection Additional Debugging Concepts +@subsection Debugging Concepts Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. @@ -27737,8 +28103,8 @@ as our example. @cindex starting the debugger @cindex debugger, how to start -Starting the debugger is almost exactly like running @command{gawk}, -except you have to pass an additional option @option{--debug} or the +Starting the debugger is almost exactly like running @command{gawk} normally, +except you have to pass an additional option @option{--debug}, or the corresponding short option @option{-D}. The file(s) containing the program and any supporting code are given on the command line as arguments to one or more @option{-f} options. (@command{gawk} is not designed @@ -27746,7 +28112,7 @@ to debug command-line programs, only programs contained in files.) In our case, we invoke the debugger like this: @example -$ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk inputfile} +$ @kbd{gawk -D -f getopt.awk -f join.awk -f uniq.awk -1 inputfile} @end example @noindent @@ -27756,6 +28122,7 @@ this syntax is slightly different from what they are used to. With the @command{gawk} debugger, you give the arguments for running the program in the command line to the debugger rather than as part of the @code{run} command at the debugger prompt.) +The @option{-1} is an option to @file{uniq.awk}. Instead of immediately running the program on @file{inputfile}, as @command{gawk} would ordinarily do, the debugger merely loads all @@ -27808,7 +28175,7 @@ the breakpoint, use the @code{b} (breakpoint) command: @example gawk> @kbd{b are_equal} -@print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 64 +@print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 63 @end example The debugger tells us the file and line number where the breakpoint is. @@ -27820,8 +28187,8 @@ gawk> @kbd{r} @print{} Starting program: @print{} Stopping in Rule ... @print{} Breakpoint 1, are_equal(n, m, clast, cline, alast, aline) - at `awklib/eg/prog/uniq.awk':64 -@print{} 64 if (fcount == 0 && charcount == 0) + at `awklib/eg/prog/uniq.awk':63 +@print{} 63 if (fcount == 0 && charcount == 0) gawk> @end example @@ -27833,12 +28200,12 @@ listing of the current stack frames: @example gawk> @kbd{bt} @print{} #0 are_equal(n, m, clast, cline, alast, aline) - at `awklib/eg/prog/uniq.awk':69 -@print{} #1 in main() at `awklib/eg/prog/uniq.awk':89 + at `awklib/eg/prog/uniq.awk':68 +@print{} #1 in main() at `awklib/eg/prog/uniq.awk':88 @end example This tells us that @code{are_equal()} was called by the main program at -line 89 of @file{uniq.awk}. (This is not a big surprise, since this +line 88 of @file{uniq.awk}. (This is not a big surprise, since 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.) @@ -27862,7 +28229,7 @@ A more useful variable to display might be the current record: @example gawk> @kbd{p $0} -@print{} $0 = string ("gawk is a wonderful program!") +@print{} $0 = "gawk is a wonderful program!" @end example @noindent @@ -27871,7 +28238,7 @@ our test input above. Let's look at @code{NR}: @example gawk> @kbd{p NR} -@print{} NR = number (2) +@print{} NR = 2 @end example @noindent @@ -27890,7 +28257,7 @@ OK, let's just check that that rule worked correctly: @example gawk> @kbd{p last} -@print{} last = string ("awk is a wonderful program!") +@print{} last = "awk is a wonderful program!" @end example Everything we have done so far has verified that the program has worked as @@ -27901,13 +28268,13 @@ be inside this function. To investigate further, we must begin @example gawk> @kbd{n} -@print{} 67 if (fcount > 0) @{ +@print{} 66 if (fcount > 0) @{ @end example -This tells us that @command{gawk} is now ready to execute line 67, which +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{-f} command-line option. (Notice that we skipped -from where we were before at line 64 to here, since the condition in line 64 +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 @samp{if (fcount == 0 && charcount == 0)} was false.) Continuing to step, we now get to the splitting of the current and @@ -27915,9 +28282,9 @@ last records: @example gawk> @kbd{n} -@print{} 68 n = split(last, alast) +@print{} 67 n = split(last, alast) gawk> @kbd{n} -@print{} 69 m = split($0, aline) +@print{} 68 m = split($0, aline) @end example At this point, we should be curious to see what our records were split @@ -27925,10 +28292,10 @@ into, so we try to look: @example gawk> @kbd{p n m alast aline} -@print{} n = number (5) -@print{} m = number (5) +@print{} n = 5 +@print{} m = untyped variable @print{} alast = array, 5 elements -@print{} aline = array, 5 elements +@print{} aline = untyped variable @end example @noindent @@ -27936,7 +28303,9 @@ gawk> @kbd{p n m alast aline} @command{awk}'s @code{print} statement.) This is kind of disappointing, though. All we found out is that there -are five elements in each of our arrays. Useful enough (we now know that +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. +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? @@ -27952,7 +28321,7 @@ Oops! @example gawk> @kbd{p alast[1]} -@print{} alast["1"] = string ("awk") +@print{} alast["1"] = "awk" @end example This would be kind of slow for a 100-member array, though, so @@ -27961,11 +28330,11 @@ not to be mentioned): @example gawk> @kbd{p @@alast} -@print{} alast["1"] = string ("awk") -@print{} alast["2"] = string ("is") -@print{} alast["3"] = string ("a") -@print{} alast["4"] = string ("wonderful") -@print{} alast["5"] = string ("program!") +@print{} alast["1"] = "awk" +@print{} alast["2"] = "is" +@print{} alast["3"] = "a" +@print{} alast["4"] = "wonderful" +@print{} alast["5"] = "program!" @end example It looks like we got this far OK. Let's take another step @@ -27973,9 +28342,9 @@ or two: @example gawk> @kbd{n} -@print{} 70 clast = join(alast, fcount, n) +@print{} 69 clast = join(alast, fcount, n) gawk> @kbd{n} -@print{} 71 cline = join(aline, fcount, m) +@print{} 70 cline = join(aline, fcount, m) @end example Well, here we are at our error (sorry to spoil the suspense). What we @@ -27985,8 +28354,8 @@ this would work. Let's look at what we've got: @example gawk> @kbd{p cline clast} -@print{} cline = string ("gawk is a wonderful program!") -@print{} clast = string ("awk is a wonderful program!") +@print{} cline = "gawk is a wonderful program!" +@print{} clast = "awk is a wonderful program!" @end example Hey, those look pretty familiar! They're just our original, unaltered, @@ -28128,7 +28497,8 @@ Delete breakpoint(s) set at entry to function @var{function}. @cindex breakpoint condition @item @code{condition} @var{n} @code{"@var{expression}"} Add a condition to existing breakpoint or watchpoint @var{n}. The -condition is an @command{awk} expression that the debugger evaluates +condition is an @command{awk} expression @emph{enclosed in double quotes} +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 @@ -28316,7 +28686,7 @@ see the output shown under @code{dump} in @ref{Miscellaneous Debugger Commands}. @item @code{until} [[@var{filename}@code{:}]@var{n} | @var{function}] @itemx @code{u} [[@var{filename}@code{:}]@var{n} | @var{function}] Without any argument, continue execution until a line past the current -line in current stack frame is reached. With an argument, +line in the current stack frame is reached. With an argument, continue execution until the specified location is reached, or the current stack frame returns. @end table @@ -28380,7 +28750,7 @@ gawk> @kbd{print $3} @noindent This prints the third field in the input record (if the specified field does not exist, it prints @samp{Null field}). A variable can be an array element, with -the subscripts being constant values. To print the contents of an array, +the subscripts being constant string values. To print the contents of an array, prefix the name of the array with the @samp{@@} symbol: @example @@ -28446,7 +28816,7 @@ watch list. @end table @node Execution Stack -@subsection Dealing with the Stack +@subsection Working with the Stack Whenever you run a program which contains any function calls, @command{gawk} maintains a stack of all of the function calls leading up @@ -28457,16 +28827,22 @@ functions which called the one you are in. The commands for doing this are: @table @asis @cindex debugger commands, @code{bt} (@code{backtrace}) @cindex debugger commands, @code{backtrace} +@cindex debugger commands, @code{where} (@code{backtrace}) @cindex @code{backtrace} debugger command @cindex @code{bt} debugger command (alias for @code{backtrace}) +@cindex @code{where} debugger command +@cindex @code{where} debugger command (alias for @code{backtrace}) @cindex call stack, display in debugger @cindex traceback, display in debugger @item @code{backtrace} [@var{count}] @itemx @code{bt} [@var{count}] +@itemx @code{where} [@var{count}] 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 +GDB users who may be used to that command. @cindex debugger commands, @code{down} @cindex @code{down} debugger command @@ -28516,7 +28892,7 @@ The value for @var{what} should be one of the following: @table @code @item args @cindex show function arguments, in debugger -Arguments of the selected frame. +List arguments of the selected frame. @item break @cindex show breakpoints @@ -28528,7 +28904,7 @@ List all items in the automatic display list. @item frame @cindex describe call stack frame, in debugger -Description of the selected stack frame. +Give a description of the selected stack frame. @item functions @cindex list function definitions, in debugger @@ -28537,11 +28913,11 @@ line numbers. @item locals @cindex show local variables, in debugger -Local variables of the selected frame. +List local variables of the selected frame. @item source @cindex show name of current source file, in debugger -The name of the current source file. Each time the program stops, the +Print the name of the current source file. Each time the program stops, the current source file is the file containing the current instruction. When the debugger first starts, the current source file is the first file included via the @option{-f} option. The @@ -28658,6 +29034,7 @@ commands in a program. This can be very enlightening, as the following partial dump of Davide Brini's obfuscated code (@pxref{Signature Program}) demonstrates: +@c FIXME: This will need updating if num-handler branch is ever merged in. @smallexample gawk> @kbd{dump} @print{} # BEGIN @@ -28731,7 +29108,7 @@ are as follows: @c nested table @table @asis -@item @code{-} +@item @code{-} (Minus) Print lines before the lines last printed. @item @code{+} @@ -28819,7 +29196,7 @@ and @end table @node Limitations -@section Limitations and Future Plans +@section Limitations We hope you find the @command{gawk} debugger useful and enjoyable to work with, but as with any program, especially in its early releases, it still has @@ -28833,7 +29210,9 @@ responds @samp{syntax error}. When you do figure out what your mistake was, though, you'll feel like a real guru. @item -If you perused the dump of opcodes in @ref{Miscellaneous Debugger Commands}, +@c NOTE: no comma after the ref{} on purpose, due to following +@c parenthetical remark. +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. @@ -28865,8 +29244,10 @@ executing, short programs. The @command{gawk} debugger only accepts source supplied with the @option{-f} option. @end itemize +@ignore Look forward to a future release when these and other missing features may be added, and of course feel free to try to add them yourself! +@end ignore @node Debugging Summary @section Summary @@ -28909,9 +29290,8 @@ and editing. @cindex floating-point, numbers@comma{} arbitrary precision This @value{CHAPTER} introduces some basic concepts relating to -how computers do arithmetic and briefly lists the features in -@command{gawk} for performing arbitrary precision floating point -computations. It then proceeds to describe floating-point arithmetic, +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 a feature available only in @command{gawk}. It continues on to present @@ -29006,10 +29386,12 @@ 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 the following table. +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} @multitable @columnfractions .34 .33 .33 -@headitem Numeric representation @tab Miniumum value @tab Maximum value +@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 @@ -29017,6 +29399,7 @@ signed. The possible ranges of values are shown in the following table. @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 @@ -29044,14 +29427,12 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.''@footnote{Thanks -to Michael Brennan for this description, which I have paraphrased, and -for the examples}. -A special value that results from attempting a -calculation that has no answer as a real number. In such a case, -programs can either receive a floating-point exception, or get @code{NaN} -back as the result. The IEEE 754 standard recommends that systems return -@code{NaN}. Some examples: +``Not A Number.''@footnote{Thanks to Michael Brennan for this description, +which we have paraphrased, and for the examples.} A special value that +results from attempting a calculation that has no answer as a real number. +In such a case, programs can either receive a floating-point exception, +or get @code{NaN} back as the result. The IEEE 754 standard recommends +that systems return @code{NaN}. Some examples: @table @code @item sqrt(-1) @@ -29125,9 +29506,9 @@ to allow greater precisions and larger exponent ranges. field values for the basic IEEE 754 binary formats: @float Table,table-ieee-formats -@caption{Basic IEEE Format Context Values} +@caption{Basic IEEE Format Values} @multitable @columnfractions .20 .20 .20 .20 .20 -@headitem Name @tab Total bits @tab Precision @tab emin @tab emax +@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 Double @tab 64 @tab 53 @tab @minus{}1022 @tab +1023 @item Quadruple @tab 128 @tab 113 @tab @minus{}16382 @tab +16383 @@ -29140,18 +29521,18 @@ one extra bit of significand. @end quotation @node MPFR features -@section Arbitrary Precison 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, @command{gawk} uses the @uref{http://www.mpfr.org, GNU -MPFR} and @uref{http://gmplib.org, GNU MP} (GMP) libraries for arbitrary +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} -@print{} GNU Awk 4.1.1, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) +@print{} GNU Awk 4.1.2, API: 1.1 (GNU MPFR 3.1.0-p3, GNU MP 5.0.2) @print{} Copyright (C) 1989, 1991-2014 Free Software Foundation. @dots{} @end example @@ -29171,17 +29552,18 @@ results. With the @option{-M} command-line option, all floating-point arithmetic operators and numeric functions can yield results to any desired precision level supported by MPFR. -Two built-in variables, @code{PREC} and @code{ROUNDMODE}, +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{Auto-set}, for more information. +@xref{Setting precision}, and @ref{Setting the rounding mode}, +for more information. @node FP Math Caution @section Floating Point Arithmetic: Caveat Emptor! @quotation -Math class is tough! +@i{Math class is tough!} @author Teen Talk Barbie, July 1992 @end quotation @@ -29289,6 +29671,10 @@ else # not ok @end example +@noindent +(We assume that you have a simple absolute value function named +@code{abs()} defined elsewhere in your program.) + @node Errors accumulate @subsubsection Errors Accumulate @@ -29375,7 +29761,7 @@ 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 -computations with a particular precision and effective rounding rule, +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. @@ -29442,7 +29828,7 @@ $ @kbd{gawk -f pi2.awk} the precision or accuracy of individual numbers. Performing an arithmetic operation or calling a built-in function rounds the result to the current working precision. The default working precision is 53 bits, which you can -modify using the built-in variable @code{PREC}. You can also set the +modify using the predefined variable @code{PREC}. You can also set the value to one of the predefined case-insensitive strings shown in @ref{table-predefined-precision-strings}, to emulate an IEEE 754 binary format. @@ -29474,7 +29860,7 @@ Be wary of floating-point constants! When reading a floating-point constant from program source code, @command{gawk} uses the default precision (that of a C @code{double}), unless overridden by an assignment to the special variable @code{PREC} on the command line, to store it -internally as a MPFR number. Changing the precision using @code{PREC} +internally as an MPFR number. Changing the precision using @code{PREC} in the program text does @emph{not} change the precision of a constant. If you need to represent a floating-point constant at a higher precision @@ -29612,15 +29998,15 @@ 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 @{} > @kbd{x = 5^4^3^2} -> @kbd{print "# of digits =", length(x)} +> @kbd{print "number of digits =", length(x)} > @kbd{print substr(x, 1, 20), "...", substr(x, length(x) - 19, 20)} > @kbd{@}'} -@print{} # of digits = 183231 +@print{} number of digits = 183231 @print{} 62060698786608744707 ... 92256259918212890625 @end example @@ -29722,7 +30108,7 @@ using this user-defined function: @end ignore @c file eg/lib/div.awk -function div(numerator, denominator, result, i) +function div(numerator, denominator, result) @{ split("", result) @@ -29736,6 +30122,80 @@ function div(numerator, denominator, result, i) @c endfile @end example +The following example program, contributed by Katie Wasserman, +uses @code{div()} to +compute the digits of @value{PI} to as many places as you +choose to set: + +@example +@c file eg/prog/pi.awk +# pi.awk --- compute the digits of pi +@c endfile +@c endfile +@ignore +@c file eg/prog/pi.awk +# +# Katie Wasserman, katie@@wass.net +# August 2014 +@c endfile +@end ignore +@c file eg/prog/pi.awk + +BEGIN @{ + digits = 100000 + two = 2 * 10 ^ digits + pi = two + for (m = digits * 4; m > 0; --m) @{ + d = m * 2 + 1 + x = pi * m + div(x, d, result) + pi = result["quotient"] + pi = pi + two + @} + print pi +@} +@c endfile +@end example + +@ignore +Date: Wed, 20 Aug 2014 10:19:11 -0400 +To: arnold@skeeve.com +From: Katherine Wasserman <katie@wass.net> +Subject: Re: computation of digits of pi? + +Arnold, + +>The program that you sent to compute the digits of pi using div(). Is +>that some standard algorithm that every math student knows? If so, +>what's it called? + +It's not that well known but it's not that obscure either + +It's Euler's modification to Newton's method for calculating pi. + +Take a look at lines (23) - (25) here: http://mathworld.wolfram.com/PiFormulas.htm + +The algorithm I wrote simply expands the multiply by 2 and works from the innermost expression outwards. I used this to program HP calculators because it's quite easy to modify for tiny memory devices with smallish word sizes. + +http://www.hpmuseum.org/cgi-sys/cgiwrap/hpmuseum/articles.cgi?read=899 + +-Katie +@end ignore + +When asked about the algorithm used, Katie replied: + +@quotation +It's not that well known but it's not that obscure either. +It's Euler's modification to Newton's method for calculating pi. +Take a look at lines (23) - (25) here: @uref{http://mathworld.wolfram.com/PiFormulas.htm}. + +The algorithm I wrote simply expands the multiply by 2 and works from +the innermost expression outwards. I used this to program HP calculators +because it's quite easy to modify for tiny memory devices with smallish +word sizes. See +@uref{http://www.hpmuseum.org/cgi-sys/cgiwrap/hpmuseum/articles.cgi?read=899}. +@end quotation + @node POSIX Floating Point Problems @section Standards Versus Existing Practice @@ -29843,7 +30303,7 @@ 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. The default for @command{awk} is to use double-precision +values. Standard @command{awk} uses double precision floating-point values. @item @@ -29962,7 +30422,7 @@ 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 sample extension. In addition, it documents +them, and presents a small example extension. In addition, it documents the sample extensions included in the @command{gawk} distribution, and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @@ -29978,10 +30438,14 @@ goals and design. @node Plugin License @section Extension Licensing -Every dynamic extension should define the global symbol -@code{plugin_is_GPL_compatible} to assert that it has been licensed under -a GPL-compatible license. If this symbol does not exist, @command{gawk} -emits a fatal error and exits when it tries to load your extension. +Every dynamic extension must be distributed under a license that is +compatible with the GNU GPL (@pxref{Copying}). + +In order for the extension to tell @command{gawk} that it is +properly licensed, the extension must define the global symbol +@code{plugin_is_GPL_compatible}. If this symbol does not exist, +@command{gawk} emits a fatal error and exits when it tries to load +your extension. The declared type of the symbol should be @code{int}. It does not need to be in any allocated section, though. The code merely asserts that @@ -29996,7 +30460,7 @@ int plugin_is_GPL_compatible; Communication between @command{gawk} and an extension is two-way. First, when an extension -is loaded, it is passed a pointer to a @code{struct} whose fields are +is loaded, @command{gawk} passes it a pointer to a @code{struct} whose fields are function pointers. @ifnotdocbook This is shown in @ref{figure-load-extension}. @@ -30032,29 +30496,29 @@ This is shown in @inlineraw{docbook, <xref linkend="figure-load-extension"/>}. The extension can call functions inside @command{gawk} through these function pointers, at runtime, without needing (link-time) access to @command{gawk}'s symbols. One of these function pointers is to a -function for ``registering'' new built-in functions. +function for ``registering'' new functions. @ifnotdocbook -This is shown in @ref{figure-load-new-function}. +This is shown in @ref{figure-register-new-function}. @end ifnotdocbook @ifdocbook -This is shown in @inlineraw{docbook, <xref linkend="figure-load-new-function"/>}. +This is shown in @inlineraw{docbook, <xref linkend="figure-register-new-function"/>}. @end ifdocbook @ifnotdocbook -@float Figure,figure-load-new-function -@caption{Loading The New Function} +@float Figure,figure-register-new-function +@caption{Registering A New Function} @ifinfo -@center @image{api-figure2, , , Loading The New Function, txt} +@center @image{api-figure2, , , Registering A New Function, txt} @end ifinfo @ifnotinfo -@center @image{api-figure2, , , Loading The New Function} +@center @image{api-figure2, , , Registering A New Function} @end ifnotinfo @end float @end ifnotdocbook @docbook -<figure id="figure-load-new-function" float="0"> -<title>Loading The New Function</title> +<figure id="figure-register-new-function" float="0"> +<title>Registering A New Function</title> <mediaobject> <imageobject role="web"><imagedata fileref="api-figure2.png" format="PNG"/></imageobject> </mediaobject> @@ -30104,8 +30568,8 @@ and understandable. Although all of this sounds somewhat complicated, the result is that extension code is quite straightforward to write and to read. You can -see this in the sample extensions @file{filefuncs.c} (@pxref{Extension -Example}) and also the @file{testext.c} code for testing the APIs. +see this in the sample extension @file{filefuncs.c} (@pxref{Extension +Example}) and also in the @file{testext.c} code for testing the APIs. Some other bits and pieces: @@ -30139,13 +30603,13 @@ This (rather large) @value{SECTION} describes the API in detail. @menu * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. -* Requesting Values:: How to get a value. * Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @command{gawk}. * Printing Messages:: Functions for printing messages. * Updating @code{ERRNO}:: Functions for updating @code{ERRNO}. +* Requesting Values:: How to get a value. * Accessing Parameters:: Functions for accessing parameters. * Symbol Table Access:: Functions for accessing global variables. @@ -30164,6 +30628,9 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item +Allocating, reallocating, and releasing memory. + +@item Registration functions. You may register: @itemize @value{MINUS} @item @@ -30196,9 +30663,6 @@ Symbol table access: retrieving a global variable, creating one, or changing one. @item -Allocating, reallocating, and releasing memory. - -@item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -30266,15 +30730,15 @@ does not support this keyword, you should either place All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} -from the extension @emph{must} come from calling the API-provided function -pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}, +from the extension @emph{must} come from calling one of +@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item 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 since embedded @value{NUL} characters are allowed. @quotation NOTE @@ -30287,7 +30751,7 @@ and also how characters are likely to be input and output from files. @item When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type (number, string, -scalars, value cookie, array, or ``undefined''). When the request is +scalar, value cookie, array, or ``undefined''). When the request is ``undefined,'' the returned value will have the real underlying type. However, if the request and actual type don't match, the access function @@ -30350,8 +30814,8 @@ 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 the API-provided function -pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} +@strong{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. @@ -30406,7 +30870,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. Since @command{gawk} allows embedded @value{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. @@ -30446,7 +30910,7 @@ the cookie for getting the variable's value or for changing the variable's value. This is the @code{awk_scalar_t} type and @code{scalar_cookie} macro. Given a scalar cookie, @command{gawk} can directly retrieve or -modify the value, as required, without having to first find it. +modify the value, as required, without having to find it first. The @code{awk_value_cookie_t} type and @code{value_cookie} macro are similar. If you know that you wish to @@ -30456,149 +30920,6 @@ and then pass in that value cookie whenever you wish to set the value of a variable. This saves both storage space within the running @command{gawk} process as well as the time needed to create the value. -@node Requesting Values -@subsection Requesting Values - -All of the functions that return values from @command{gawk} -work in the same way. You pass in an @code{awk_valtype_t} value -to indicate what kind of value you expect. If the actual value -matches what you requested, the function returns true and fills -in the @code{awk_value_t} result. -Otherwise, the function returns false, and the @code{val_type} -member indicates the type of the actual value. You may then -print an error message, or reissue the request for the actual -value type, as appropriate. This behavior is summarized in -@ref{table-value-types-returned}. - -@c FIXME: Try to do this with spans... - -@float Table,table-value-types-returned -@caption{API Value Types Returned} -@docbook -<informaltable> -<tgroup cols="2"> - <colspec colwidth="50*"/><colspec colwidth="50*"/> - <thead> - <row><entry></entry><entry><para>Type of Actual Value:</para></entry></row> - </thead> - <tbody> - <row><entry></entry><entry></entry></row> - </tbody> -</tgroup> -<tgroup cols="6"> - <colspec colwidth="16.6*"/> - <colspec colwidth="16.6*"/> - <colspec colwidth="19.8*"/> - <colspec colwidth="15*"/> - <colspec colwidth="15*"/> - <colspec colwidth="16.6*"/> - <thead> - <row> - <entry></entry> - <entry></entry> - <entry><para>String</para></entry> - <entry><para>Number</para></entry> - <entry><para>Array</para></entry> - <entry><para>Undefined</para></entry> - </row> - </thead> - <tbody> - <row> - <entry></entry> - <entry><para><emphasis role="bold">String</emphasis></para></entry> - <entry><para>String</para></entry> - <entry><para>String</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Number</emphasis></para></entry> - <entry><para>Number if can be converted, else false</para></entry> - <entry><para>Number</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry><para><emphasis role="bold">Type</emphasis></para></entry> - <entry><para><emphasis role="bold">Array</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>Array</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <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> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> - <entry><para>String</para></entry> - <entry><para>Number</para></entry> - <entry><para>Array</para></entry> - <entry><para>Undefined</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para> - </entry><entry><para>false</para></entry> - </row> - </tbody> -</tgroup> -</informaltable> -@end docbook - -@ifnotplaintext -@ifnotdocbook -@multitable @columnfractions .50 .50 -@headitem @tab Type of Actual Value: -@end multitable -@multitable @columnfractions .166 .166 .198 .15 .15 .166 -@headitem @tab @tab String @tab Number @tab Array @tab Undefined -@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 @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 -@end ifnotdocbook -@end ifnotplaintext -@ifplaintext -@example - +-------------------------------------------------+ - | Type of Actual Value: | - +------------+------------+-----------+-----------+ - | String | Number | Array | Undefined | -+-----------+-----------+------------+------------+-----------+-----------+ -| | String | String | String | false | false | -| |-----------+------------+------------+-----------+-----------+ -| | Number | Number if | Number | false | false | -| | | can be | | | | -| | | converted, | | | | -| | | else false | | | | -| |-----------+------------+------------+-----------+-----------+ -| Type | Array | false | false | Array | false | -| Requested |-----------+------------+------------+-----------+-----------+ -| | Scalar | Scalar | Scalar | false | false | -| |-----------+------------+------------+-----------+-----------+ -| | Undefined | String | Number | Array | Undefined | -| |-----------+------------+------------+-----------+-----------+ -| | Value | false | false | false | false | -| | Cookie | | | | | -+-----------+-----------+------------+------------+-----------+-----------+ -@end example -@end ifplaintext -@end float - @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros @cindex allocating memory for extensions @@ -30607,22 +30928,24 @@ value type, as appropriate. This behavior is summarized in 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. @table @code @item void *gawk_malloc(size_t size); -Call @command{gawk}-provided @code{api_malloc()} to allocate storage that may +Call the correct version of @code{malloc()} to allocate storage that may be passed to @command{gawk}. @item void *gawk_calloc(size_t nmemb, size_t size); -Call @command{gawk}-provided @code{api_calloc()} to allocate storage that may +Call the correct version of @code{calloc()} to allocate storage that may be passed to @command{gawk}. @item void *gawk_realloc(void *ptr, size_t size); -Call @command{gawk}-provided @code{api_realloc()} to allocate storage that may +Call the correct version of @code{realloc()} to allocate storage that may be passed to @command{gawk}. @item void gawk_free(void *ptr); -Call @command{gawk}-provided @code{api_free()} to release storage that was +Call the correct version of @code{free()} to release storage that was allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. @end table @@ -30636,8 +30959,8 @@ unrelated version of @code{malloc()}, unexpected behavior would likely result. Two convenience macros may be used for allocating storage -from the API-provided function pointers @code{api_malloc()} and -@code{api_realloc()}. If the allocation fails, they cause @command{gawk} +from @code{gawk_malloc()} and +@code{gawk_realloc()}. If the allocation fails, they cause @command{gawk} to exit with a fatal error message. They should be used as if they were procedure calls that do not return a value. @@ -30651,7 +30974,7 @@ 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{api_malloc()}. +The type of the pointer variable, used to create a cast for the call to @code{gawk_malloc()}. @item size The total number of bytes to be allocated. @@ -30675,8 +30998,8 @@ make_malloced_string(message, strlen(message), & result); @end example @item #define erealloc(pointer, type, size, message) @dots{} -This is like @code{emalloc()}, but it calls @code{api_realloc()}, -instead of @code{api_malloc()}. +This is like @code{emalloc()}, but it calls @code{gawk_realloc()}, +instead of @code{gawk_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table @@ -30700,7 +31023,7 @@ for storage in @code{result}. It returns @code{result}. @itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) This function creates a string value in the @code{awk_value_t} variable pointed to by @code{result}. It expects @code{string} to be a @samp{char *} -value pointing to data previously obtained from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. The idea here +value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. The idea here is that the data is passed directly to @command{gawk}, which assumes responsibility for it. It returns @code{result}. @@ -30755,17 +31078,18 @@ The name of the new function. This is a regular C string. Function names must obey the rules for @command{awk} -identifiers. That is, they must begin with either a letter +identifiers. That is, they must begin with either an English letter or an underscore, which may be followed by any number of letters, digits, and underscores. Letter case in function names is significant. @item awk_value_t *(*function)(int num_actual_args, awk_value_t *result); -This is a pointer to the C function that provides the desired +This is a pointer to the C function that provides the extension's functionality. -The function must fill in the result with either a number +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 the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_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. @@ -30776,7 +31100,7 @@ This is for the convenience of the calling code inside @command{gawk}. @item size_t num_expected_args; This is the number of arguments the function expects to receive. Each extension function may decide what to do if the number of -arguments isn't what it expected. Following @command{awk} functions, it +arguments isn't what it expected. As with real @command{awk} functions, it is likely OK to ignore extra arguments. @end table @@ -31030,7 +31354,7 @@ If the concept of a ``record terminator'' makes sense, then @code{RT}, and @code{*rt_len} should be set to the length of the data. Otherwise, @code{*rt_len} should be set to zero. @code{gawk} makes its own copy of this data, so the -extension must manage the storage. +extension must manage this storage. @end table The return value is the length of the buffer pointed to by @@ -31309,10 +31633,148 @@ into a (possibly translated) string using the C @code{strerror()} function. Set @code{ERRNO} directly to the string value of @code{ERRNO}. @command{gawk} makes a copy of the value of @code{string}. -@item void unset_ERRNO(); +@item void unset_ERRNO(void); Unset @code{ERRNO}. @end table +@node Requesting Values +@subsection Requesting Values + +All of the functions that return values from @command{gawk} +work in the same way. You pass in an @code{awk_valtype_t} value +to indicate what kind of value you expect. If the actual value +matches what you requested, the function returns true and fills +in the @code{awk_value_t} result. +Otherwise, the function returns false, and the @code{val_type} +member indicates the type of the actual value. You may then +print an error message, or reissue the request for the actual +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} +@docbook +<informaltable> +<tgroup cols="6"> + <colspec colwidth="16.6*"/> + <colspec colwidth="16.6*"/> + <colspec colwidth="19.8*" colname="c3"/> + <colspec colwidth="15*" colname="c4"/> + <colspec colwidth="15*" colname="c5"/> + <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></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + </thead> + <tbody> + <row> + <entry></entry> + <entry><para><emphasis role="bold">String</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>String</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Number</emphasis></para></entry> + <entry><para>Number if can be converted, else false</para></entry> + <entry><para>Number</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Type</emphasis></para></entry> + <entry><para><emphasis role="bold">Array</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>Array</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <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> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para> + </entry><entry><para>false</para></entry> + </row> + </tbody> +</tgroup> +</informaltable> +@end docbook + +@ifnotplaintext +@ifnotdocbook +@multitable @columnfractions .50 .50 +@headitem @tab Type of Actual Value: +@end multitable +@c 10/2014: Thanks to Karl Berry for this bit to reduce the space: +@tex +\vglue-1.1\baselineskip +@end tex +@multitable @columnfractions .166 .166 .198 .15 .15 .166 +@headitem @tab @tab String @tab Number @tab Array @tab Undefined +@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 @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 +@end ifnotdocbook +@end ifnotplaintext +@ifplaintext +@example + +-------------------------------------------------+ + | Type of Actual Value: | + +------------+------------+-----------+-----------+ + | String | Number | Array | Undefined | ++-----------+-----------+------------+------------+-----------+-----------+ +| | String | String | String | false | false | +| |-----------+------------+------------+-----------+-----------+ +| | Number | Number if | Number | false | false | +| | | can be | | | | +| | | converted, | | | | +| | | else false | | | | +| |-----------+------------+------------+-----------+-----------+ +| Type | Array | false | false | Array | false | +| Requested |-----------+------------+------------+-----------+-----------+ +| | Scalar | Scalar | Scalar | false | false | +| |-----------+------------+------------+-----------+-----------+ +| | Undefined | String | Number | Array | Undefined | +| |-----------+------------+------------+-----------+-----------+ +| | Value | false | false | false | false | +| | Cookie | | | | | ++-----------+-----------+------------+------------+-----------+-----------+ +@end example +@end ifplaintext +@end float + @node Accessing Parameters @subsection Accessing and Updating Parameters @@ -31367,7 +31829,7 @@ about symbols is termed a @dfn{symbol table}. Fill in the @code{awk_value_t} structure pointed to by @code{result} with the value of the variable named by the string @code{name}, which is a regular C string. @code{wanted} indicates the type of value expected. -Return true if the actual type matches @code{wanted}, false otherwise +Return true if the actual type matches @code{wanted}, false otherwise. In the latter case, @code{result->val_type} indicates the actual type (@pxref{table-value-types-returned}). @@ -31386,7 +31848,7 @@ An extension can look up the value of @command{gawk}'s special variables. However, with the exception of the @code{PROCINFO} array, an extension cannot change any of those variables. -@quotation NOTE +@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 @@ -31408,14 +31870,14 @@ The following functions let you work with scalar cookies. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result); Retrieve the current value of a scalar cookie. -Once you have obtained a scalar_cookie using @code{sym_lookup()}, you can +Once you have obtained a scalar cookie using @code{sym_lookup()}, you can use this function to get its value more efficiently. Return false if the value cannot be retrieved. @item awk_bool_t sym_update_scalar(awk_scalar_t cookie, awk_value_t *value); Update the value associated with a scalar cookie. Return false if the new value is not of type @code{AWK_STRING} or @code{AWK_NUMBER}. -Here too, the built-in variables may not be updated. +Here too, the predefined variables may not be updated. @end table It is not obvious at first glance how to work with scalar cookies or @@ -31470,7 +31932,7 @@ my_extension_init() /* install initial value */ sym_update("MAGIC_VAR", make_number(42.0, & value)); - /* get cookie */ + /* get the cookie */ sym_lookup("MAGIC_VAR", AWK_SCALAR, & value); /* save the cookie */ @@ -31519,7 +31981,8 @@ assign those values to variables using @code{sym_update()} 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{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. +@emph{every} string value's storage @emph{must} come from @code{gawk_malloc()}, +@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.} @@ -31590,7 +32053,7 @@ Using value cookies in this way saves considerable storage, since all of You might be wondering, ``Is this sharing problematic? What happens if @command{awk} code assigns a new value to @code{VAR1}, -are all the others be changed too?'' +are all the others changed too?'' That's a great question. The answer is that no, it's not a problem. Internally, @command{gawk} uses @dfn{reference-counted strings}. This means @@ -31645,7 +32108,7 @@ with the @code{<stdio.h>} library routines. @itemx @ @ @ @ struct awk_element *next; @itemx @ @ @ @ enum @{ @itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DEFAULT = 0,@ @ /* set by gawk */ -@itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DELETE = 1@ @ @ @ /* set by extension if should be deleted */ +@itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DELETE = 1@ @ @ @ /* set by extension */ @itemx @ @ @ @ @} flags; @itemx @ @ @ @ awk_value_t index; @itemx @ @ @ @ awk_value_t value; @@ -31665,8 +32128,8 @@ an extension to create a linked list of new elements that can then be added to an array in a loop that traverses the list. @item enum @{ @dots{} @} flags; -A set of flag values that convey information between @command{gawk} -and the extension. Currently there is only one: @code{AWK_ELEMENT_DELETE}. +A set of flag values that convey information between the extension +and @command{gawk}. Currently there is only one: @code{AWK_ELEMENT_DELETE}. Setting it causes @command{gawk} to delete the element from the original array upon release of the flattened array. @@ -31677,8 +32140,8 @@ The index and value of the element, respectively. @end table @item typedef struct awk_flat_array @{ -@itemx @ @ @ @ awk_const void *awk_const opaque1;@ @ @ @ /* private data for use by gawk */ -@itemx @ @ @ @ awk_const void *awk_const opaque2;@ @ @ @ /* private data for use by gawk */ +@itemx @ @ @ @ awk_const void *awk_const opaque1;@ @ @ @ /* for use by gawk */ +@itemx @ @ @ @ awk_const void *awk_const opaque2;@ @ @ @ /* for use by gawk */ @itemx @ @ @ @ awk_const size_t count;@ @ @ @ @ /* how many elements */ @itemx @ @ @ @ awk_element_t elements[1];@ @ /* will be extended */ @itemx @} awk_flat_array_t; @@ -31697,7 +32160,7 @@ The following functions relate to individual array elements. @table @code @item awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count); -For the array represented by @code{a_cookie}, return in @code{*count} +For the array represented by @code{a_cookie}, place in @code{*count} the number of elements it contains. A subarray counts as a single element. Return false if there is an error. @@ -31717,7 +32180,8 @@ requires that you understand how such values are converted to strings (@pxref{Conversion}); thus using integral values is safest. As with @emph{all} strings passed into @code{gawk} from an extension, -the string value of @code{index} must come from the API-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and +the string value of @code{index} must come from @code{gawk_malloc()}, +@code{gawk_calloc()} or @code{gawk_realloc()}, and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -31744,7 +32208,7 @@ not exist in the array. The following functions relate to arrays as a whole: @table @code -@item awk_array_t create_array(); +@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 create a new array and add elements to it. @@ -31761,7 +32225,13 @@ For the array represented by @code{a_cookie}, create an @code{awk_flat_array_t} structure and fill it in. Set the pointer whose address is passed as @code{data} to point to this structure. Return true upon success, or false otherwise. -@xref{Flattening Arrays}, for a discussion of how to +@ifset FOR_PRINT +See the next section +@end ifset +@ifclear FOR_PRINT +@xref{Flattening Arrays}, +@end ifclear +for a discussion of how to flatten an array and work with it. @item awk_bool_t release_flattened_array(awk_array_t a_cookie, @@ -31781,6 +32251,7 @@ for C code to traverse the entire array. Test code in @file{extension/testext.c} does this, and also serves as a nice example showing how to use the APIs. +We walk through that part of the code one step at a time. First, the @command{gawk} script that drives the test extension: @example @@ -31919,8 +32390,7 @@ have this flag bit set: valrep2str(& flat_array->elements[i].value)); if (strcmp(value3.str_value.str, - flat_array->elements[i].index.str_value.str) - == 0) @{ + flat_array->elements[i].index.str_value.str) == 0) @{ flat_array->elements[i].flags |= AWK_ELEMENT_DELETE; printf("dump_array_and_delete: marking element \"%s\" " "for deletion\n", @@ -32024,7 +32494,9 @@ of the array cookie after the call to @code{set_element()}. 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} -directives and boilerplate variable declarations are omitted for brevity. +directives and boilerplate variable declarations +(@pxref{Extension API Boilerplate}) +are omitted for brevity. The first step is to create a new array and then install it in the symbol table: @@ -32270,7 +32742,7 @@ This variable is true if @command{gawk} was invoked with @option{--traditional} @end table The value of @code{do_lint} can change if @command{awk} code -modifies the @code{LINT} built-in variable (@pxref{Built-in Variables}). +modifies the @code{LINT} predefined variable (@pxref{Built-in Variables}). The others should not change during execution. @node Extension API Boilerplate @@ -32303,12 +32775,12 @@ static awk_bool_t (*init_func)(void) = NULL; /* OR: */ static awk_bool_t -init_my_module(void) +init_my_extension(void) @{ @dots{} @} -static awk_bool_t (*init_func)(void) = init_my_module; +static awk_bool_t (*init_func)(void) = init_my_extension; dl_load_func(func_table, some_name, "name_space_in_quotes") @end example @@ -32351,8 +32823,8 @@ It can then be looped over for multiple calls to @c Use @var{OR} for docbook @item static awk_bool_t (*init_func)(void) = NULL; @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @var{OR} -@itemx static awk_bool_t init_my_module(void) @{ @dots{} @} -@itemx static awk_bool_t (*init_func)(void) = init_my_module; +@itemx static awk_bool_t init_my_extension(void) @{ @dots{} @} +@itemx static awk_bool_t (*init_func)(void) = init_my_extension; If you need to do some initialization work, you should define a function that does it (creates variables, opens files, etc.) and then define the @code{init_func} pointer to point to your @@ -32419,8 +32891,8 @@ path with a list of directories to search for compiled extensions. Two useful functions that are not in @command{awk} are @code{chdir()} (so that an @command{awk} program can change its directory) and @code{stat()} (so that an @command{awk} program can gather information about a file). -This @value{SECTION} implements these functions for @command{gawk} -in an extension. +In order to illustrate the API in action, this @value{SECTION} implements +these functions for @command{gawk} in an extension. @menu * Internal File Description:: What the new functions will do. @@ -32442,8 +32914,7 @@ straightforward. It takes one argument, the new directory to change to: newdir = "/home/arnold/funstuff" ret = chdir(newdir) if (ret < 0) @{ - printf("could not change to %s: %s\n", - newdir, ERRNO) > "/dev/stderr" + printf("could not change to %s: %s\n", newdir, ERRNO) > "/dev/stderr" exit 1 @} @dots{} @@ -32631,7 +33102,7 @@ The second is a pointer to an @code{awk_value_t}, usually named @code{result}. @example -/* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ +/* do_chdir --- provide dynamically loaded chdir() function for gawk */ static awk_value_t * do_chdir(int nargs, awk_value_t *result) @@ -32840,13 +33311,22 @@ for success: @} @} - array_set(array, "type", make_const_string(type, strlen(type), &tmp)); + array_set(array, "type", make_const_string(type, strlen(type), & tmp)); return 0; @} @end example -Finally, here is the @code{do_stat()} function. It starts with +The third argument to @code{stat()} was not discussed previously. This +argument is optional. If present, it causes @code{do_stat()} to use +the @code{stat()} system call instead of the @code{lstat()} system +call. This is done by using a function pointer: @code{statfunc}. +@code{statfunc} is initialized to point to @code{lstat()} (instead +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 variable declarations and argument checking: @ignore @@ -32877,16 +33357,10 @@ do_stat(int nargs, awk_value_t *result) @} @end example -The third argument to @code{stat()} was not discussed previously. This argument -is optional. If present, it causes @code{stat()} to use the @code{stat()} -system call instead of the @code{lstat()} system call. - Then comes the actual work. First, the function gets the arguments. -Next, it gets the information for the file. -The code use @code{lstat()} (instead of @code{stat()}) -to get the file information, -in case the file is a symbolic link. -If there's an error, it sets @code{ERRNO} and returns: +Next, it gets the information for the file. If the called function +(@code{lstat()} or @code{stat()}) returns an error, the code sets +@code{ERRNO} and returns: @example /* file is first arg, array to hold results is second */ @@ -32915,7 +33389,7 @@ If there's an error, it sets @code{ERRNO} and returns: @end example The tedious work is done by @code{fill_stat_array()}, shown -earlier. When done, return the result from @code{fill_stat_array()}: +earlier. When done, the function returns the result from @code{fill_stat_array()}: @example ret = fill_stat_array(name, array, & sbuf); @@ -32978,7 +33452,7 @@ 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 configure and build your libraries. Instructions for doing so are beyond -the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for WWW links to +the scope of this @value{DOCUMENT}. @xref{gawkextlib}, for Internet links to the tools.} create a GNU/Linux shared library: @example @@ -33006,14 +33480,14 @@ BEGIN @{ for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] print "testff.awk modified:", - strftime("%m %d %y %H:%M:%S", data["mtime"]) + strftime("%m %d %Y %H:%M:%S", data["mtime"]) print "\nInfo for JUNK" ret = stat("JUNK", data) print "ret =", ret for (i in data) printf "data[\"%s\"] = %s\n", i, data[i] - print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"]) + print "JUNK modified:", strftime("%m %d %Y %H:%M:%S", data["mtime"]) @} @end example @@ -33027,25 +33501,26 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk} @print{} Info for testff.awk @print{} ret = 0 @print{} data["blksize"] = 4096 -@print{} data["mtime"] = 1350838628 +@print{} data["devbsize"] = 512 +@print{} data["mtime"] = 1412004710 @print{} data["mode"] = 33204 @print{} data["type"] = file @print{} data["dev"] = 2053 @print{} data["gid"] = 1000 -@print{} data["ino"] = 1719496 -@print{} data["ctime"] = 1350838628 +@print{} data["ino"] = 10358899 +@print{} data["ctime"] = 1412004710 @print{} data["blocks"] = 8 @print{} data["nlink"] = 1 @print{} data["name"] = testff.awk -@print{} data["atime"] = 1350838632 +@print{} data["atime"] = 1412004716 @print{} data["pmode"] = -rw-rw-r-- -@print{} data["size"] = 662 +@print{} data["size"] = 666 @print{} data["uid"] = 1000 -@print{} testff.awk modified: 10 21 12 18:57:08 -@print{} +@print{} testff.awk modified: 09 29 2014 18:31:50 +@print{} @print{} Info for JUNK @print{} ret = -1 -@print{} JUNK modified: 01 01 70 02:00:00 +@print{} JUNK modified: 01 01 1970 02:00:00 @end example @node Extension Samples @@ -33070,9 +33545,9 @@ Others mainly provide example code that shows how to use the extension API. * Extension Sample Rev2way:: Reversing data sample two-way processor. * Extension Sample Read write array:: Serializing an array to a file. * Extension Sample Readfile:: Reading an entire file into a string. -* Extension Sample API Tests:: Tests for the API. * Extension Sample Time:: An interface to @code{gettimeofday()} and @code{sleep()}. +* Extension Sample API Tests:: Tests for the API. @end menu @node Extension Sample File Functions @@ -33082,7 +33557,7 @@ The @code{filefuncs} extension provides three different functions, as follows: The usage is: @table @asis -@item @@load "filefuncs" +@item @code{@@load "filefuncs"} This is how you load the extension. @cindex @code{chdir()} extension function @@ -33145,7 +33620,7 @@ Not all systems support all file types. @tab All @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 constant values, also described below. +OR of several predefined values, also described below. Return zero if there were no errors, otherwise return @minus{}1. @end table @@ -33190,10 +33665,10 @@ Immediately follow a symbolic link named in @code{pathlist}, whether or not @code{FTS_LOGICAL} is set. @item FTS_SEEDOT -By default, the @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.) +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.) @item FTS_XDEV During a traversal, do not cross onto a different mounted filesystem. @@ -33247,8 +33722,8 @@ Otherwise it returns @minus{}1. @quotation NOTE 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 should -be more comfortable to use from an @command{awk} program. This includes the +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 interface could have been provided, this felt less natural than simply @@ -33256,7 +33731,8 @@ creating a multidimensional array to represent the file hierarchy and its information. @end quotation -See @file{test/fts.awk} in the @command{gawk} distribution for an example. +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()} @@ -33464,7 +33940,7 @@ indicating the type of the file. The letters are file types are shown in @ref{table-readdir-file-types}. @float Table,table-readdir-file-types -@caption{File Types Returned By @code{readdir()}} +@caption{File Types Returned By The @code{readdir} Extension} @multitable @columnfractions .1 .9 @headitem Letter @tab File Type @item @code{b} @tab Block device @@ -33556,6 +34032,9 @@ The @code{rwarray} extension adds two functions, named @code{writea()} and @code{reada()}, as follows: @table @code +@item @@load "rwarray" +This is how you load the extension. + @cindex @code{writea()} extension function @item ret = writea(file, array) This function takes a string argument, which is the name of the file @@ -33631,17 +34110,6 @@ if (contents == "" && ERRNO != "") @{ @} @end example -@node Extension Sample API Tests -@subsection API Tests -@cindex @code{testext} extension - -The @code{testext} extension exercises parts of the extension API that -are not tested by the other samples. The @file{extension/testext.c} -file contains both the C code for the extension and @command{awk} -test code inside C comments that run the tests. The testing framework -extracts the @command{awk} code and runs the tests. See the source file -for more information. - @node Extension Sample Time @subsection Extension Time Functions @@ -33672,6 +34140,17 @@ Implementation details: depending on platform availability, this function tries to use @code{nanosleep()} or @code{select()} to implement the delay. @end table +@node Extension Sample API Tests +@subsection API Tests +@cindex @code{testext} extension + +The @code{testext} extension exercises parts of the extension API that +are not tested by the other samples. The @file{extension/testext.c} +file contains both the C code for the extension and @command{awk} +test code inside C comments that run the tests. The testing framework +extracts the @command{awk} code and runs the tests. See the source file +for more information. + @node gawkextlib @section The @code{gawkextlib} Project @cindex @code{gawkextlib} @@ -33687,8 +34166,7 @@ As of this writing, there are five extensions: @itemize @value{BULLET} @item -XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} -XML parsing library. +GD graphics library extension. @item PDF extension. @@ -33697,17 +34175,14 @@ PDF extension. PostgreSQL extension. @item -GD graphics library extension. - -@item MPFR library extension. This provides access to a number of MPFR functions which @command{gawk}'s native MPFR support does not. -@end itemize -The @code{time} extension described earlier (@pxref{Extension Sample -Time}) was originally from this project but has been moved in to the -main @command{gawk} distribution. +@item +XML parser extension, using the @uref{http://expat.sourceforge.net, Expat} +XML parsing library. +@end itemize @cindex @command{git} utility You can check out the code for the @code{gawkextlib} project @@ -33784,7 +34259,7 @@ certain tasks. @item One of these tasks is to ``register'' the name and implementation of -a new @command{awk}-level function with @command{gawk}. The implementation +new @command{awk}-level functions with @command{gawk}. The implementation takes the form of a C function pointer with a defined signature. By convention, implementation functions are named @code{do_@var{XXXX}()} for some @command{awk}-level function @code{@var{XXXX}()}. @@ -33798,6 +34273,9 @@ API function pointers are provided for the following kinds of operations: @itemize @value{BULLET} @item +Allocating, reallocating, and releasing memory. + +@item Registration functions. You may register extension functions, exit callbacks, @@ -33821,9 +34299,6 @@ Symbol table access: retrieving a global variable, creating one, or changing one. @item -Allocating, reallocating, and releasing memory. - -@item Creating and releasing cached values; this provides an efficient way to use values for multiple variables and can be a big performance win. @@ -33835,7 +34310,7 @@ 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 @@ -33855,7 +34330,7 @@ treated as read-only by the extension. @item @emph{All} memory passed from an extension to @command{gawk} must come from the API's memory allocation functions. @command{gawk} takes responsibility for -the memory and will release it when appropriate. +the memory and releases it when appropriate. @item The API provides information about the running version of @command{gawk} so @@ -33872,10 +34347,11 @@ The @command{gawk} distribution includes a number of small but useful sample extensions. The @code{gawkextlib} project includes several more, larger, extensions. If you wish to write an extension and contribute it to the community of @command{gawk} users, the @code{gawkextlib} project -should be the place to do so. +is the place to do so. @end itemize +@c EXCLUDE START @node Extension Exercises @section Exercises @@ -33898,6 +34374,7 @@ Write a wrapper script that provides an interface similar to @ref{Extension Sample Inplace}. @end enumerate +@c EXCLUDE END @ifnotinfo @part @value{PART4}Appendices @@ -33952,7 +34429,7 @@ which follows the POSIX specification. Many long-time @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 -of Berkeley Unix, and some systems derived from 4.4BSD-Lite, used various +of Berkeley Unix, and, for a while, some systems derived from 4.4BSD-Lite, used various versions of @command{gawk} for their @command{awk}.) This @value{CHAPTER} briefly describes the evolution of the @command{awk} language, with cross-references to other parts of the @value{DOCUMENT} where you can @@ -34025,7 +34502,7 @@ The built-in functions @code{close()} and @code{system()} @item The @code{ARGC}, @code{ARGV}, @code{FNR}, @code{RLENGTH}, @code{RSTART}, -and @code{SUBSEP} built-in variables (@pxref{Built-in Variables}). +and @code{SUBSEP} predefined variables (@pxref{Built-in Variables}). @item Assignable @code{$0} (@pxref{Changing Fields}). @@ -34056,14 +34533,11 @@ of @code{FS}. @item Dynamic regexps as operands of the @samp{~} and @samp{!~} operators -(@pxref{Regexp Usage}). +(@pxref{Computed Regexps}). @item The escape sequences @samp{\b}, @samp{\f}, and @samp{\r} (@pxref{Escape Sequences}). -(Some vendors have updated their old versions of @command{awk} to -recognize @samp{\b}, @samp{\f}, and @samp{\r}, but this is not -something you can rely on.) @item Redirection of input for the @code{getline} function @@ -34102,7 +34576,7 @@ The @option{-v} option for assigning variables before program execution begins @c GNU, Bell Laboratories & MKS together @item -The @option{--} option for terminating command-line options. +The @option{--} signal for terminating command-line options. @item The @samp{\a}, @samp{\v}, and @samp{\x} escape sequences @@ -34119,13 +34593,13 @@ for case translation (@pxref{String Functions}). @item -A cleaner specification for the @samp{%c} format-control letter in the +A cleaner specification for the @code{%c} format-control letter in the @code{printf} function (@pxref{Control Letters}). @item The ability to dynamically pass the field width and precision (@code{"%*.*d"}) -in the argument list of the @code{printf} function +in the argument list of @code{printf} and @code{sprintf()} (@pxref{Control Letters}). @item @@ -34160,8 +34634,8 @@ The concept of a numeric string and tighter comparison rules to go with it (@pxref{Typing and Comparison}). @item -The use of built-in variables as function parameter names is forbidden -(@pxref{Definition Syntax}. +The use of predefined variables as function parameter names is forbidden +(@pxref{Definition Syntax}). @item More complete documentation of many of the previously undocumented @@ -34256,7 +34730,7 @@ in the current version of @command{gawk}. @itemize @value{BULLET} @item -Additional built-in variables: +Additional predefined variables: @itemize @value{MINUS} @item @@ -34340,14 +34814,6 @@ The @code{BEGINFILE} and @code{ENDFILE} special patterns. (@pxref{BEGINFILE/ENDFILE}). @item -The ability to delete all of an array at once with @samp{delete @var{array}} -(@pxref{Delete}). - -@item -The @code{nextfile} statement -(@pxref{Nextfile Statement}). - -@item The @code{switch} statement (@pxref{Switch Statement}). @end itemize @@ -34362,7 +34828,7 @@ of a two-way pipe to a coprocess (@pxref{Two-way I/O}). @item -POSIX compliance for @code{gsub()} and @code{sub()}. +POSIX compliance for @code{gsub()} and @code{sub()} with @option{--posix}. @item The @code{length()} function accepts an array argument @@ -34390,6 +34856,20 @@ Additional functions only in @command{gawk}: @itemize @value{MINUS} @item +The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions +for more powerful text manipulation +(@pxref{String Functions}). + +@item +The @code{asort()} and @code{asorti()} functions for sorting arrays +(@pxref{Array Sorting}). + +@item +The @code{mktime()}, @code{systime()}, and @code{strftime()} +functions for working with timestamps +(@pxref{Time Functions}). + +@item The @code{and()}, @code{compl()}, @@ -34403,30 +34883,15 @@ functions for bit manipulation @c In 4.1, and(), or() and xor() grew the ability to take > 2 arguments @item -The @code{asort()} and @code{asorti()} functions for sorting arrays -(@pxref{Array Sorting}). +The @code{isarray()} function to check if a variable is an array or not +(@pxref{Type Functions}). @item The @code{bindtextdomain()}, @code{dcgettext()} and @code{dcngettext()} functions for internationalization (@pxref{Programmer i18n}). - -@item -The @code{fflush()} function from BWK @command{awk} -(@pxref{I/O Functions}). - -@item -The @code{gensub()}, @code{patsplit()}, and @code{strtonum()} functions -for more powerful text manipulation -(@pxref{String Functions}). - -@item -The @code{mktime()}, @code{systime()}, and @code{strftime()} -functions for working with timestamps -(@pxref{Time Functions}). @end itemize - @item Changes and/or additions in the command-line options: @@ -34549,7 +35014,7 @@ GCC for VAX and Alpha has not been tested for a while. @item Support for the following obsolete systems was removed from the code -and the documentation for @command{gawk} @value{PVERSION} 4.1: +for @command{gawk} @value{PVERSION} 4.1: @c nested table @itemize @value{MINUS} @@ -34557,6 +35022,10 @@ and the documentation for @command{gawk} @value{PVERSION} 4.1: Ultrix @end itemize +@item +@c FIXME: Verify the version here. +Support for MirBSD was removed at @command{gawk} @value{PVERSION} 4.2. + @end itemize @c XXX ADD MORE STUFF HERE @@ -35182,33 +35651,29 @@ The dynamic extension interface was completely redone @cindex extensions, Brian Kernighan's @command{awk} @cindex extensions, @command{mawk} -This @value{SECTION} summarizes the common extensions supported +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} (@pxref{Other Versions}). -@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} -@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk -@item @samp{\x} Escape sequence @tab X @tab X @tab X -@item @code{FS} as null string @tab X @tab X @tab X -@item @file{/dev/stdin} special file @tab X @tab X @tab X -@item @file{/dev/stdout} special file @tab X @tab X @tab X -@item @file{/dev/stderr} special file @tab X @tab X @tab X -@item @code{delete} without subscript @tab X @tab X @tab X -@item @code{fflush()} function @tab X @tab X @tab X -@item @code{length()} of an array @tab X @tab X @tab X -@item @code{nextfile} statement @tab X @tab X @tab X -@item @code{**} and @code{**=} operators @tab X @tab @tab X -@item @code{func} keyword @tab X @tab @tab X -@item @code{BINMODE} variable @tab @tab X @tab X -@item @code{RS} as regexp @tab @tab X @tab X -@item Time related functions @tab @tab X @tab X +@multitable {@file{/dev/stderr} special file} {BWK Awk} {Mawk} {GNU Awk} {Now standard} +@headitem Feature @tab BWK Awk @tab Mawk @tab GNU Awk @tab Now standard +@item @samp{\x} Escape sequence @tab X @tab X @tab X @tab +@item @code{FS} as null string @tab X @tab X @tab X @tab +@item @file{/dev/stdin} special file @tab X @tab X @tab X @tab +@item @file{/dev/stdout} special file @tab X @tab X @tab X @tab +@item @file{/dev/stderr} special file @tab X @tab X @tab X @tab +@item @code{delete} without subscript @tab X @tab X @tab X @tab X +@item @code{fflush()} function @tab X @tab X @tab X @tab X +@item @code{length()} of an array @tab X @tab X @tab X @tab +@item @code{nextfile} statement @tab X @tab X @tab X @tab X +@item @code{**} and @code{**=} operators @tab X @tab @tab X @tab +@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 @end multitable -(Technically speaking, as of late 2012, @code{fflush()}, @samp{delete @var{array}}, -and @code{nextfile} are no longer extensions, since they have been added -to POSIX.) - @node Ranges and Locales @appendixsec Regexp Ranges and Locales: A Long Sad Story @@ -35245,6 +35710,7 @@ In the @code{"C"} and @code{"POSIX"} locales, a range expression like But outside those locales, the ordering was defined to be based on @dfn{collation order}. +What does that mean? In many locales, @samp{A} and @samp{a} are both less than @samp{B}. In other words, these locales sort characters in dictionary order, and @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; @@ -35252,7 +35718,7 @@ instead it might be equivalent to @samp{[ABCXYabcdxyz]}, for example. 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 matched all of the uppercase characters +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 into the twenty-first century. @@ -35442,7 +35908,7 @@ the various PC platforms. @cindex Zoulas, Christos Christos Zoulas provided the @code{extension()} -built-in function for dynamically adding new modules. +built-in function for dynamically adding new functions. (This was obsoleted at @command{gawk} 4.1.) @item @@ -35558,6 +36024,11 @@ The development of the extension API first released with Arnold Robbins and Andrew Schorr, with notable contributions from the rest of the development team. +@cindex Malmberg, John E. +@item +John Malmberg contributed significant improvements to the +OpenVMS port and the related documentation. + @item @cindex Colombo, Antonio Antonio Giovanni Colombo rewrote a number of examples in the early @@ -35619,7 +36090,7 @@ 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 did +for the electronic mail addresses of the people who maintain the respective ports. @menu @@ -35938,11 +36409,10 @@ Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin environment for MS-Windows. After you have extracted the @command{gawk} distribution, @command{cd} -to @file{gawk-@value{VERSION}.@value{PATCHLEVEL}}. Like most GNU software, -@command{gawk} is configured -automatically for your system by running the @command{configure} program. -This program is a Bourne shell script that is generated automatically using -GNU Autoconf. +to @file{gawk-@value{VERSION}.@value{PATCHLEVEL}}. As with most GNU +software, you configure @command{gawk} for your system by running the +@command{configure} program. This program is a Bourne shell script that +is generated automatically using GNU Autoconf. @ifnotinfo (The Autoconf software is described fully in @@ -36037,8 +36507,8 @@ Similarly, setting the @code{LINT} variable has no effect on the running @command{awk} program. When used with GCC's automatic dead-code-elimination, this option -cuts almost 200K bytes off the size of the @command{gawk} -executable on GNU/Linux x86 systems. Results on other systems and +cuts almost 23K bytes off the size of the @command{gawk} +executable on GNU/Linux x86_64 systems. Results on other systems and with other compilers are likely to vary. Using this option may bring you some slight performance improvement. @@ -36131,7 +36601,8 @@ various non-Unix systems. @cindex PC operating systems@comma{} @command{gawk} on, installing @cindex operating systems, PC@comma{} @command{gawk} on, installing -This @value{SECTION} covers installation and usage of @command{gawk} on x86 machines +This @value{SECTION} covers installation and usage of @command{gawk} +on Intel architecture machines @ifclear FOR_PRINT running MS-DOS, any version of MS-Windows, or OS/2. @end ifclear @@ -36233,7 +36704,8 @@ MS-DOS and Windows32 versions. A list of targets is printed if the build @command{gawk} using the DJGPP tools, enter @samp{make djgpp}. (The DJGPP tools needed for the build may be found at @uref{ftp://ftp.delorie.com/pub/djgpp/current/v2gnu/}.) To build a -native MS-Windows binary of @command{gawk}, type @samp{make mingw32}. +native MS-Windows binary of @command{gawk} using the MinGW tools, +type @samp{make mingw32}. @ifclear FOR_PRINT @cindex compiling @command{gawk} with EMX for OS/2 @@ -36363,8 +36835,7 @@ The MS-DOS and MS-Windows versions of @command{gawk} search for program files as described in @ref{AWKPATH Variable}. However, semicolons (rather than colons) separate elements in the @env{AWKPATH} variable. If @env{AWKPATH} is not set or is empty, then the default -search path for MS-Windows and MS-DOS versions is -@samp{@w{.;c:/lib/awk;c:/gnu/lib/awk}}. +search path is @samp{@w{.;c:/lib/awk;c:/gnu/lib/awk}}. @ifclear FOR_PRINT @cindex @command{gawk}, OS/2 version of @@ -36409,12 +36880,12 @@ allows control over these translations and is interpreted as follows: @itemize @value{BULLET} @item -If @code{BINMODE} is @code{"r"}, or one, +If @code{BINMODE} is @code{"r"} or one, then binary mode is set on read (i.e., no translations on reads). @item -If @code{BINMODE} is @code{"w"}, or two, +If @code{BINMODE} is @code{"w"} or two, then binary mode is set on write (i.e., no translations on writes). @@ -36502,7 +36973,7 @@ same as for a Unix system: tar -xvpzf gawk-@value{VERSION}.@value{PATCHLEVEL}.tar.gz cd gawk-@value{VERSION}.@value{PATCHLEVEL} ./configure -make +make && make check @end example When compared to GNU/Linux on the same system, the @samp{configure} @@ -36518,10 +36989,10 @@ 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. Caveat Emptor! +translation of @code{"\r\n"}, since it won't. @node VMS Installation -@appendixsubsec How to Compile and Install @command{gawk} on Vax/VMS and OpenVMS +@appendixsubsec Compiling and Installing @command{gawk} on Vax/VMS and OpenVMS @c based on material from Pat Rankin <rankin@eql.caltech.edu> @c now rankin@pactechdata.com @@ -36626,7 +37097,7 @@ For VAX: @end example Compile time macros need to be defined before the first VMS-supplied -header file is included. +header file is included, as follows: @example #if (__CRTL_VER >= 70200000) && !defined (__VAX) @@ -36642,6 +37113,11 @@ header file is included. #endif @end example +If you are writing your own extensions to run on VMS, you must supply these +definitions yourself. The @file{config.h} file created when building @command{gawk} +on VMS does this for you; if instead you use that file or a similar one, then you +must remember to include it before any VMS-supplied header files. + @node VMS Installation Details @appendixsubsubsec Installing @command{gawk} on VMS @@ -36738,12 +37214,12 @@ other dash-type options (or multiple parameters such as @value{DF}s to process) are present, there is no ambiguity and @option{--} can be omitted. @cindex exit status, of VMS -The @code{exit} value is a Unix-style value and is encoded to a VMS exit +The @code{exit} value is a Unix-style value and is encoded into a VMS exit status value when the program exits. The VMS severity bits will be set based on the @code{exit} value. A failure is indicated by 1 and VMS sets the @code{ERROR} status. -A fatal error is indicated by 2 and VMS will set the @code{FATAL} status. +A fatal error is indicated by 2 and VMS sets the @code{FATAL} status. All other values will have the @code{SUCCESS} status. The exit value is encoded to comply with VMS coding standards and will have the @code{C_FACILITY_NO} of @code{0x350000} with the constant @code{0xA000} @@ -36759,7 +37235,7 @@ unix_status = (vms_status .and. &x7f8) / 8 A C program that uses @code{exec()} to call @command{gawk} will get the original Unix-style exit value. -Older versions of @command{gawk} treated a Unix exit code 0 as 1, a failure +Older versions of @command{gawk} for VMS treated a Unix exit code 0 as 1, a failure as 2, a fatal error as 4, and passed all the other numbers through. This violated the VMS exit status coding requirements. @@ -36793,8 +37269,8 @@ See @w{@uref{https://sourceforge.net/p/gnv/wiki/InstallingGNVPackages/}.} The normal build procedure for @command{gawk} produces a program that is suitable for use with GNV. -The @file{vms/gawk_build_steps.txt} in the source documents the procedure -for building a VMS PCSI kit that is compatible with GNV. +The file @file{vms/gawk_build_steps.txt} in the distribution documents +the procedure for building a VMS PCSI kit that is compatible with GNV. @ignore @c The VMS POSIX product, also known as POSIX for OpenVMS, is long defunct @@ -36866,8 +37342,8 @@ 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 but we might well want to fix it. -Before reporting a bug, make sure you have actually found a real bug. -Carefully reread the documentation and see if it really says you can do +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 documentation! @@ -36885,17 +37361,15 @@ You can get this information with the command @samp{gawk --version}. @cindex @code{bug-gawk@@gnu.org} bug reporting address @cindex email address for bug reports, @code{bug-gawk@@gnu.org} @cindex bug reports, email address, @code{bug-gawk@@gnu.org} -Once you have a precise problem, send email to +Once you have a precise problem description, send email to @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. -@cindex Robbins, Arnold The @command{gawk} maintainers subscribe to this address and thus they will receive your bug report. -If necessary, the primary maintainer can be reached directly at -@EMAIL{arnold@@skeeve.com,arnold at skeeve dot com}. -The bug reporting address is preferred since the +Although you can send mail to the maintainers directly, +the bug reporting address is preferred since the email list is archived at the GNU Project. -@emph{All email should be in English. This is the only language +@emph{All email must be in English. This is the only language understood in common by all the maintainers.} @cindex @code{comp.lang.awk} newsgroup @@ -36904,7 +37378,7 @@ 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 official recognized ways for reporting bugs. +above are the only official recognized way for reporting bugs. Really. @end quotation @@ -36916,35 +37390,34 @@ bug reporting system, @emph{please} also send a copy to 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 @command{gawk} maintainer won't even see the bug report! Second, +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 -keeps things self-contained and not dependant on other web sites. +keeps things self-contained and not dependant on other organizations. @end quotation 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 me; I will try to help you out, although I -may not have the time to fix the problem. You can send me electronic -mail at the Internet address noted previously. - -If you find bugs in one of the non-Unix ports of @command{gawk}, please send -an electronic mail message 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 if it conflicts with this -@value{DOCUMENT}. +features, ask on the bug list; we will try to help you out if we can. -The people maintaining the non-Unix ports of @command{gawk} are -as follows: +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 +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 +if it conflicts with this @value{DOCUMENT}. + +The people maintaining the various @command{gawk} ports are: @c put the index entries outside the table, for docbook -@cindex Deifik, Scott -@cindex Zaretskii, Eli @cindex Buening, Andreas -@cindex Rankin, Pat +@cindex Deifik, Scott @cindex Malmberg, John @cindex Pitts, Dave +@cindex Robbins, Arnold +@cindex Zaretskii, Eli @multitable {MS-Windows with MinGW} {123456789012345678901234567890123456789001234567890} +@item Unix and POSIX systems @tab Arnold Robbins, @EMAIL{arnold@@skeeve.com,arnold at skeeve dot com}. + @item MS-DOS with DJGPP @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}. @item MS-Windows with MinGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. @@ -36953,8 +37426,7 @@ as follows: @c OS/2 is not mentioned anywhere else in the print version though. @item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}. -@item VMS @tab Pat Rankin, @EMAIL{r.pat.rankin@@gmail.com,r.pat.rankin at gmail.com}, and -John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net}. +@item VMS @tab John Malmberg, @EMAIL{wb8tyw@@qsl.net,wb8tyw at qsl.net}. @item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. @end multitable @@ -36977,11 +37449,22 @@ Date: Wed, 4 Sep 1996 08:11:48 -0700 (PDT) @end ignore @cindex Brennan, Michael +@ifnotdocbook @quotation @i{It's kind of fun to put comments like this in your awk code.}@* @ @ @ @ @ @ @code{// Do C++ comments work? answer: yes! of course} @author Michael Brennan @end quotation +@end ifnotdocbook + +@docbook +<blockquote><attribution>Michael Brennan</attribution> +<literallayout><emphasis>It's kind of fun to put comments like this in your awk code.</emphasis> + <literal>// Do C++ comments work? answer: yes! of course</literal></literallayout> +</blockquote> +@end docbook + + There are a number of other freely available @command{awk} implementations. This @value{SECTION} briefly describes where to get them: @@ -37087,7 +37570,7 @@ since approximately 2003. @item @command{pawk} Nelson H.F.@: Beebe at the University of Utah has modified BWK @command{awk} to provide timing and profiling information. -It is different from @command{gawk} with the @option{--profile} option. +It is different from @command{gawk} with the @option{--profile} option (@pxref{Profiling}), in that it uses CPU-based profiling, not line-count profiling. You may find it at either @@ -37112,7 +37595,7 @@ information, see the @uref{http://busybox.net, project's home page}. The versions of @command{awk} in @file{/usr/xpg4/bin} and @file{/usr/xpg6/bin} on Solaris are more-or-less POSIX-compliant. They are based on the @command{awk} from Mortice Kern Systems for PCs. -This author was able to make this code compile and work under GNU/Linux +We were able to make this code compile and work under GNU/Linux with 1--2 hours of work. Making it more generally portable (using GNU Autoconf and/or Automake) would take more work, and this has not been done, at least to our knowledge. @@ -37288,7 +37771,7 @@ as well as any considerations you should bear in mind. @appendixsubsec Accessing The @command{gawk} Git Repository As @command{gawk} is Free Software, the source code is always available. -@ref{Gawk Distribution}, describes how to get and build the formal, +@DBREF{Gawk Distribution} describes how to get and build the formal, released versions of @command{gawk}. @cindex @command{git} utility @@ -37339,7 +37822,7 @@ make it possible to include them: @enumerate 1 @item Before building the new feature into @command{gawk} itself, -consider writing it as an extension module +consider writing it as an extension (@pxref{Dynamic Extensions}). If that's not possible, continue with the rest of the steps in this list. @@ -37584,7 +38067,7 @@ and @item Be willing to continue to maintain the port. Non-Unix operating systems are supported by volunteers who maintain -the code needed to compile and run @command{gawk} on their systems. If noone +the code needed to compile and run @command{gawk} on their systems. If no-one volunteers to maintain a port, it becomes unsupported and it may be necessary to remove it from the distribution. @@ -37646,7 +38129,7 @@ the derived files, because that keeps the repository less cluttered, and it is easier to see the substantive changes when comparing versions and trying to understand what changed between commits. -However, there are two reasons why the @command{gawk} maintainer +However, there are several reasons why the @command{gawk} maintainer likes to have everything in the repository. First, because it is then easy to reproduce any given version completely, @@ -37715,6 +38198,14 @@ the maintainer is no different than Jane User who wants to try to build Thus, the maintainer thinks that it's not just important, but critical, that for any given branch, the above incantation @emph{just works}. +@c Added 9/2014: +A third reason to have all the files is that without them, using @samp{git +bisect} to try to find the commit that introduced a bug is exceedingly +difficult. The maintainer tried to do that on another project that +requires running bootstrapping scripts just to create @command{configure} +and so on; it was really painful. When the repository is self-contained, +using @command{git bisect} in it is very easy. + @c So - that's my reasoning and philosophy. What are some of the consequences and/or actions to take? @@ -38062,7 +38553,7 @@ Pat Rankin suggested the solution that was adopted. @appendixsubsec Other Design Decisions As an arbitrary design decision, extensions can read the values of -built-in variables and arrays (such as @code{ARGV} and @code{FS}), but cannot +predefined variables and arrays (such as @code{ARGV} and @code{FS}), but cannot change them, with the exception of @code{PROCINFO}. The reason for this is to prevent an extension function from affecting @@ -38803,11 +39294,11 @@ See ``Free Documentation License.'' @item Field When @command{awk} reads an input record, it splits the record into pieces separated by whitespace (or by a separator regexp that you can -change by setting the built-in variable @code{FS}). Such pieces are +change by setting the predefined variable @code{FS}). Such pieces are called fields. If the pieces are of fixed length, you can use the built-in variable @code{FIELDWIDTHS} to describe their lengths. If you wish to specify the contents of fields instead of the field -separator, you can use the built-in variable @code{FPAT} to do so. +separator, you can use the predefined variable @code{FPAT} to do so. (@xref{Field Separators}, @ref{Constant Size}, and @@ -38826,7 +39317,7 @@ See also ``Double Precision'' and ``Single Precision.'' Format strings control the appearance of output in the @code{strftime()} and @code{sprintf()} functions, and in the @code{printf} statement as well. Also, data conversions from numbers to strings -are controlled by the format strings contained in the built-in variables +are controlled by the format strings contained in the predefined variables @code{CONVFMT} and @code{OFMT}. (@xref{Control Letters}.) @item Free Documentation License @@ -40505,6 +40996,7 @@ Consistency issues: Use --foo, not -Wfoo when describing long options Use "Bell Laboratories", but not "Bell Labs". Use "behavior" instead of "behaviour". + Use "coprocess" instead of "co-process". Use "zeros" instead of "zeroes". Use "nonzero" not "non-zero". Use "runtime" not "run time" or "run-time". @@ -40609,4 +41101,3 @@ But to use it you have to say which sorta sucks. TODO: ------ @@ -216,6 +216,7 @@ load_casetable(void) return; #ifndef ZOS_USS + /* use of isalpha is ok here (see is_alpha in awkgram.y) */ for (i = 0200; i <= 0377; i++) { if (isalpha(i) && islower(i) && i != toupper(i)) casetable[i] = toupper(i); @@ -241,6 +242,7 @@ static const char *const nodetypes[] = { "Node_func", "Node_ext_func", "Node_old_ext_func", + "Node_builtin_func", "Node_array_ref", "Node_array_tree", "Node_array_leaf", @@ -360,6 +362,7 @@ static struct optypetab { { "Op_after_beginfile", NULL }, { "Op_after_endfile", NULL }, { "Op_func", NULL }, + { "Op_comment", NULL }, { "Op_exec_count", NULL }, { "Op_breakpoint", NULL }, { "Op_lint", NULL }, @@ -46,33 +46,9 @@ extern SRCFILE *srcfiles; static bool is_letter(unsigned char c) { - switch (c) { - case 'a': case 'b': case 'c': case 'd': case 'e': case 'f': - case 'g': case 'h': case 'i': case 'j': case 'k': case 'l': - case 'm': case 'n': case 'o': case 'p': case 'q': case 'r': - case 's': case 't': case 'u': case 'v': case 'w': case 'x': - case 'y': case 'z': - case 'A': case 'B': case 'C': case 'D': case 'E': case 'F': - case 'G': case 'H': case 'I': case 'J': case 'K': case 'L': - case 'M': case 'N': case 'O': case 'P': case 'Q': case 'R': - case 'S': case 'T': case 'U': case 'V': case 'W': case 'X': - case 'Y': case 'Z': - case '_': - return true; - default: - return false; - } + return (is_alpha(c) || c == '_'); } -/* is_identifier_char --- return true if a character can be used in an identifier */ - -static bool -is_identifier_char(unsigned char c) -{ - return (is_letter(c) || isdigit(c)); -} - - #define INIT_FUNC "dl_load" /* load_ext --- load an external library */ @@ -224,7 +200,7 @@ make_builtin(const awk_ext_func_t *funcinfo) return awk_false; for (sp++; (c = *sp++) != '\0';) { - if (! is_identifier_char(c)) + if (! is_identchar(c)) return awk_false; } @@ -279,7 +255,7 @@ make_old_builtin(const char *name, NODE *(*func)(int), int count) /* temporary * fatal(_("extension: illegal character `%c' in function name `%s'"), *sp, name); for (sp++; (c = *sp++) != '\0';) { - if (! is_identifier_char(c)) + if (! is_identchar(c)) fatal(_("extension: illegal character `%c' in function name `%s'"), c, name); } diff --git a/extension/ChangeLog b/extension/ChangeLog index f324bdeb..3fee967f 100644 --- a/extension/ChangeLog +++ b/extension/ChangeLog @@ -1,3 +1,13 @@ +2014-10-08 Arnold D. Robbins <arnold@skeeve.com> + + * inplace.c (do_inplace_begin): Use a cast to void in front + of the second call to chown to avoid compiler warnings from clang. + +2014-09-29 Arnold D. Robbins <arnold@skeeve.com> + + * filefuncs.c: Minor edits to sync with documentation. + * testext.c: Add test to get PROCINFO, expected to fail. + 2014-08-12 Arnold D. Robbins <arnold@skeeve.com> * Makefile.am (RM): Define for makes that don't have it, diff --git a/extension/filefuncs.c b/extension/filefuncs.c index d5249a4e..a20e9ff7 100644 --- a/extension/filefuncs.c +++ b/extension/filefuncs.c @@ -145,7 +145,7 @@ static const char *ext_version = "filefuncs extension: version 1.0"; int plugin_is_GPL_compatible; -/* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ +/* do_chdir --- provide dynamically loaded chdir() function for gawk */ static awk_value_t * do_chdir(int nargs, awk_value_t *result) @@ -448,7 +448,7 @@ fill_stat_array(const char *name, awk_array_t array, struct stat *sbuf) } } - array_set(array, "type", make_const_string(type, strlen(type), &tmp)); + array_set(array, "type", make_const_string(type, strlen(type), & tmp)); return 0; } diff --git a/extension/inplace.c b/extension/inplace.c index e2f8b73f..8a7375c4 100644 --- a/extension/inplace.c +++ b/extension/inplace.c @@ -171,9 +171,8 @@ do_inplace_begin(int nargs, awk_value_t *result) /* N.B. chown/chmod should be more portable than fchown/fchmod */ if (chown(state.tname, sbuf.st_uid, sbuf.st_gid) < 0) - /* checking chown here shuts up the compiler. bleah */ - if (chown(state.tname, -1, sbuf.st_gid) < 0) - ; + (void) chown(state.tname, -1, sbuf.st_gid); + if (chmod(state.tname, sbuf.st_mode) < 0) fatal(ext_id, _("inplace_begin: chmod failed (%s)"), strerror(errno)); diff --git a/extension/testext.c b/extension/testext.c index 2dda339f..7462265b 100644 --- a/extension/testext.c +++ b/extension/testext.c @@ -302,6 +302,12 @@ var_test(int nargs, awk_value_t *result) goto out; } + /* look up PROCINFO - should fail */ + if (sym_lookup("PROCINFO", AWK_ARRAY, & value)) + printf("var_test: sym_lookup of PROCINFO failed - got a value!\n"); + else + printf("var_test: sym_lookup of PROCINFO passed - did not get a value\n"); + /* look up a reserved variable - should pass */ if (sym_lookup("ARGC", AWK_NUMBER, & value)) printf("var_test: sym_lookup of ARGC passed - got a value!\n"); @@ -865,17 +865,17 @@ static awk_bool_t (*init_func)(void) = NULL; /* OR: */ static awk_bool_t -init_my_module(void) +init_my_extension(void) { ... } -static awk_bool_t (*init_func)(void) = init_my_module; +static awk_bool_t (*init_func)(void) = init_my_extension; dl_load_func(func_table, some_name, "name_space_in_quotes") #endif -#define dl_load_func(func_table, module, name_space) \ +#define dl_load_func(func_table, extension, name_space) \ int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id) \ { \ size_t i, j; \ @@ -886,7 +886,7 @@ int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id) \ \ if (api->major_version != GAWK_API_MAJOR_VERSION \ || api->minor_version < GAWK_API_MINOR_VERSION) { \ - fprintf(stderr, #module ": version mismatch with gawk!\n"); \ + fprintf(stderr, #extension ": version mismatch with gawk!\n"); \ fprintf(stderr, "\tmy version (%d, %d), gawk version (%d, %d)\n", \ GAWK_API_MAJOR_VERSION, GAWK_API_MINOR_VERSION, \ api->major_version, api->minor_version); \ @@ -898,7 +898,7 @@ int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id) \ if (func_table[i].name == NULL) \ break; \ if (! add_ext_func(name_space, & func_table[i])) { \ - warning(ext_id, #module ": could not add %s\n", \ + warning(ext_id, #extension ": could not add %s\n", \ func_table[i].name); \ errors++; \ } \ @@ -906,7 +906,7 @@ int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id) \ \ if (init_func != NULL) { \ if (! init_func()) { \ - warning(ext_id, #module ": initialization function failed\n"); \ + warning(ext_id, #extension ": initialization function failed\n"); \ errors++; \ } \ } \ diff --git a/helpers/ChangeLog b/helpers/ChangeLog index c9121403..a5bbafb1 100644 --- a/helpers/ChangeLog +++ b/helpers/ChangeLog @@ -1,3 +1,7 @@ +2014-09-04 Arnold D. Robbins <arnold@skeeve.com> + + * chlistref.awk: New file. Finds @ref{} to non-chapters. + 2014-06-08 Arnold D. Robbins <arnold@skeeve.com> * testdfa.c: Minor improvements. diff --git a/helpers/chlistref.awk b/helpers/chlistref.awk new file mode 100644 index 00000000..49f63f59 --- /dev/null +++ b/helpers/chlistref.awk @@ -0,0 +1,31 @@ +BEGIN { + chapters["Getting Started"]++ + chapters["Invoking Gawk"]++ + chapters["Regexp"]++ + chapters["Reading Files"]++ + chapters["Printing"]++ + chapters["Expressions"]++ + chapters["Patterns and Actions"]++ + chapters["Arrays"]++ + chapters["Functions"]++ + chapters["Library Functions"]++ + chapters["Sample Programs"]++ + chapters["Advanced Features"]++ + chapters["Internationalization"]++ + chapters["Debugger"]++ + chapters["Arbitrary Precision Arithmetic"]++ + chapters["Dynamic Extensions"]++ + chapters["Language History"]++ + chapters["Installation"]++ + chapters["Notes"]++ + chapters["Basic Concepts"]++ + + Pattern = ".*@ref\\{([^}]+)\\},.*" +} + +$0 ~ Pattern { + ref = gensub(Pattern, "\\1", 1, $0) + if (! (ref in chapters)) + printf("%s:%d: %s\n", FILENAME, FNR, $0) +} + diff --git a/interpret.h b/interpret.h index c26a9d46..23ce0c1a 100644 --- a/interpret.h +++ b/interpret.h @@ -1038,10 +1038,44 @@ match_re: f = lookup(t1->stptr); } - if (f == NULL || f->type != Node_func) { - if (f->type == Node_ext_func || f->type == Node_old_ext_func) - fatal(_("cannot (yet) call extension functions indirectly")); - else + if (f == NULL) { + fatal(_("`%s' is not a function, so it cannot be called indirectly"), + t1->stptr); + } else if (f->type == Node_builtin_func) { + int arg_count = (pc + 1)->expr_count; + builtin_func_t the_func = lookup_builtin(t1->stptr); + + assert(the_func != NULL); + + /* call it */ + r = the_func(arg_count); + PUSH(r); + break; + } else if (f->type != Node_func) { + if ( f->type == Node_ext_func + || f->type == Node_old_ext_func) { + /* code copied from below, keep in sync */ + INSTRUCTION *bc; + char *fname = pc->func_name; + int arg_count = (pc + 1)->expr_count; + static INSTRUCTION npc[2]; + + npc[0] = *pc; + + bc = f->code_ptr; + assert(bc->opcode == Op_symbol); + if (f->type == Node_ext_func) + npc[0].opcode = Op_ext_builtin; /* self modifying code */ + else + npc[0].opcode = Op_old_ext_builtin; /* self modifying code */ + npc[0].extfunc = bc->extfunc; + npc[0].expr_count = arg_count; /* actual argument count */ + npc[1] = pc[1]; + npc[1].func_name = fname; /* name of the builtin */ + npc[1].expr_count = bc->expr_count; /* defined max # of arguments */ + ni = npc; + JUMPTO(ni); + } else fatal(_("function called indirectly through `%s' does not exist"), pc->func_name); } @@ -1065,6 +1099,7 @@ match_re: } if (f->type == Node_ext_func || f->type == Node_old_ext_func) { + /* keep in sync with indirect call code */ INSTRUCTION *bc; char *fname = pc->func_name; int arg_count = (pc + 1)->expr_count; @@ -1355,6 +1390,7 @@ match_re: case Op_K_if: case Op_K_else: case Op_cond_exp: + case Op_comment: break; default: @@ -1550,6 +1550,17 @@ nextrres: * change the string. */ +/* + * 9/2014: Flow here is a little messy. + * + * For do_posix, we don't allow any of the special filenames. + * + * For do_traditional, we allow /dev/{stdin,stdout,stderr} since BWK awk + * (and mawk) support them. But we don't allow /dev/fd/N or /inet. + * + * Note that for POSIX systems os_devopen() is a no-op. + */ + int devopen(const char *name, const char *mode) { @@ -1565,7 +1576,7 @@ devopen(const char *name, const char *mode) flag = str2mode(mode); openfd = INVALID_HANDLE; - if (do_traditional) + if (do_posix) goto strictopen; if ((openfd = os_devopen(name, flag)) != INVALID_HANDLE) { @@ -1582,6 +1593,8 @@ devopen(const char *name, const char *mode) openfd = fileno(stdout); else if (strcmp(cp, "stderr") == 0 && (flag & O_ACCMODE) == O_WRONLY) openfd = fileno(stderr); + else if (do_traditional) + goto strictopen; else if (strncmp(cp, "fd/", 3) == 0) { struct stat sbuf; @@ -1594,6 +1607,8 @@ devopen(const char *name, const char *mode) /* do not set close-on-exec for inherited fd's */ if (openfd != INVALID_HANDLE) return openfd; + } else if (do_traditional) { + goto strictopen; } else if (inetfile(name, & isi)) { #ifdef HAVE_SOCKETS cp = (char *) name; @@ -33,6 +33,16 @@ #include <mcheck.h> #endif +#ifdef HAVE_LIBSIGSEGV +#include <sigsegv.h> +#else +typedef void *stackoverflow_context_t; +/* the argument to this macro is purposely not used */ +#define sigsegv_install_handler(catchsegv) signal(SIGSEGV, catchsig) +/* define as 0 rather than empty so that (void) cast on it works */ +#define stackoverflow_install_handler(catchstackoverflow, extra_stack, STACK_SIZE) 0 +#endif + #define DEFAULT_PROFILE "awkprof.out" /* where to put profile */ #define DEFAULT_VARFILE "awkvars.out" /* where to put vars */ #define DEFAULT_PREC 53 @@ -202,7 +212,7 @@ 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:gh:i:l:L:nNo::Op::MPrStVY"; + 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; @@ -262,17 +272,6 @@ main(int argc, char **argv) */ gawk_mb_cur_max = MB_CUR_MAX; /* Without MBS_SUPPORT, gawk_mb_cur_max is 1. */ -#ifdef LIBC_IS_BORKED -{ - const char *env_lc; - - env_lc = getenv("LC_ALL"); - if (env_lc == NULL) - env_lc = getenv("LANG"); - if (env_lc != NULL && env_lc[1] == '\0' && tolower(env_lc[0]) == 'c') - gawk_mb_cur_max = 1; -} -#endif /* init the cache for checking bytes if they're characters */ init_btowc_cache(); @@ -705,6 +704,8 @@ out: if (do_intl) exit(EXIT_SUCCESS); + install_builtins(); + if (do_lint) shadow_funcs(); @@ -1328,11 +1329,11 @@ arg_assign(char *arg, bool initing) /* first check that the variable name has valid syntax */ badvar = false; - if (! isalpha((unsigned char) arg[0]) && arg[0] != '_') + if (! is_alpha((unsigned char) arg[0]) && arg[0] != '_') badvar = true; else for (cp2 = arg+1; *cp2; cp2++) - if (! isalnum((unsigned char) *cp2) && *cp2 != '_') { + if (! is_identchar((unsigned char) *cp2)) { badvar = true; break; } @@ -72,7 +72,7 @@ r_force_number(NODE *n) * This also allows hexadecimal floating point. Ugh. */ if (! do_posix) { - if (isalpha((unsigned char) *cp)) { + if (is_alpha((unsigned char) *cp)) { return n; } else if (n->stlen == 4 && is_ieee_magic_val(n->stptr)) { if ((n->flags & MAYBE_NUM) != 0) @@ -94,7 +94,7 @@ r_force_number(NODE *n) if ( cp == cpend /* only spaces, or */ || (! do_posix /* not POSIXLY paranoid and */ - && (isalpha((unsigned char) *cp) /* letter, or */ + && (is_alpha((unsigned char) *cp) /* letter, or */ /* CANNOT do non-decimal and saw 0x */ || (! do_non_decimal_data && cp[0] == '0' && (cp[1] == 'x' || cp[1] == 'X'))))) { diff --git a/pc/ChangeLog b/pc/ChangeLog index a66edae9..235f520c 100644 --- a/pc/ChangeLog +++ b/pc/ChangeLog @@ -1,3 +1,7 @@ +2014-09-23 Scott Deifik <scottd.mail@sbcglobal.net> + + * Makefile.tst: Sync with mainline. + 2014-04-17 Scott Deifik <scottd.mail@sbcglobal.net> * Makefile.tst: Add readfile2 test. diff --git a/pc/Makefile.tst b/pc/Makefile.tst index 610704e4..48fc5189 100644 --- a/pc/Makefile.tst +++ b/pc/Makefile.tst @@ -180,19 +180,19 @@ UNIX_TESTS = \ GAWK_EXT_TESTS = \ aadelete1 aadelete2 aarray1 aasort aasorti argtest arraysort \ backw badargs beginfile1 beginfile2 binmode1 charasbytes \ - colonwarn clos1way delsub devfd devfd1 devfd2 dumpvars exit \ + 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 \ icasefs icasers id igncdym igncfs ignrcas2 ignrcase \ incdupe incdupe2 incdupe3 incdupe4 incdupe5 incdupe6 incdupe7 \ - include include2 indirectcall \ + include include2 indirectcall indirectcall2 \ lint lintold lintwarn \ manyfiles match1 match2 match3 mbstr1 \ nastyparm next nondec nondec2 \ - patsplit posix printfbad1 printfbad2 printfbad3 procinfs \ + patsplit posix printfbad1 printfbad2 printfbad3 printhuge procinfs \ profile1 profile2 profile3 profile4 profile5 pty1 \ - rebuf regx8bit reginttrad reint reint2 rsstart1 \ + rebuf regnul1 regnul2 regx8bit reginttrad reint reint2 rsgetline rsglstdin rsstart1 \ rsstart2 rsstart3 rstest6 shadow sortfor sortu split_after_fpat \ splitarg4 strftime \ strtonum switch2 symtab1 symtab2 symtab3 symtab4 symtab5 symtab6 \ @@ -201,8 +201,9 @@ GAWK_EXT_TESTS = \ EXTRA_TESTS = inftest regtest INET_TESTS = inetdayu inetdayt inetechu inetecht MACHINE_TESTS = double1 double2 fmtspcl intformat -MPFR_TESTS = mpfrnr mpfrnegzero mpfrrnd mpfrieee mpfrexprange \ - mpfrsort mpfrbigint +MPFR_TESTS = mpfrnr mpfrnegzero mpfrrem mpfrrnd mpfrieee mpfrexprange \ + mpfrsort mpfrsqrt mpfrbigint + LOCALE_CHARSET_TESTS = \ asort asorti backbigs1 backsmalls1 backsmalls2 \ fmttest fnarydel fnparydl jarebug lc_num1 mbfw1 \ @@ -318,6 +319,10 @@ machine-msg-end: charset-msg-start: @echo "======== Starting tests that can vary based on character set or locale support ========" + @echo "************************************************" + @echo "** Some or all of these tests may fail if you **" + @echo "** have inadequate or missing locale support **" + @echo "************************************************" charset-msg-end: @echo "======== Done with tests that can vary based on character set or locale support ========" @@ -352,7 +357,7 @@ poundbang:: @if ./_pbd.awk "$(srcdir)"/poundbang.awk > _`basename $@` ; \ then : ; \ else \ - sed "s;/tmp/gawk;../$(AWKPROG);" < "$(srcdir)"/poundbang.awk > ./_pbd.awk ; \ + sed "s;/tmp/gawk;$(AWKPROG);" < "$(srcdir)"/poundbang.awk > ./_pbd.awk ; \ chmod +x ./_pbd.awk ; \ LC_ALL=$${GAWKLOCALE:-C} LANG=$${GAWKLOCALE:-C} ./_pbd.awk "$(srcdir)"/poundbang.awk > _`basename $@`; \ fi @@ -503,6 +508,16 @@ fmtspcl: fmtspcl.ok $(CMP) "$(srcdir)"/$@-mpfr.ok _$@ && rm -f _$@ ; \ fi +rebuf:: + @echo $@ + @AWKBUFSIZE=4096 AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + +rsglstdin:: + @echo $@ + @cat "$(srcdir)"/rsgetline.in | AWKPATH="$(srcdir)" $(AWK) -f rsgetline.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + reint:: @echo $@ @$(AWK) --re-interval -f "$(srcdir)"/reint.awk "$(srcdir)"/reint.in >_$@ @@ -932,6 +947,16 @@ mpfrbigint: @$(AWK) -M -f "$(srcdir)"/$@.awk > _$@ 2>&1 @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +mpfrsqrt: + @echo $@ + @$(AWK) -M -f "$(srcdir)"/$@.awk > _$@ 2>&1 + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + +mpfrrem: + @echo $@ + @$(AWK) -M -f "$(srcdir)"/$@.awk > _$@ 2>&1 + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + jarebug:: @echo $@ @echo Expect jarebug to fail with DJGPP and MinGW. @@ -1135,6 +1160,22 @@ backsmalls2: @[ -z "$$GAWKLOCALE" ] && GAWKLOCALE=en_US.UTF-8; \ AWKPATH="$(srcdir)" $(AWK) -f $@.awk "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + +dbugeval:: + @echo $@ + @$(AWK) --debug -f /dev/null < "$(srcdir)"/$@.in > _$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + +printhuge:: + @echo $@ + @[ -z "$$GAWKLOCALE" ] && GAWKLOCALE=en_US.UTF-8; \ + AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + +filefuncs: + @echo $@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk -v builddir="$(abs_top_builddir)" >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ Gt-dummy: # file Maketests, generated from Makefile.am by the Gentests program addcomma: @@ -2227,6 +2268,11 @@ indirectcall: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +indirectcall2: + @echo $@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + lint: @echo $@ @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @@ -2299,9 +2345,14 @@ pty1: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ -rebuf: +regnul1: @echo $@ - @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + +regnul2: + @echo $@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ regx8bit: @@ -2309,6 +2360,11 @@ regx8bit: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +rsgetline: + @echo $@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + rstest6: @echo $@ @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @@ -2445,11 +2501,6 @@ fnmatch: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ -filefuncs: - @echo $@ - @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ - @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ - fork: @echo $@ @echo Expect $@ to fail with MinGW because fork.dll is not available diff --git a/pc/config.h b/pc/config.h index c5d78a96..a6b2d4c4 100644 --- a/pc/config.h +++ b/pc/config.h @@ -242,6 +242,9 @@ #define HAVE_STDLIB_H 1 #endif +/* Define to 1 if you have the `strcasecmp' function. */ +#undef HAVE_STRCASECMP + /* Define to 1 if you have the `strchr' function. */ #define HAVE_STRCHR 1 @@ -407,6 +410,9 @@ /* Define to 1 if the system has the type `_Bool'. */ #undef HAVE__BOOL +/* enable severe portability problems */ +#undef I_DONT_KNOW_WHAT_IM_DOING + /* libc is broken for regex handling */ #undef LIBC_IS_BORKED @@ -1,17 +1,18 @@ # Swedish translation of gawk # Copyright © 2003, 2011, 2012, 2013, 2014 Free Software Foundation, Inc. # This file is distributed under the same license as the gawk package. +# # Martin Sjögren <md9ms@mdstud.chalmers.se>, 2001-2002. # Christer Andersson <klamm@comhem.se>, 2007. # Göran Uddeborg <goeran@uddeborg.se>, 2011, 2012, 2013, 2014. # -# $Revision: 1.14 $ +# $Revision: 1.15 $ msgid "" msgstr "" "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: 2014-01-21 17:40+0100\n" +"PO-Revision-Date: 2014-09-22 09:12+0200\n" "Last-Translator: Göran Uddeborg <goeran@uddeborg.se>\n" "Language-Team: Swedish <tp-sv@listor.tp-sv.se>\n" "Language: sv\n" @@ -690,7 +691,7 @@ msgstr "^ tog slut här" #: builtin.c:1575 msgid "[s]printf: format specifier does not have control letter" -msgstr "[s]printf: formatspecifieraren har ingen kommandobokstav" +msgstr "[s]printf: formatspecificeraren har ingen kommandobokstav" #: builtin.c:1578 msgid "too many arguments supplied for format string" @@ -770,7 +771,7 @@ msgstr "strftime: fick ett ickenumeriskt andra argument" #: builtin.c:1927 msgid "strftime: second argument less than 0 or too big for time_t" -msgstr "strftime: andra argimentet mindre än 0 eller för stort för time_t" +msgstr "strftime: andra argumentet mindre än 0 eller för stort för time_t" #: builtin.c:1934 msgid "strftime: received non-string first argument" @@ -899,7 +900,7 @@ msgstr "and: argument %d med negativt värde %g kommer ge konstiga resultat" #: builtin.c:3136 mpfr.c:1000 msgid "or: called with less than two arguments" -msgstr "or: anropad med färre än två argmuent" +msgstr "or: anropad med färre än två argument" #: builtin.c:3141 #, c-format @@ -1087,7 +1088,7 @@ msgstr "delete [brytpunkter] [intervall] - radera angivna brytpunkter." #: command.y:831 msgid "disable [breakpoints] [range] - disable specified breakpoints." -msgstr "disable [brytpunkger] [intervall] - avaktivera angivna brytpunkter." +msgstr "disable [brytpunkter] [intervall] - avaktivera angivna brytpunkter." #: command.y:833 msgid "display [var] - print value of variable each time the program stops." @@ -1277,7 +1278,7 @@ msgstr "odefinierat kommando: %s\n" #: debug.c:252 msgid "set or show the number of lines to keep in history file." -msgstr "sätt eller visa antalet rader att behålla i historiefilen." +msgstr "sätt eller visa antalet rader att behålla i historikfilen." #: debug.c:254 msgid "set or show the list command window size." @@ -1293,7 +1294,7 @@ msgstr "sätt eller visa felsökningsprompten." #: debug.c:260 msgid "(un)set or show saving of command history (value=on|off)." -msgstr "slå av/på eller visa sparandet av kommandohisterik (värde=on|off)." +msgstr "slå av/på eller visa sparandet av kommandohistorik (värde=on|off)." #: debug.c:262 msgid "(un)set or show saving of options (value=on|off)." @@ -1561,7 +1562,7 @@ msgstr "Ogiltigt ramnummer" #, c-format msgid "Note: breakpoint %d (enabled, ignore next %ld hits), also set at %s:%d" msgstr "" -"Observera: brytpunkt %d (aktiverad, ingorera följande %ld träffar), är också " +"Observera: brytpunkt %d (aktiverad, ignorera följande %ld träffar), är också " "satt vid %s:%d" #: debug.c:2207 @@ -1604,7 +1605,7 @@ msgstr "Kan inte hitta regeln!!!\n" #: debug.c:2375 #, c-format msgid "Can't set breakpoint at `%s':%d\n" -msgstr "Kan inte sätta än brytpunkt vid ”%s”:%d\n" +msgstr "Kan inte sätta en brytpunkt vid ”%s”:%d\n" #: debug.c:2387 #, c-format @@ -1680,7 +1681,7 @@ msgstr "fel: kan inte starta om, åtgärden är inte tillåten\n" #: debug.c:2942 #, c-format msgid "error (%s): cannot restart, ignoring rest of the commands\n" -msgstr "fel (%s): kan inte starta om, ingorerar resten av kommandona\n" +msgstr "fel (%s): kan inte starta om, ignorerar resten av kommandona\n" #: debug.c:2950 #, c-format @@ -2824,11 +2825,11 @@ msgstr "flyttande av rör till standard in i barnet misslyckades (dup: %s)" #: io.c:2073 io.c:2298 msgid "restoring stdout in parent process failed\n" -msgstr "återställande av standard ut i förälderprocessen misslyckades\n" +msgstr "återställande av standard ut i föräldraprocessen misslyckades\n" #: io.c:2081 msgid "restoring stdin in parent process failed\n" -msgstr "återställande av standard in i förälderprocessen misslyckades\n" +msgstr "återställande av standard in i föräldraprocessen misslyckades\n" #: io.c:2116 io.c:2310 io.c:2324 #, c-format @@ -2880,7 +2881,7 @@ msgstr "" #: io.c:2880 #, c-format msgid "output wrapper `%s' failed to open `%s'" -msgstr "utmatningsomslag ”%s” misslyckades att öpnna ”%s”" +msgstr "utmatningsomslag ”%s” misslyckades att öppna ”%s”" #: io.c:2901 msgid "register_output_processor: received NULL pointer" @@ -3180,7 +3181,7 @@ msgid "" "along with this program. If not, see http://www.gnu.org/licenses/.\n" msgstr "" "Du bör ha fått en kopia av GNU General Public License tillsammans\n" -"med detta program. Om inte, se http//www.gnu.org/liceences/.\n" +"med detta program. Om inte, se http://www.gnu.org/licenses/.\n" #: main.c:931 msgid "-Ft does not set FS to tab in POSIX awk" @@ -36,7 +36,8 @@ static bool is_scalar(int type); static int prec_level(int type); static void pp_push(int type, char *s, int flag); static NODE *pp_pop(void); -static void pp_free(NODE *n); +static void pprint(INSTRUCTION *startp, INSTRUCTION *endp, bool in_for_header); +static void print_comment(INSTRUCTION *pc, long in); const char *redir2str(int redirtype); #define pp_str vname @@ -100,10 +101,12 @@ indent(long count) { int i; - if (count == 0) - fprintf(prof_fp, "\t"); - else - fprintf(prof_fp, "%6ld ", count); + if (do_profile) { + if (count == 0) + fprintf(prof_fp, "\t"); + else + fprintf(prof_fp, "%6ld ", count); + } assert(indent_level >= 0); for (i = 0; i < indent_level; i++) @@ -177,6 +180,7 @@ pprint(INSTRUCTION *startp, INSTRUCTION *endp, bool in_for_header) NODE *m; char *tmp; int rule; + long lind; static int rule_count[MAXRULE]; for (pc = startp; pc != endp; pc = pc->nexti) { @@ -189,16 +193,35 @@ pprint(INSTRUCTION *startp, INSTRUCTION *endp, bool in_for_header) rule = pc->in_rule; if (rule != Rule) { - if (! rule_count[rule]++) - fprintf(prof_fp, _("\t# %s block(s)\n\n"), ruletab[rule]); - fprintf(prof_fp, "\t%s {\n", ruletab[rule]); ip = (pc + 1)->firsti; + + /* print pre-begin/end comments */ + if (ip->opcode == Op_comment) { + print_comment(ip, 0); + ip = ip->nexti; + } + + 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]); } else { - if (! rule_count[rule]++) + if (do_profile && ! rule_count[rule]++) fprintf(prof_fp, _("\t# Rule(s)\n\n")); ip = pc->nexti; - indent(ip->exec_count); + 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); @@ -218,7 +241,9 @@ pprint(INSTRUCTION *startp, INSTRUCTION *endp, bool in_for_header) indent_in(); pprint(ip, (pc + 1)->lasti, false); indent_out(); - fprintf(prof_fp, "\t}\n\n"); + if (do_profile) + indent(0); + fprintf(prof_fp, "}\n\n"); pc = (pc + 1)->lasti; break; @@ -731,20 +756,28 @@ cleanup: ip = pc + 1; indent(ip->forloop_body->exec_count); fprintf(prof_fp, "%s (", op2str(pc->opcode)); - pprint(pc->nexti, ip->forloop_cond, true); - fprintf(prof_fp, "; "); - if (ip->forloop_cond->opcode == Op_no_op && - ip->forloop_cond->nexti == ip->forloop_body) + /* If empty for looop header, print it a little more nicely. */ + if ( pc->nexti->opcode == Op_no_op + && ip->forloop_cond == pc->nexti + && pc->target_continue->opcode == Op_jmp) { + fprintf(prof_fp, ";;"); + } else { + pprint(pc->nexti, ip->forloop_cond, true); fprintf(prof_fp, "; "); - else { - pprint(ip->forloop_cond, ip->forloop_body, true); - t1 = pp_pop(); - fprintf(prof_fp, "%s; ", t1->pp_str); - pp_free(t1); - } - pprint(pc->target_continue, pc->target_break, true); + if (ip->forloop_cond->opcode == Op_no_op && + ip->forloop_cond->nexti == ip->forloop_body) + fprintf(prof_fp, "; "); + else { + pprint(ip->forloop_cond, ip->forloop_body, true); + t1 = pp_pop(); + fprintf(prof_fp, "%s; ", t1->pp_str); + pp_free(t1); + } + + pprint(pc->target_continue, pc->target_break, true); + } fprintf(prof_fp, ") {\n"); indent_in(); pprint(ip->forloop_body->nexti, pc->target_continue, false); @@ -873,6 +906,13 @@ cleanup: indent(pc->exec_count); break; + case Op_comment: + print_comment(pc, 0); + break; + + case Op_list: + break; + default: cant_happen(); } @@ -901,11 +941,11 @@ pp_string_fp(Func_print print_func, FILE *fp, const char *in_str, slen = strlen(str); for (count = 0; slen > 0; slen--, str++) { + print_func(fp, "%c", *str); if (++count >= BREAKPOINT && breaklines) { print_func(fp, "%c\n%c", delim, delim); count = 0; - } else - print_func(fp, "%c", *str); + } } efree(s); } @@ -955,6 +995,30 @@ print_lib_list(FILE *prof_fp) fprintf(prof_fp, "\n"); } +/* print_comment --- print comment text with proper indentation */ + +static void +print_comment(INSTRUCTION* pc, long in) +{ + char *text; + size_t count; + bool after_newline = false; + + count = pc->memory->stlen; + text = pc->memory->stptr; + + indent(in); /* is this correct? Where should comments go? */ + for (; count > 0; count--, text++) { + if (after_newline) { + indent(in); + after_newline = false; + } + putc(*text, prof_fp); + if (*text == '\n') + after_newline = true; + } +} + /* dump_prog --- dump the program */ /* @@ -969,7 +1033,8 @@ dump_prog(INSTRUCTION *code) (void) time(& now); /* \n on purpose, with \n in ctime() output */ - fprintf(prof_fp, _("\t# gawk profile, created %s\n"), ctime(& now)); + if (do_profile) + fprintf(prof_fp, _("\t# gawk profile, created %s\n"), ctime(& now)); print_lib_list(prof_fp); pprint(code, NULL, false); } @@ -1469,14 +1534,24 @@ pp_func(INSTRUCTION *pc, void *data ATTRIBUTE_UNUSED) static bool first = true; NODE *func; int pcount; + INSTRUCTION *fp; if (first) { first = false; - fprintf(prof_fp, _("\n\t# Functions, listed alphabetically\n")); + if (do_profile) + fprintf(prof_fp, _("\n\t# Functions, listed alphabetically\n")); } + fp = pc->nexti->nexti; func = pc->func_body; fprintf(prof_fp, "\n"); + + /* print any function comment */ + if (fp->opcode == Op_comment && fp->source_line == 0) { + print_comment(fp, 0); + fp = fp->nexti; + } + indent(pc->nexti->exec_count); fprintf(prof_fp, "%s %s(", op2str(Op_K_function), func->vname); pcount = func->param_cnt; @@ -1486,11 +1561,16 @@ pp_func(INSTRUCTION *pc, void *data ATTRIBUTE_UNUSED) if (j < pcount - 1) fprintf(prof_fp, ", "); } - fprintf(prof_fp, ")\n\t{\n"); + fprintf(prof_fp, ")\n"); + if (do_profile) + indent(0); + fprintf(prof_fp, "{\n"); indent_in(); - pprint(pc->nexti->nexti, NULL, false); /* function body */ + pprint(fp, NULL, false); /* function body */ indent_out(); - fprintf(prof_fp, "\t}\n"); + if (do_profile) + indent(0); + fprintf(prof_fp, "}\n"); return 0; } @@ -149,7 +149,7 @@ const char __re_error_msgid[] attribute_hidden = gettext_noop ("Invalid back reference") /* REG_ESUBREG */ "\0" #define REG_EBRACK_IDX (REG_ESUBREG_IDX + sizeof "Invalid back reference") - gettext_noop ("Unmatched [ or [^") /* REG_EBRACK */ + gettext_noop ("Unmatched [, [^, [:, [., or [=") /* REG_EBRACK */ "\0" #define REG_EPAREN_IDX (REG_EBRACK_IDX + sizeof "Unmatched [ or [^") gettext_noop ("Unmatched ( or \\(") /* REG_EPAREN */ @@ -856,10 +856,6 @@ init_dfa (re_dfa_t *dfa, size_t pat_len) #ifndef _LIBC char *codeset_name; #endif -#if defined(GAWK) && defined(LIBC_IS_BORKED) - /* Needed for brain damaged systems */ - extern int gawk_mb_cur_max; -#endif memset (dfa, '\0', sizeof (re_dfa_t)); @@ -881,11 +877,7 @@ init_dfa (re_dfa_t *dfa, size_t pat_len) dfa->state_table = calloc (sizeof (struct re_state_table_entry), table_size); dfa->state_hash_mask = table_size - 1; -#if defined(GAWK) && defined(LIBC_IS_BORKED) - dfa->mb_cur_max = gawk_mb_cur_max; -#else dfa->mb_cur_max = MB_CUR_MAX; -#endif #ifdef _LIBC if (dfa->mb_cur_max == 6 && strcmp (_NL_CURRENT (LC_CTYPE, _NL_CTYPE_CODESET_NAME), "UTF-8") == 0) @@ -907,24 +899,9 @@ init_dfa (re_dfa_t *dfa, size_t pat_len) codeset_name = strchr (codeset_name, '.') + 1; # endif - /* strcasecmp isn't a standard interface. brute force check */ -#ifndef GAWK if (strcasecmp (codeset_name, "UTF-8") == 0 || strcasecmp (codeset_name, "UTF8") == 0) dfa->is_utf8 = 1; -#else - if ( (codeset_name[0] == 'U' || codeset_name[0] == 'u') - && (codeset_name[1] == 'T' || codeset_name[1] == 't') - && (codeset_name[2] == 'F' || codeset_name[2] == 'f') - && (codeset_name[3] == '-' - ? codeset_name[4] == '8' && codeset_name[5] == '\0' - : codeset_name[3] == '8' && codeset_name[4] == '\0')) - dfa->is_utf8 = 1; -#if defined(GAWK) && defined(LIBC_IS_BORKED) - if (gawk_mb_cur_max == 1) - dfa->is_utf8 = 0; -#endif /* defined(GAWK) && defined(LIBC_IS_BORKED) */ -#endif /* We check exhaustively in the loop below if this charset is a superset of ASCII. */ @@ -2215,7 +2192,11 @@ parse_reg_exp (re_string_t *regexp, regex_t *preg, re_token_t *token, { branch = parse_branch (regexp, preg, token, syntax, nest, err); if (BE (*err != REG_NOERROR && branch == NULL, 0)) - return NULL; + { + if (tree != NULL) + postorder (tree, free_tree, NULL); + return NULL; + } } else branch = NULL; @@ -2476,8 +2457,7 @@ parse_expression (re_string_t *regexp, regex_t *preg, re_token_t *token, while (token->type == OP_DUP_ASTERISK || token->type == OP_DUP_PLUS || token->type == OP_DUP_QUESTION || token->type == OP_OPEN_DUP_NUM) { - bin_tree_t *dup_tree = parse_dup_op (tree, regexp, dfa, token, - syntax, err); + bin_tree_t *dup_tree = parse_dup_op (tree, regexp, dfa, token, syntax, err); if (BE (*err != REG_NOERROR && dup_tree == NULL, 0)) { if (tree != NULL) @@ -2640,6 +2620,8 @@ parse_dup_op (bin_tree_t *elem, re_string_t *regexp, re_dfa_t *dfa, /* Duplicate ELEM before it is marked optional. */ elem = duplicate_tree (elem, dfa); + if (BE (elem == NULL, 0)) + goto parse_dup_op_espace; old_tree = tree; } else @@ -3136,8 +3118,8 @@ parse_bracket_exp (re_string_t *regexp, re_dfa_t *dfa, re_token_t *token, if (BE (sbcset == NULL, 0)) #endif /* RE_ENABLE_I18N */ { -#ifdef RE_ENABLE_I18N re_free (sbcset); +#ifdef RE_ENABLE_I18N re_free (mbcset); #endif *err = REG_ESPACE; @@ -470,7 +470,7 @@ typedef struct #ifdef __USE_GNU /* Sets the current default syntax to SYNTAX, and return the old syntax. You can also simply assign to the `re_syntax_options' variable. */ -extern reg_syntax_t re_set_syntax (reg_syntax_t __syntax); +extern reg_syntax_t re_set_syntax (reg_syntax_t syntax); /* Compile the regular expression PATTERN, with length LENGTH and syntax given by the global `re_syntax_options', into the buffer @@ -480,14 +480,14 @@ extern reg_syntax_t re_set_syntax (reg_syntax_t __syntax); Note that the translate table must either have been initialised by `regcomp', with a malloc'ed value, or set to NULL before calling `regfree'. */ -extern const char *re_compile_pattern (const char *__pattern, size_t __length, - struct re_pattern_buffer *__buffer); +extern const char *re_compile_pattern (const char *pattern, size_t length, + struct re_pattern_buffer *buffer); /* Compile a fastmap for the compiled pattern in BUFFER; used to accelerate searches. Return 0 if successful and -2 if was an internal error. */ -extern int re_compile_fastmap (struct re_pattern_buffer *__buffer); +extern int re_compile_fastmap (struct re_pattern_buffer *buffer); /* Search in the string STRING (with length LENGTH) for the pattern @@ -495,30 +495,30 @@ extern int re_compile_fastmap (struct re_pattern_buffer *__buffer); characters. Return the starting position of the match, -1 for no match, or -2 for an internal error. Also return register information in REGS (if REGS and BUFFER->no_sub are nonzero). */ -extern int re_search (struct re_pattern_buffer *__buffer, const char *__cstring, - int __length, int __start, int __range, - struct re_registers *__regs); +extern int re_search (struct re_pattern_buffer *buffer, const char *c_string, + int length, int start, int range, + struct re_registers *regs); /* Like `re_search', but search in the concatenation of STRING1 and STRING2. Also, stop searching at index START + STOP. */ -extern int re_search_2 (struct re_pattern_buffer *__buffer, - const char *__string1, int __length1, - const char *__string2, int __length2, int __start, - int __range, struct re_registers *__regs, int __stop); +extern int re_search_2 (struct re_pattern_buffer *buffer, + const char *string1, int length1, + const char *string2, int length2, int start, + int range, struct re_registers *regs, int stop); /* Like `re_search', but return how many characters in STRING the regexp in BUFFER matched, starting at position START. */ -extern int re_match (struct re_pattern_buffer *__buffer, const char *__cstring, - int __length, int __start, struct re_registers *__regs); +extern int re_match (struct re_pattern_buffer *buffer, const char *c_string, + int length, int start, struct re_registers *regs); /* Relates to `re_match' as `re_search_2' relates to `re_search'. */ -extern int re_match_2 (struct re_pattern_buffer *__buffer, - const char *__string1, int __length1, - const char *__string2, int __length2, int __start, - struct re_registers *__regs, int __stop); +extern int re_match_2 (struct re_pattern_buffer *buffer, + const char *string1, int length1, + const char *string2, int length2, int start, + struct re_registers *regs, int stop); /* Set REGS to hold NUM_REGS registers, storing them in STARTS and @@ -533,10 +533,10 @@ extern int re_match_2 (struct re_pattern_buffer *__buffer, Unless this function is called, the first search or match using PATTERN_BUFFER will allocate its own register data, without freeing the old data. */ -extern void re_set_registers (struct re_pattern_buffer *__buffer, - struct re_registers *__regs, - unsigned int __num_regs, - regoff_t *__starts, regoff_t *__ends); +extern void re_set_registers (struct re_pattern_buffer *buffer, + struct re_registers *regs, + unsigned int num_regs, + regoff_t *starts, regoff_t *ends); #endif /* Use GNU */ #if defined _REGEX_RE_COMP || (defined _LIBC && defined __USE_MISC) @@ -569,19 +569,19 @@ extern int re_exec (const char *); #endif /* POSIX compatibility. */ -extern int regcomp (regex_t *__restrict __preg, - const char *__restrict __pattern, - int __cflags); +extern int regcomp (regex_t *__restrict preg, + const char *__restrict pattern, + int cflags); -extern int regexec (const regex_t *__restrict __preg, - const char *__restrict __cstring, size_t __nmatch, - regmatch_t __pmatch[__restrict_arr], - int __eflags); +extern int regexec (const regex_t *__restrict preg, + const char *__restrict c_string, size_t nmatch, + regmatch_t pmatch[__restrict_arr], + int eflags); -extern size_t regerror (int __errcode, const regex_t *__restrict __preg, - char *__restrict __errbuf, size_t __errbuf_size); +extern size_t regerror (int errcode, const regex_t *__restrict preg, + char *__restrict errbuf, size_t errbuf_size); -extern void regfree (regex_t *__preg); +extern void regfree (regex_t *preg); #ifdef __cplusplus diff --git a/regex_internal.c b/regex_internal.c index 056cff3d..9e427081 100644 --- a/regex_internal.c +++ b/regex_internal.c @@ -545,7 +545,10 @@ build_upper_buffer (re_string_t *pstr) int ch = pstr->raw_mbs[pstr->raw_mbs_idx + char_idx]; if (BE (pstr->trans != NULL, 0)) ch = pstr->trans[ch]; - pstr->mbs[char_idx] = toupper (ch); + if (islower (ch)) + pstr->mbs[char_idx] = toupper (ch); + else + pstr->mbs[char_idx] = ch; } pstr->valid_len = char_idx; pstr->valid_raw_len = char_idx; @@ -683,7 +686,7 @@ re_string_reconstruct (re_string_t *pstr, int idx, int eflags) pstr->valid_len - offset); pstr->valid_len -= offset; pstr->valid_raw_len -= offset; -#if DEBUG +#if defined DEBUG && DEBUG assert (pstr->valid_len > 0); #endif } @@ -940,7 +943,7 @@ re_string_context_at (const re_string_t *input, int idx, int eflags) int wc_idx = idx; while(input->wcs[wc_idx] == WEOF) { -#ifdef DEBUG +#if defined DEBUG && DEBUG /* It must not happen. */ assert (wc_idx >= 0); #endif @@ -50,7 +50,7 @@ #include "missing_d/memmove.c" #endif /* HAVE_MEMMOVE */ -#ifndef HAVE_STRNCASECMP +#if !defined(HAVE_STRNCASECMP) || !defined(HAVE_STRCASECMP) #include "missing_d/strncasecmp.c" #endif /* HAVE_STRCASE */ @@ -35,8 +35,8 @@ static int var_count; /* total number of global variables and functions */ static NODE *symbol_list; static void (*install_func)(NODE *) = NULL; -static NODE *make_symbol(char *name, NODETYPE type); -static NODE *install(char *name, NODE *parm, NODETYPE type); +static NODE *make_symbol(const char *name, NODETYPE type); +static NODE *install(const char *name, NODE *parm, NODETYPE type); static void free_bcpool(INSTRUCTION *pl); static AWK_CONTEXT *curr_ctxt = NULL; @@ -75,7 +75,7 @@ init_symbol_table() */ NODE * -install_symbol(char *name, NODETYPE type) +install_symbol(const char *name, NODETYPE type) { return install(name, NULL, type); } @@ -275,7 +275,7 @@ destroy_symbol(NODE *r) /* make_symbol --- allocates a global symbol for the symbol table. */ static NODE * -make_symbol(char *name, NODETYPE type) +make_symbol(const char *name, NODETYPE type) { NODE *r; @@ -285,7 +285,7 @@ make_symbol(char *name, NODETYPE type) null_array(r); else if (type == Node_var) r->var_value = dupnode(Nnull_string); - r->vname = name; + r->vname = (char *) name; r->type = type; return r; @@ -294,7 +294,7 @@ make_symbol(char *name, NODETYPE type) /* install --- install a global name or function parameter in the symbol table */ static NODE * -install(char *name, NODE *parm, NODETYPE type) +install(const char *name, NODE *parm, NODETYPE type) { NODE *r; NODE **aptr; @@ -307,7 +307,9 @@ install(char *name, NODE *parm, NODETYPE type) if (type == Node_param_list) { table = param_table; - } else if (type == Node_func || type == Node_ext_func) { + } else if ( type == Node_func + || type == Node_ext_func + || type == Node_builtin_func) { table = func_table; } else if (installing_specials) { table = global_table; @@ -320,7 +322,7 @@ install(char *name, NODE *parm, NODETYPE type) r = make_symbol(name, type); if (type == Node_func) func_count++; - if (type != Node_ext_func && table != global_table) + if (type != Node_ext_func && type != Node_builtin_func && table != global_table) var_count++; /* total, includes Node_func */ } @@ -393,7 +395,7 @@ get_symbols(SYMBOL_TYPE what, bool sort) for (i = count = 0; i < max; i += 2) { r = list[i+1]; - if (r->type == Node_ext_func) + if (r->type == Node_ext_func || r->type == Node_builtin_func) continue; assert(r->type == Node_func); table[count++] = r; @@ -539,7 +541,7 @@ load_symbols() NODE *sym_array; NODE **aptr; long i, j, max; - NODE *user, *extension, *untyped, *scalar, *array; + NODE *user, *extension, *untyped, *scalar, *array, *built_in; NODE **list; NODE *tables[4]; @@ -570,6 +572,7 @@ load_symbols() scalar = make_string("scalar", 6); untyped = make_string("untyped", 7); array = make_string("array", 5); + built_in = make_string("builtin", 7); for (i = 0; tables[i] != NULL; i++) { list = assoc_list(tables[i], "@unsorted", ASORTI); @@ -580,6 +583,7 @@ load_symbols() r = list[j+1]; if ( r->type == Node_ext_func || r->type == Node_func + || r->type == Node_builtin_func || r->type == Node_var || r->type == Node_var_array || r->type == Node_var_new) { @@ -594,6 +598,9 @@ load_symbols() case Node_func: *aptr = dupnode(user); break; + case Node_builtin_func: + *aptr = dupnode(built_in); + break; case Node_var: *aptr = dupnode(scalar); break; diff --git a/test/ChangeLog b/test/ChangeLog index 8f8c9c31..aa0ddcbe 100644 --- a/test/ChangeLog +++ b/test/ChangeLog @@ -1,3 +1,59 @@ +2014-10-12 Arnold D. Robbins <arnold@skeeve.com> + + * Makefile.am (charset-msg-start): Add a list of needed locales. + Suggested by Shaun Jackman <sjackman@gmail.com>. + +2014-10-05 Arnold D. Robbins <arnold@skeeve.com> + + * profile2.ok, profile3.ok, profile4.ok, profile5.ok: + Adjusted after minor code change. Again. + +2014-10-04 Arnold D. Robbins <arnold@skeeve.com> + + * Makefile.am (genpot): New test. + * genpot.awk, genpot.ok: New files. + +2014-09-29 Arnold D. Robbins <arnold@skeeve.com> + + * testext.ok: Adjusted after minor code change. + +2014-09-27 Arnold D. Robbins <arnold@skeeve.com> + + * profile2.ok, profile3.ok, profile4.ok, profile5.ok: + Adjusted after minor code change. + +2014-09-18 Arnold D. Robbins <arnold@skeeve.com> + + * filefuncs.awk: Change to build directory instead of "..". + * Makefile.am (filefuncs): Pass in $(abs_top_builddir). + +2014-09-13 Stephen Davies <sdavies@sdc.com.au> + + * Makefile.am (profile4, profile5): Changes processing to not delete + the first two lines. This is no longer needed. + * profile4.ok, profile5.ok: Changed to suit new rules and comments. + +2014-09-10 Arnold D. Robbins <arnold@skeeve.com> + + * profile2.ok, profile4.ok, profile5.ok: Update for new code. + +2014-09-05 Arnold D. Robbins <arnold@skeeve.com> + + * functab4.awk: Changed to use stat instead of chdir since + /tmp isn't /tmp on all systems (e.g. Mac OS X). Thanks to + Hermann Peifer for the report. + + Sort of related: + + * indirectcall2.awk, indirectcall2.ok: New files. + * id.ok: Updated. + +2014-09-04 Arnold D. Robbins <arnold@skeeve.com> + + * profile2.ok: Update after code improvement in profiler. + * functab4.ok: Update after making indirect calls of + extension functions work. :-) + 2014-08-15 Arnold D. Robbins <arnold@skeeve.com> * badargs.ok: Adjust after revising text for -L option. @@ -270,6 +326,10 @@ in locations with spaces in their names (think Windows or Mac OS X). * Gentests: Ditto for when creating Maketests file. +2013-07-30 Arnold D. Robbins <arnold@skeeve.com> + + * profile2.ok, profile5.ok: Update. + 2013-07-04 Arnold D. Robbins <arnold@skeeve.com> * Makefile.am (mbprintf4): New test. diff --git a/test/Makefile.am b/test/Makefile.am index f28b381e..81548186 100644 --- a/test/Makefile.am +++ b/test/Makefile.am @@ -324,6 +324,8 @@ EXTRA_DIST = \ fwtest3.awk \ fwtest3.in \ fwtest3.ok \ + genpot.awk \ + genpot.ok \ gensub.awk \ gensub.in \ gensub.ok \ @@ -421,6 +423,8 @@ EXTRA_DIST = \ indirectcall.awk \ indirectcall.in \ indirectcall.ok \ + indirectcall2.awk \ + indirectcall2.ok \ inftest.awk \ inftest.ok \ inplace.in \ @@ -1007,10 +1011,10 @@ 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 \ + include include2 indirectcall indirectcall2 \ lint lintold lintwarn \ manyfiles match1 match2 match3 mbstr1 \ nastyparm next nondec nondec2 \ @@ -1164,6 +1168,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: @@ -1686,14 +1692,12 @@ profile3: profile4: @echo $@ - @$(AWK) --pretty-print=ap-$@.out -f "$(srcdir)"/$@.awk > /dev/null - @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @$(AWK) --pretty-print=_$@ -f "$(srcdir)"/$@.awk > /dev/null @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ profile5: @echo $@ - @$(AWK) --pretty-print=ap-$@.out -f "$(srcdir)"/$@.awk > /dev/null - @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @$(AWK) --pretty-print=_$@ -f "$(srcdir)"/$@.awk > /dev/null @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ posix2008sub: @@ -1970,6 +1974,17 @@ printhuge:: AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +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 _$@ + + # Targets generated for other tests: include Maketests diff --git a/test/Makefile.in b/test/Makefile.in index f3b537f3..8d7790f4 100644 --- a/test/Makefile.in +++ b/test/Makefile.in @@ -570,6 +570,8 @@ EXTRA_DIST = \ fwtest3.awk \ fwtest3.in \ fwtest3.ok \ + genpot.awk \ + genpot.ok \ gensub.awk \ gensub.in \ gensub.ok \ @@ -667,6 +669,8 @@ EXTRA_DIST = \ indirectcall.awk \ indirectcall.in \ indirectcall.ok \ + indirectcall2.awk \ + indirectcall2.ok \ inftest.awk \ inftest.ok \ inplace.in \ @@ -1252,10 +1256,10 @@ 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 \ + include include2 indirectcall indirectcall2 \ lint lintold lintwarn \ manyfiles match1 match2 match3 mbstr1 \ nastyparm next nondec nondec2 \ @@ -1591,6 +1595,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: @@ -2110,14 +2116,12 @@ profile3: profile4: @echo $@ - @$(AWK) --pretty-print=ap-$@.out -f "$(srcdir)"/$@.awk > /dev/null - @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @$(AWK) --pretty-print=_$@ -f "$(srcdir)"/$@.awk > /dev/null @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ profile5: @echo $@ - @$(AWK) --pretty-print=ap-$@.out -f "$(srcdir)"/$@.awk > /dev/null - @sed 1,2d < ap-$@.out > _$@; rm ap-$@.out + @$(AWK) --pretty-print=_$@ -f "$(srcdir)"/$@.awk > /dev/null @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ posix2008sub: @@ -2392,6 +2396,16 @@ printhuge:: @[ -z "$$GAWKLOCALE" ] && GAWKLOCALE=en_US.UTF-8; \ AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + +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: @@ -3476,6 +3490,11 @@ indirectcall: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +indirectcall2: + @echo $@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + lint: @echo $@ @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @@ -3700,11 +3719,6 @@ fnmatch: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ -filefuncs: - @echo $@ - @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ - @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ - fork: @echo $@ @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ diff --git a/test/Maketests b/test/Maketests index 0841ae77..f8d5e8a9 100644 --- a/test/Maketests +++ b/test/Maketests @@ -1082,6 +1082,11 @@ indirectcall: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk < "$(srcdir)"/$@.in >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ +indirectcall2: + @echo $@ + @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ + @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ + lint: @echo $@ @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @@ -1306,11 +1311,6 @@ fnmatch: @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ -filefuncs: - @echo $@ - @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ - @-$(CMP) "$(srcdir)"/$@.ok _$@ && rm -f _$@ - fork: @echo $@ @AWKPATH="$(srcdir)" $(AWK) -f $@.awk >_$@ 2>&1 || echo EXIT CODE: $$? >>_$@ diff --git a/test/filefuncs.awk b/test/filefuncs.awk index 4bbfcb55..7aa5ae6a 100644 --- a/test/filefuncs.awk +++ b/test/filefuncs.awk @@ -1,7 +1,7 @@ @load "filefuncs" BEGIN { - if (chdir("..") < 0) { + if (chdir(builddir) < 0) { printf "Error: chdir failed with ERRNO %s\n", ERRNO exit 1 } diff --git a/test/functab4.awk b/test/functab4.awk index 0d9d4267..196fcc6d 100644 --- a/test/functab4.awk +++ b/test/functab4.awk @@ -6,9 +6,25 @@ function foo() } BEGIN { - x = FUNCTAB["chdir"] - print "x =", x - @x("/tmp") - printf "we are now in --> " - system("/bin/pwd || /usr/bin/pwd") + f = FUNCTAB["foo"] + @f() + + ret1 = stat(".", data1) + print "ret1 =", ret1 + + f = "stat" + ret2 = @f(".", data2) + print "ret2 =", ret2 + + problem = 0 + for (i in data1) { + if (! isarray(data1[i])) { +# print i, data1[i] + if (! (i in data2) || data1[i] != data2[i]) { + printf("mismatch element \"%s\"\n", i) + problems++ + } + } + } + print(problems ? (problems+0) "encountered" : "no problems encountered") } diff --git a/test/functab4.ok b/test/functab4.ok index 70a520b7..2b76cd88 100644 --- a/test/functab4.ok +++ b/test/functab4.ok @@ -1,3 +1,4 @@ -x = chdir -gawk: functab4.awk:11: fatal: cannot (yet) call extension functions indirectly -EXIT CODE: 2 +foo! +ret1 = 0 +ret2 = 0 +no problems encountered diff --git a/test/genpot.awk b/test/genpot.awk new file mode 100644 index 00000000..990b0b5c --- /dev/null +++ b/test/genpot.awk @@ -0,0 +1 @@ +{print _"This string is so long that gawk --gen-pot will break it and lose a letter at the break."} diff --git a/test/genpot.ok b/test/genpot.ok new file mode 100644 index 00000000..35c0cc99 --- /dev/null +++ b/test/genpot.ok @@ -0,0 +1,5 @@ +#: genpot.awk:1 +msgid "This string is so long that gawk --gen-pot will break it and lose a l" +"etter at the break." +msgstr "" + @@ -1,32 +1,73 @@ -FUNCTAB -> array -ARGV -> array -SYMTAB -> array -ORS -> scalar -ROUNDMODE -> scalar -i -> untyped OFS -> scalar +rand -> builtin +ARGC -> scalar +dcgettext -> builtin +gsub -> builtin +PREC -> scalar +match -> builtin +ARGIND -> scalar +int -> builtin ERRNO -> scalar +ARGV -> array +log -> builtin +sprintf -> builtin +ROUNDMODE -> scalar +strftime -> builtin +systime -> builtin +and -> builtin +srand -> builtin FNR -> scalar +asort -> builtin +atan2 -> builtin +cos -> builtin +TEXTDOMAIN -> scalar +ORS -> scalar +split -> builtin +div -> builtin +RSTART -> scalar +compl -> builtin +bindtextdomain -> builtin +exp -> builtin +or -> builtin +fflush -> builtin +gensub -> builtin LINT -> scalar +dcngettext -> builtin +index -> builtin IGNORECASE -> scalar -NR -> scalar -function1 -> user -ARGIND -> scalar -NF -> scalar -TEXTDOMAIN -> scalar +system -> builtin CONVFMT -> scalar +sqrt -> builtin +rshift -> builtin +tolower -> builtin +FS -> scalar +BINMODE -> scalar +sin -> builtin +asorti -> builtin FIELDWIDTHS -> scalar -ARGC -> scalar +function1 -> user +FILENAME -> scalar +close -> builtin +mktime -> builtin +FUNCTAB -> array +NF -> scalar +isarray -> builtin an_array -> untyped -PROCINFO -> array -PREC -> scalar +patsplit -> builtin +NR -> scalar SUBSEP -> scalar -FPAT -> scalar -RS -> scalar -FS -> scalar +extension -> builtin +i -> untyped +sub -> builtin OFMT -> scalar RLENGTH -> scalar +substr -> builtin +FPAT -> scalar +RS -> scalar +xor -> builtin RT -> scalar -BINMODE -> scalar -FILENAME -> scalar -RSTART -> scalar +PROCINFO -> array +lshift -> builtin +SYMTAB -> array +strtonum -> builtin +toupper -> builtin diff --git a/test/indirectcall2.awk b/test/indirectcall2.awk new file mode 100644 index 00000000..8f3c9483 --- /dev/null +++ b/test/indirectcall2.awk @@ -0,0 +1,11 @@ +BEGIN { + Quarter_pi = 3.1415927 / 4 + print sin(Quarter_pi) + + f = "sin" + print @f(Quarter_pi) + + print substr("abcdefgh", 2, 3) + f = "substr" + print @f("abcdefgh", 2, 3) +} diff --git a/test/indirectcall2.ok b/test/indirectcall2.ok new file mode 100644 index 00000000..05bee4b1 --- /dev/null +++ b/test/indirectcall2.ok @@ -0,0 +1,4 @@ +0.707107 +0.707107 +bcd +bcd diff --git a/test/profile2.ok b/test/profile2.ok index fe76a2c9..938d6858 100644 --- a/test/profile2.ok +++ b/test/profile2.ok @@ -1,4 +1,4 @@ - # BEGIN block(s) + # BEGIN rule(s) BEGIN { 1 if (sortcmd == "") { @@ -7,7 +7,7 @@ 1 asplit("BEGIN:END:atan2:break:close:continue:cos:delete:" "do:else:exit:exp:for:getline:gsub:if:in:index:int:" "length:log:match:next:print:printf:rand:return:sin:" "split:sprintf:sqrt:srand:sub:substr:system:while", keywords, ":") 1 split("00:00:00:00:00:00:00:00:00:00:" "20:10:10:12:12:11:07:00:00:00:" "08:08:08:08:08:33:08:00:00:00:" "08:44:08:36:08:08:08:00:00:00:" "08:44:45:42:42:41:08", machine, ":") 1 state = 1 - 571 for (; ; ) { + 571 for (;;) { 571 symb = lex() 571 nextstate = substr(machine[state symb], 1, 1) 571 act = substr(machine[state symb], 2, 1) @@ -109,7 +109,7 @@ 571 function lex() { - 1702 for (; ; ) { + 1702 for (;;) { 1702 if (tok == "(eof)") { return 7 } diff --git a/test/profile3.ok b/test/profile3.ok index 50172c48..bbf06541 100644 --- a/test/profile3.ok +++ b/test/profile3.ok @@ -1,4 +1,4 @@ - # BEGIN block(s) + # BEGIN rule(s) BEGIN { 1 the_func = "p" diff --git a/test/profile4.ok b/test/profile4.ok index 8ff4470f..9d2b9430 100644 --- a/test/profile4.ok +++ b/test/profile4.ok @@ -1,11 +1,9 @@ - # BEGIN block(s) - - BEGIN { - a = "foo" (c = "bar") - a = (b - c) "foo" - a = "foo" (b - c) - q = (d = "x") (e = "y") - a = (c = tolower("FOO")) in JUNK - x = y == 0 && z == 2 && q == 45 - } +BEGIN { + a = "foo" (c = "bar") + a = (b - c) "foo" + a = "foo" (b - c) + q = (d = "x") (e = "y") + a = (c = tolower("FOO")) in JUNK + x = y == 0 && z == 2 && q == 45 +} diff --git a/test/profile5.ok b/test/profile5.ok index cc83dc06..4c944627 100644 --- a/test/profile5.ok +++ b/test/profile5.ok @@ -1,4770 +1,5728 @@ - # BEGIN block(s) +BEGIN { + _addlib("_BASE") +} + +############################################################################ + +BEGIN { + BINMODE = "rw" + SUBSEP = "\000" + _NULARR[""] + delete _NULARR[""] + _INITBASE() +} + +BEGIN { + _addlib("_sYS") +} + +BEGIN { + _addlib("_rEG") +} + +BEGIN { + _addlib("_INSTRUC") +} + +############################################################################# + +BEGIN { + _delay_perfmsdelay = 11500 +} + +BEGIN { + _addlib("_ARR") +} + +#___________________________________________________________________________________ +BEGIN { +} + +########################################################################### + + + + + + +BEGIN { + _addlib("_EXTFN") +} + +############################################################################# + +BEGIN { + delete _XCHR + delete _ASC + delete _CHR + t = "" + for (i = 0; i < 256; i++) { + _ASC[a = _CHR[i] = sprintf("%c", i)] = i + _QASC[a] = sprintf("%.3o", i) + _XCHR[_CHR[i]] = sprintf("%c", (i < 128 ? i + 128 : i - 128)) + } + #_____________________________________________________________________________ + + for (i = 0; i < 256; i++) { + _QSTRQ[_CHR[i]] = "\\" sprintf("%.3o", i) + } + #_______________________________________________________________________ + + for (i = 0; i < 32; i++) { + _QSTR[_CHR[i]] = _QSTRQ[_CHR[i]] + } + for (; i < 128; i++) { + _QSTR[_CHR[i]] = _CHR[i] + } + for (; i < 256; i++) { + _QSTR[_CHR[i]] = _QSTRQ[_CHR[i]] + } + _QSTR["\\"] = "\\\\" + #; _QSTR["\""]="\\\"" + #_____________________________________________________________________________ + + _CHR["CR"] = "\r" + _CHR["EOL"] = "\r\n" + _CHR["EOF"] = "\032" + _QSTR[_CHR["EOL"]] = "\\015\\012" + #_______________________________________________________________________ + + _CHR["MONTH"][_CHR["MONTH"]["Jan"] = "01"] = "Jan" + _CHR["MONTH"][_CHR["MONTH"]["Feb"] = "02"] = "Feb" + _CHR["MONTH"][_CHR["MONTH"]["Mar"] = "03"] = "Mar" + _CHR["MONTH"][_CHR["MONTH"]["Apr"] = "04"] = "Apr" + _CHR["MONTH"][_CHR["MONTH"]["May"] = "05"] = "May" + _CHR["MONTH"][_CHR["MONTH"]["Jun"] = "06"] = "Jun" + _CHR["MONTH"][_CHR["MONTH"]["Jul"] = "07"] = "Jul" + _CHR["MONTH"][_CHR["MONTH"]["Aug"] = "08"] = "Aug" + _CHR["MONTH"][_CHR["MONTH"]["Sep"] = "09"] = "Sep" + _CHR["MONTH"][_CHR["MONTH"]["Oct"] = "10"] = "Oct" + _CHR["MONTH"][_CHR["MONTH"]["Nov"] = "11"] = "Nov" + _CHR["MONTH"][_CHR["MONTH"]["Dec"] = "12"] = "Dec" + #_____________________________________________________________________________ + + _TAB_STEP_DEFAULT = 8 + #_____________________________________________________________________________ + + for (i = 0; i < 32; i++) { + _REXPSTR[_CHR[i]] = _QSTRQ[_CHR[i]] + } + for (; i < 256; i++) { + _REXPSTR[_CHR[i]] = _CHR[i] + } + _gensubfn("\\^$.()|{,}[-]?+*", ".", "_rexpstr_i0") +} + +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) +} + +BEGIN { + _addlib("_FILEIO") +} + +############################################################################# + +BEGIN { + if (_SYS_STDOUT == "") { + _SYS_STDOUT = "/dev/stdout" + } + if (_SYS_STDERR == "") { + _SYS_STDERR = "/dev/stderr" + } + _CHR["SUBDIR"] = "\\" + if (_gawk_scriptlevel < 1) { + match(b = _cmd("echo %CD% 2>NUL"), /[^\x00-\x1F]*/) + ENVIRON["CD"] = _FILEIO_RD = _filerd(substr(b, RSTART, RLENGTH) _CHR["SUBDIR"]) + _FILEIO_R = _filer(_FILEIO_RD) + _FILEIO_D = _filed(_FILEIO_RD) + _setmpath(_filerd(_FILEIO_RD "_tmp" _CHR["SUBDIR"])) + } +} + +BEGIN { + _addlib("_tOBJ") +} + +############################################################################# +BEGIN { + _tInBy = "\212._tInBy" + _tgenuid_init() + _UIDS[""] + delete _UIDS[""] + _UIDSDEL[""] + delete _UIDSDEL[""] + _tPREV[""] + _tPARENT[""] + _tNEXT[""] + _tFCHLD[""] + _tQCHLD[""] + _tLCHLD[""] + _tLINK[""] + _tCLASS[""] + _tSTR[""] + _tDLINK[""] + _[""] + delete _[""] + _ptr[""] + delete _ptr[""] + _TMP0[""] + delete _TMP0[""] + _TMP1[""] + delete _TMP1[""] +} + +BEGIN { + _addlib("_ERRLOG") +} + +############################################################################# + +BEGIN { + if (_gawk_scriptlevel < 1) { + _ERRLOG_TF = 1 + _ERRLOG_VF = 1 + _ERRLOG_IF = 1 + _ERRLOG_WF = 1 + _ERRLOG_EF = 1 + _ERRLOG_FF = 1 + _wrfile(_errlog_file = _getmpfile("OUTPUT.LOG"), "") + } +} + +BEGIN { + _addlib("_SHORTCUT") +} + +#___________________________________________________________________________________ +BEGIN { + _shortcut_init() +} + +######################################################### + + + +BEGIN { + _addlib("_eXTFN") +} + +#___________________________________________________________________________________ +BEGIN { + _extfn_init() +} + +############################################################ + + +BEGIN { + _addlib("_sHARE") +} + +BEGIN { + _addlib("_FILEVER") +} + +BEGIN { + _addlib("_DS") + ############################################################################### + + _PRODUCT_NAME = "Deployment Solution Control" + _PRODUCT_VERSION = "1.0" + _PRODUCT_COPYRIGHT = "Copyright (C) 2013 by CosumoGEN" + _PRODUCT_FILENAME = "_main.ewk" +} + +# problem configuring uid by array charset: i can' understand what format of the array: possibly - remove array support +# after removal of array format detection: there is unfinished conflicts: it is possible to totally remove array uid-gen initialization + +#_____________________________________________________ +BEGIN { + _inituidefault() +} + +#_____________________________________________________ +BEGIN { + _initfilever() +} + +#_____________________________________________________ +BEGIN { + _initshare() +} + +#_________________________________________________________________ +BEGIN { + _inspass(_IMPORT, "_import_data") +} + +#_______________________________________________ +BEGIN { + _TEND[_ARRLEN] = 0 + _TYPEWORD = "_TYPE" +} + +#_______________________________________________ +BEGIN { + _ARRLEN = "\032LEN" + _ARRPTR = "\032PTR" + _ARRSTR = "" +} + +#_____________________________________________________ +BEGIN { + _getperf_fn = "_nop" +} + +BEGIN { + _datablock_length = 262144 +} + +#_____________________________________________________ +BEGIN { + _initrdreg() +} + +#_____________________________________________________ +BEGIN { + _initregpath0() +} - BEGIN { - _addlib("_BASE") - } +#_____________________________________________________ +BEGIN { + _initsys() +} - BEGIN { - BINMODE = "rw" - SUBSEP = "\000" - _NULARR[""] - delete _NULARR[""] - _INITBASE() - } - - BEGIN { - _addlib("_sYS") +############################################################################ + +BEGIN { + a = ENVIRON["EGAWK_CMDLINE"] + gsub(/^[ \t]*/, "", a) + a = _lib_CMDLN(a) + if (a != "" && ! _LIBAPI["F"]["!"]) { + _out(_lib_HELP()) + _fatal("Bad comandline argument `" a "'") + } + gsub(/^[ \t]*/, "", a) + ENVIRON["EGAWK_CMDLINE"] = a + _lib_APPLY() + if (_basexit_fl) { + exit + } + _INIT() + _START() + _END() +} + +######################################################################## + +END { + _EXIT() +} + +############################################################################### + +END { + if (_gawk_scriptlevel < 1) { + close(_errlog_file) + p = _Zimport(_rdfile(_errlog_file), _N()) + if ((t = _get_errout(p)) != "") { + _expout(t, "/dev/stderr") + } + } +} + +############################################################################### + +END { + if (_gawk_scriptlevel < 1) { + if (! _fileio_notdeltmpflag) { + _FILEIO_TMPATHS[_FILEIO_TMPRD] + _Foreach(_FILEIO_TMPATHS, "_uninit_del") + } + } +} + +############################################################################### +END { + if (_constatstrln > 0) { + _constat() } +} - BEGIN { - _addlib("_rEG") - } +#___________________________________________________________________________________ +#################################################################################### - BEGIN { - _addlib("_INSTRUC") - } - BEGIN { - _delay_perfmsdelay = 11500 - } - BEGIN { - _addlib("_ARR") - } - BEGIN { - } - BEGIN { - _addlib("_EXTFN") - } - BEGIN { - delete _XCHR - delete _ASC - delete _CHR - t = "" - for (i = 0; i < 256; i++) { - _ASC[a = _CHR[i] = sprintf("%c", i)] = i - _QASC[a] = sprintf("%.3o", i) - _XCHR[_CHR[i]] = sprintf("%c", (i < 128 ? i + 128 : i - 128)) - } - for (i = 0; i < 256; i++) { - _QSTRQ[_CHR[i]] = "\\" sprintf("%.3o", i) - } - for (i = 0; i < 32; i++) { - _QSTR[_CHR[i]] = _QSTRQ[_CHR[i]] - } - for (; i < 128; i++) { - _QSTR[_CHR[i]] = _CHR[i] - } - for (; i < 256; i++) { - _QSTR[_CHR[i]] = _QSTRQ[_CHR[i]] - } - _QSTR["\\"] = "\\\\" - _CHR["CR"] = "\r" - _CHR["EOL"] = "\r\n" - _CHR["EOF"] = "\032" - _QSTR[_CHR["EOL"]] = "\\015\\012" - _CHR["MONTH"][_CHR["MONTH"]["Jan"] = "01"] = "Jan" - _CHR["MONTH"][_CHR["MONTH"]["Feb"] = "02"] = "Feb" - _CHR["MONTH"][_CHR["MONTH"]["Mar"] = "03"] = "Mar" - _CHR["MONTH"][_CHR["MONTH"]["Apr"] = "04"] = "Apr" - _CHR["MONTH"][_CHR["MONTH"]["May"] = "05"] = "May" - _CHR["MONTH"][_CHR["MONTH"]["Jun"] = "06"] = "Jun" - _CHR["MONTH"][_CHR["MONTH"]["Jul"] = "07"] = "Jul" - _CHR["MONTH"][_CHR["MONTH"]["Aug"] = "08"] = "Aug" - _CHR["MONTH"][_CHR["MONTH"]["Sep"] = "09"] = "Sep" - _CHR["MONTH"][_CHR["MONTH"]["Oct"] = "10"] = "Oct" - _CHR["MONTH"][_CHR["MONTH"]["Nov"] = "11"] = "Nov" - _CHR["MONTH"][_CHR["MONTH"]["Dec"] = "12"] = "Dec" - _TAB_STEP_DEFAULT = 8 - for (i = 0; i < 32; i++) { - _REXPSTR[_CHR[i]] = _QSTRQ[_CHR[i]] - } - for (; i < 256; i++) { - _REXPSTR[_CHR[i]] = _CHR[i] - } - _gensubfn("\\^$.()|{,}[-]?+*", ".", "_rexpstr_i0") - } - BEGIN { - _addlib("_SYSIO") - } +# make sure that stdout contain only expected characters +# make sure that stderr contain only expected characters +# redesign & reformat keys and its outputs +# try different key combinations +# add lib-specified to all libs - BEGIN { - _SYS_STDCON = "CON" - _CON_WIDTH = (match(_cmd("MODE " _SYS_STDCON " 2>NUL"), /Columns:[ \t]*([0-9]+)/, A) ? strtonum(A[1]) : 80) - } - BEGIN { - _addlib("_FILEIO") - } - - BEGIN { - if (_SYS_STDOUT == "") { - _SYS_STDOUT = "/dev/stdout" - } - if (_SYS_STDERR == "") { - _SYS_STDERR = "/dev/stderr" - } - _CHR["SUBDIR"] = "\\" - if (_gawk_scriptlevel < 1) { - match(b = _cmd("echo %CD% 2>NUL"), /[^\x00-\x1F]*/) - ENVIRON["CD"] = _FILEIO_RD = _filerd(substr(b, RSTART, RLENGTH) _CHR["SUBDIR"]) - _FILEIO_R = _filer(_FILEIO_RD) - _FILEIO_D = _filed(_FILEIO_RD) - _setmpath(_filerd(_FILEIO_RD "_tmp" _CHR["SUBDIR"])) +#_______________________________________________________________________ +function W(p, p0, p1) +{ + ##################################################### + if (isarray(p0)) { + delete p0[p] + if (isarray(p1)) { + for (i in p1) { + if (isarray(p1[i])) { + p0[p][i][""] + delete p0[p][i][""] + _N_i0(p0[p][i], p1[i]) + } else { + p0[p][i] = p1[i] + } + } + return p } + return (p0[p] = p1) } - - BEGIN { - _addlib("_tOBJ") - } - - BEGIN { - _tInBy = "\212._tInBy" - _tgenuid_init() - _UIDS[""] - delete _UIDS[""] - _UIDSDEL[""] - delete _UIDSDEL[""] - _tPREV[""] - _tPARENT[""] - _tNEXT[""] - _tFCHLD[""] - _tQCHLD[""] - _tLCHLD[""] - _tLINK[""] - _tCLASS[""] - _tSTR[""] - _tDLINK[""] - _[""] - delete _[""] - _ptr[""] - delete _ptr[""] - _TMP0[""] - delete _TMP0[""] - _TMP1[""] - delete _TMP1[""] - } - - BEGIN { - _addlib("_ERRLOG") - } - - BEGIN { - if (_gawk_scriptlevel < 1) { - _ERRLOG_TF = 1 - _ERRLOG_VF = 1 - _ERRLOG_IF = 1 - _ERRLOG_WF = 1 - _ERRLOG_EF = 1 - _ERRLOG_FF = 1 - _wrfile(_errlog_file = _getmpfile("OUTPUT.LOG"), "") + delete _[p][p0] + if (isarray(p1)) { + for (i in p1) { + if (isarray(p1[i])) { + _[p][p0][i][""] + delete _[p][p0][i][""] + _N_i0(_[p][p0][i], p1[i]) + } else { + _[p][p0][i] = p1[i] + } } + return p } + return (_[p][p0] = p1) +} - BEGIN { - _addlib("_SHORTCUT") - } - - BEGIN { - _shortcut_init() - } - - BEGIN { - _addlib("_eXTFN") - } - - BEGIN { - _extfn_init() - } - - BEGIN { - _addlib("_sHARE") - } - - BEGIN { - _addlib("_FILEVER") - } - - BEGIN { - _addlib("_DS") - _PRODUCT_NAME = "Deployment Solution Control" - _PRODUCT_VERSION = "1.0" - _PRODUCT_COPYRIGHT = "Copyright (C) 2013 by CosumoGEN" - _PRODUCT_FILENAME = "_main.ewk" - } - - BEGIN { - _inituidefault() - } - - BEGIN { - _initfilever() - } - - BEGIN { - _initshare() - } - - BEGIN { - _inspass(_IMPORT, "_import_data") - } - - BEGIN { - _TEND[_ARRLEN] = 0 - _TYPEWORD = "_TYPE" - } - - BEGIN { - _ARRLEN = "\032LEN" - _ARRPTR = "\032PTR" - _ARRSTR = "" - } - - BEGIN { - _getperf_fn = "_nop" - } - - BEGIN { - _datablock_length = 262144 - } - - BEGIN { - _initrdreg() - } - - BEGIN { - _initregpath0() - } - - BEGIN { - _initsys() - } +########################################################## - BEGIN { - a = ENVIRON["EGAWK_CMDLINE"] - gsub(/^[ \t]*/, "", a) - a = _lib_CMDLN(a) - if (a != "" && ! _LIBAPI["F"]["!"]) { - _out(_lib_HELP()) - _fatal("Bad comandline argument `" a "'") - } - gsub(/^[ \t]*/, "", a) - ENVIRON["EGAWK_CMDLINE"] = a - _lib_APPLY() - if (_basexit_fl) { - exit - } - _INIT() - _START() - _END() +function _ARR(c, t, P) +{ + switch (c) { + case "_lib_CMDLN": + return t + #___________________________________________________________ + + case "_lib_APPLY": + return + #___________________________________________________________ + + case "_lib_HELP": + return + #___________________________________________________________ + + case "_lib_NAMEVER": + return _ln("_ARR 1.0") + #___________________________________________________________ + + case "_lib_BEGIN": + return + #___________________________________________________________ + + case "_lib_END": + return } +} - # END block(s) +########################################################## - END { - _EXIT() - } - - END { - if (_gawk_scriptlevel < 1) { - close(_errlog_file) - p = _Zimport(_rdfile(_errlog_file), _N()) - if ((t = _get_errout(p)) != "") { - _expout(t, "/dev/stderr") +function _BASE(c, t, P, A) +{ + switch (c) { + case "_lib_CMDLN": + if (match(t, /^((--([Vv])ersion)|(-([Vv])))[ \t]*/, A)) { + t = substr(t, RLENGTH + 1) + _cmdln_version = A[3] A[5] + } else { + if (match(t, /^((-?\?)|(--help))[ \t]*/)) { + t = substr(t, RLENGTH + 1) + _cmdln_help = 1 + } else { + if (match(t, /^--[ \t]*/)) { + return _endpass(substr(t, RLENGTH + 1)) + } } } - } - - END { - if (_gawk_scriptlevel < 1) { - if (! _fileio_notdeltmpflag) { - _FILEIO_TMPATHS[_FILEIO_TMPRD] - _Foreach(_FILEIO_TMPATHS, "_uninit_del") - } + return t + #___________________________________________________________ + + case "_lib_APPLY": + if (_cmdln_help) { + match(_fbaccr(_LIBAPI, "_lib_HELP"), /^([^\x00]*)\x00([^\x01]*)\x01(.*)/, A) + _out(A[2] A[1] A[3]) + return _endpass(_basexit_fl = 1) + } + if (_cmdln_version) { + _out(_ln(_PRODUCT_NAME " v" _PRODUCT_VERSION) _ln(_PRODUCT_COPYRIGHT) _ln() ((_cmdln_version == "v" ? "" : _lib_NAMEVER()))) + return _endpass(_basexit_fl = 1) } + return + #___________________________________________________________ + + case "_lib_HELP": + return ("\000" _ln(_PRODUCT_NAME " v" _PRODUCT_VERSION) _ln(_PRODUCT_COPYRIGHT) _ln() _ln(" Usage:") _ln() _ln(" " _PRODUCT_FILENAME " [/key1 /key2...] [-- cmdline]") _ln() _ln(" keys:") _ln() "\001" _ln(" -v -V --version - output product version and (if /V) all modules") _ln(" ? -? --help - output this help page") _ln(" -- - command line string edge")) + #___________________________________________________________ + + case "_lib_NAMEVER": + return _ln("_BASE 3.0") + #___________________________________________________________ + + case "_lib_BEGIN": + return + #___________________________________________________________ + + case "_lib_END": + return } +} - END { - if (_constatstrln > 0) { - _constat() - } +#____________________________________________________________________________ +function _DS(c, t, P, a, A) +{ + ###################################################### + switch (c) { + case "_lib_CMDLN": + #___________________________________________________________ + return t + #_____________________________________________________ + case "_lib_APPLY": + return + #_____________________________________________________ + case "_lib_HELP": + return (_ln() _ln(" Usage: " _PRODUCT_NAME " [/key1 /key2...] sourcefile [cmdline]") _ln()) + #_____________________________________________________ + case "_lib_NAMEVER": + return + #_____________________________________________________ + case "_lib_BEGIN": + return + #_____________________________________________________ + case "_lib_END": + return } +} +#______________________________________________________________________________________________ +function _END() +{ + ################################################################################# + +} - # Functions, listed alphabetically +######################################################## - function W(p, p0, p1) - { - if (isarray(p0)) { - delete p0[p] - if (isarray(p1)) { - for (i in p1) { - if (isarray(p1[i])) { - p0[p][i][""] - delete p0[p][i][""] - _N_i0(p0[p][i], p1[i]) - } else { - p0[p][i] = p1[i] - } - } - return p - } - return (p0[p] = p1) +function _ERRLOG(c, t, P, a, b, A) +{ + switch (c) { + case "_lib_CMDLN": + if (match(t, /^[ \t]*-L:([TtVvIiWwEeFf]*)[ \t]*/, A)) { + t = substr(t, RLENGTH + 1) + _errlog_errflkey = _errlog_errflkey A[1] } - delete _[p][p0] - if (isarray(p1)) { - for (i in p1) { - if (isarray(p1[i])) { - _[p][p0][i][""] - delete _[p][p0][i][""] - _N_i0(_[p][p0][i], p1[i]) + return t + #_______________________________________________________________________ + + case "_lib_APPLY": + if (_errlog_errflkey) { + split(_errlog_errflkey, A, "") + for (a = 1; a in A; a++) { + if (A[a] == toupper(A[a])) { + b = 1 } else { - _[p][p0][i] = p1[i] + b = "" + } + switch (toupper(A[a])) { + case "T": + _ERRLOG_TF = b + break + case "V": + _ERRLOG_VF = b + break + case "I": + _ERRLOG_IF = b + break + case "W": + _ERRLOG_WF = b + break + case "E": + _ERRLOG_EF = b + break + case "F": + _ERRLOG_FF = b + break } } - return p + if (_ERRLOG_IF) { + _info("Log-message types inherited acc/deny: " "TRACE " ((_ERRLOG_TF ? "ON" : "OFF")) "/" "VERBOSE " ((_ERRLOG_VF ? "ON" : "OFF")) "/" "INFO " ((_ERRLOG_IF ? "ON" : "OFF")) "/" "WARNING " ((_ERRLOG_WF ? "ON" : "OFF")) "/" "ERROR " ((_ERRLOG_EF ? "ON" : "OFF")) "/" "FATAL " ((_ERRLOG_FF ? "ON" : "OFF"))) + } } - return (_[p][p0] = p1) + return + #_______________________________________________________________________ + + case "_lib_HELP": + return (_ln(" -L:TtVvIiWwEeFf - enable(upcase: TVIWEF) or disable(lowcase: tviwef) allowable type of") _ln(" log messages. Trace/Verbose/Informational/Warning/Error/Fatal.") _ln()) + #_______________________________________________________________________ + + case "_lib_NAMEVER": + return _ln("_ERRLOG 1.0") + #_______________________________________________________________________ + + case "_lib_BEGIN": + P["_ERRLOG_TF"] = _ERRLOG_TF + P["_ERRLOG_VF"] = _ERRLOG_VF + P["_ERRLOG_IF"] = _ERRLOG_IF + P["_ERRLOG_WF"] = _ERRLOG_WF + P["_ERRLOG_EF"] = _ERRLOG_EF + P["_ERRLOG_FF"] = _ERRLOG_FF + P["_errlog_file"] = "/dev/stderr" + return } +} - function _ARR(c, t, P) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return _ln("_ARR 1.0") - case "_lib_BEGIN": - return - case "_lib_END": - return - } +#______________________________________________________________________________________________ +function _EXIT() +{ + ################################################################################ + +} + +######################################################## + +function _EXTFN(c, t, P) +{ + switch (c) { + case "_lib_CMDLN": + return t + #___________________________________________________________ + + case "_lib_APPLY": + return + #___________________________________________________________ + + case "_lib_HELP": + return + #___________________________________________________________ + + case "_lib_NAMEVER": + return _ln("_EXTFN 1.0") + #___________________________________________________________ + + case "_lib_BEGIN": + return + #___________________________________________________________ + + case "_lib_END": + return } +} - function _BASE(c, t, P, A) - { - switch (c) { - case "_lib_CMDLN": - if (match(t, /^((--([Vv])ersion)|(-([Vv])))[ \t]*/, A)) { - t = substr(t, RLENGTH + 1) - _cmdln_version = A[3] A[5] +####################################################### + +function _FILEIO(c, t, P, A) +{ + switch (c) { + case "_lib_CMDLN": + if (match(t, /^[ \t]*-[Tt]([\+-])[ \t]*/, A)) { + t = substr(t, RLENGTH + 1) + if (A[1] == "+") { + _fileio_notdeltmpflag = 1 } else { - if (match(t, /^((-?\?)|(--help))[ \t]*/)) { - t = substr(t, RLENGTH + 1) - _cmdln_help = 1 - } else { - if (match(t, /^--[ \t]*/)) { - return _endpass(substr(t, RLENGTH + 1)) - } - } - } - return t - case "_lib_APPLY": - if (_cmdln_help) { - match(_fbaccr(_LIBAPI, "_lib_HELP"), /^([^\x00]*)\x00([^\x01]*)\x01(.*)/, A) - _out(A[2] A[1] A[3]) - return _endpass(_basexit_fl = 1) + _fileio_notdeltmpflag = "" } - if (_cmdln_version) { - _out(_ln(_PRODUCT_NAME " v" _PRODUCT_VERSION) _ln(_PRODUCT_COPYRIGHT) _ln() ((_cmdln_version == "v" ? "" : _lib_NAMEVER()))) - return _endpass(_basexit_fl = 1) - } - return - case "_lib_HELP": - return ("\000" _ln(_PRODUCT_NAME " v" _PRODUCT_VERSION) _ln(_PRODUCT_COPYRIGHT) _ln() _ln(" Usage:") _ln() _ln(" " _PRODUCT_FILENAME " [/key1 /key2...] [-- cmdline]") _ln() _ln(" keys:") _ln() "\001" _ln(" -v -V --version - output product version and (if /V) all modules") _ln(" ? -? --help - output this help page") _ln(" -- - command line string edge")) - case "_lib_NAMEVER": - return _ln("_BASE 3.0") - case "_lib_BEGIN": - return - case "_lib_END": - return } - } - - function _DS(c, t, P, a, A) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return (_ln() _ln(" Usage: " _PRODUCT_NAME " [/key1 /key2...] sourcefile [cmdline]") _ln()) - case "_lib_NAMEVER": - return - case "_lib_BEGIN": - return - case "_lib_END": - return + return t + #___________________________________________________________ + + case "_lib_APPLY": + if (_fileio_notdeltmpflag) { + _info("Temporary objects deletion DISABLED (inherited)") + } + return + #___________________________________________________________ + + case "_lib_HELP": + return (_ln(" -[Tt][+-] - inherited: +enable\\-disable temporary files\\dirs deletion") _ln()) + #___________________________________________________________ + + case "_lib_NAMEVER": + return _ln("_FILEIO 2.1") + #___________________________________________________________ + + case "_lib_BEGIN": + P["ENVIRON"]["CD"] = ENVIRON["CD"] + P["_FILEIO_RD"] = _FILEIO_RD + P["_FILEIO_R"] = _FILEIO_R + P["_FILEIO_D"] = _FILEIO_D + if (! ("_FILEIO_TMPRD" in P)) { + P["_FILEIO_TMPRD"] = _getmpdir(_filen(P["SOURCE"]) "." ++_egawk_subcntr _CHR["SUBDIR"]) } + return + #___________________________________________________________ + + case "_lib_END": + return } +} - function _END() - { +############################################################ +#_____________________________________________________________________________ +function _FILEVER(c, t, P, a, A) +{ + ################################################# + switch (c) { + case "_lib_CMDLN": + #___________________________________________________________ + return t + #_____________________________________________________ + case "_lib_APPLY": + return + #_____________________________________________________ + case "_lib_HELP": + return + #_____________________________________________________ + case "_lib_NAMEVER": + return + #_____________________________________________________ + case "_lib_BEGIN": + return + #_____________________________________________________ + case "_lib_END": + return } +} - function _ERRLOG(c, t, P, a, b, A) - { - switch (c) { - case "_lib_CMDLN": - if (match(t, /^[ \t]*-L:([TtVvIiWwEeFf]*)[ \t]*/, A)) { - t = substr(t, RLENGTH + 1) - _errlog_errflkey = _errlog_errflkey A[1] - } - return t - case "_lib_APPLY": - if (_errlog_errflkey) { - split(_errlog_errflkey, A, "") - for (a = 1; a in A; a++) { - if (A[a] == toupper(A[a])) { - b = 1 - } else { - b = "" - } - switch (toupper(A[a])) { - case "T": - _ERRLOG_TF = b - break - case "V": - _ERRLOG_VF = b - break - case "I": - _ERRLOG_IF = b - break - case "W": - _ERRLOG_WF = b - break - case "E": - _ERRLOG_EF = b - break - case "F": - _ERRLOG_FF = b - break - } - } - if (_ERRLOG_IF) { - _info("Log-message types inherited acc/deny: " "TRACE " ((_ERRLOG_TF ? "ON" : "OFF")) "/" "VERBOSE " ((_ERRLOG_VF ? "ON" : "OFF")) "/" "INFO " ((_ERRLOG_IF ? "ON" : "OFF")) "/" "WARNING " ((_ERRLOG_WF ? "ON" : "OFF")) "/" "ERROR " ((_ERRLOG_EF ? "ON" : "OFF")) "/" "FATAL " ((_ERRLOG_FF ? "ON" : "OFF"))) - } - } - return - case "_lib_HELP": - return (_ln(" -L:TtVvIiWwEeFf - enable(upcase: TVIWEF) or disable(lowcase: tviwef) allowable type of") _ln(" log messages. Trace/Verbose/Informational/Warning/Error/Fatal.") _ln()) - case "_lib_NAMEVER": - return _ln("_ERRLOG 1.0") - case "_lib_BEGIN": - P["_ERRLOG_TF"] = _ERRLOG_TF - P["_ERRLOG_VF"] = _ERRLOG_VF - P["_ERRLOG_IF"] = _ERRLOG_IF - P["_ERRLOG_WF"] = _ERRLOG_WF - P["_ERRLOG_EF"] = _ERRLOG_EF - P["_ERRLOG_FF"] = _ERRLOG_FF - P["_errlog_file"] = "/dev/stderr" - return - } +function _Foreach(A, f, p0, i) +{ + for (i in A) { + @f(A, i, p0) } +} - function _EXIT() - { - } +function _INIT(f) +{ +} - function _EXTFN(c, t, P) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return _ln("_EXTFN 1.0") - case "_lib_BEGIN": - return - case "_lib_END": - return - } - } +#___________________________________________________________________________________ +function _INITBASE() +{ + ################################################################ + + _egawk_utilpath = ENVIRON["EGAWK_PATH"] "BIN\\UTIL\\" +} - function _FILEIO(c, t, P, A) - { - switch (c) { - case "_lib_CMDLN": - if (match(t, /^[ \t]*-[Tt]([\+-])[ \t]*/, A)) { - t = substr(t, RLENGTH + 1) - if (A[1] == "+") { - _fileio_notdeltmpflag = 1 - } else { - _fileio_notdeltmpflag = "" - } - } - return t - case "_lib_APPLY": - if (_fileio_notdeltmpflag) { - _info("Temporary objects deletion DISABLED (inherited)") - } - return - case "_lib_HELP": - return (_ln(" -[Tt][+-] - inherited: +enable\\-disable temporary files\\dirs deletion") _ln()) - case "_lib_NAMEVER": - return _ln("_FILEIO 2.1") - case "_lib_BEGIN": - P["ENVIRON"]["CD"] = ENVIRON["CD"] - P["_FILEIO_RD"] = _FILEIO_RD - P["_FILEIO_R"] = _FILEIO_R - P["_FILEIO_D"] = _FILEIO_D - if (! ("_FILEIO_TMPRD" in P)) { - P["_FILEIO_TMPRD"] = _getmpdir(_filen(P["SOURCE"]) "." ++_egawk_subcntr _CHR["SUBDIR"]) - } - return - case "_lib_END": - return - } - } +###################################################### - function _FILEVER(c, t, P, a, A) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return - case "_lib_BEGIN": - return - case "_lib_END": - return - } +function _INSTRUC(c, t, P) +{ + switch (c) { + case "_lib_CMDLN": + return t + #___________________________________________________________ + + case "_lib_APPLY": + return + #___________________________________________________________ + + case "_lib_HELP": + return + #___________________________________________________________ + + case "_lib_NAMEVER": + return _ln("_INSTRUC 1.0") + #___________________________________________________________ + + case "_lib_BEGIN": + return + #___________________________________________________________ + + case "_lib_END": + return } +} - function _Foreach(A, f, p0, i) - { - for (i in A) { - @f(A, i, p0) - } - } +#___________________________________________________________________________________ - function _INIT(f) - { - } - function _INITBASE() - { - _egawk_utilpath = ENVIRON["EGAWK_PATH"] "BIN\\UTIL\\" - } +#################################################################################### - function _INSTRUC(c, t, P) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return _ln("_INSTRUC 1.0") - case "_lib_BEGIN": - return - case "_lib_END": - return - } - } - function _N(F, v, p) - { - for (p in _UIDS) { - delete _UIDS[p] - return _nN_i0(p, F, v) - } - return _nN_i0(_tgenuid(), F, v) +#_____________________________________________________________________________ +function _N(F, v, p) +{ + ########################################################### + for (p in _UIDS) { + delete _UIDS[p] + return _nN_i0(p, F, v) } + return _nN_i0(_tgenuid(), F, v) +} - function _SHORTCUT(c, t, P) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return _ln("_shortcut 1.0") - case "_lib_BEGIN": - return - case "_lib_END": - return - } - } +##################################################### - function _START(t, i, A) - { - _torexp_init() - test_uid() +function _SHORTCUT(c, t, P) +{ + switch (c) { + case "_lib_CMDLN": + return t + #___________________________________________________________ + + case "_lib_APPLY": return - _conl(patsplit("a,b,c", A, /[^,]/, B)) - test_splitstr() + #___________________________________________________________ + + case "_lib_HELP": return - A[""] - _CLASSPTR["ptr"] - ALTARR["ptra"] - _conl(_dumparr(SYMTAB)) - BB[1] = _NOP - zorr(1, 2, 3, 4, 5, 6) - zorr(BB, 1) - _rtn() - _rtn("") - _rtn(0) - _rtn("0") - _rtn(1) - _rtn("1") - _rtn(-1) - _rtn("-1") - _rtn("huj") - _rtn("ptr") - _rtn("ptra", ALTARR) - _rtn(ALTARR) - _rtn(ALTARR, ALTARR) + #___________________________________________________________ + + case "_lib_NAMEVER": + return _ln("_shortcut 1.0") + #___________________________________________________________ + + case "_lib_BEGIN": return - _tstini() + #___________________________________________________________ + + case "_lib_END": return - _splitpath_test() + } +} + +#______________________________________________________________________________________________ +function _START(t, i, A) +{ + ######################################################################### + _torexp_init() + test_uid() + return + _conl(patsplit("a,b,c", A, /[^,]/, B)) + test_splitstr() + return + A[""] + _CLASSPTR["ptr"] + ALTARR["ptra"] + _conl(_dumparr(SYMTAB)) + BB[1] = _NOP + zorr(1, 2, 3, 4, 5, 6) + zorr(BB, 1) + _rtn() + _rtn("") + _rtn(0) + _rtn("0") + _rtn(1) + _rtn("1") + _rtn(-1) + _rtn("-1") + _rtn("huj") + _rtn("ptr") + _rtn("ptra", ALTARR) + _rtn(ALTARR) + _rtn(ALTARR, ALTARR) + return + _tstini() + return + _splitpath_test() + # _split_regpath() + return + hh = "CPU" + _conl("go1!") + _conl(_var(_sharepath(hh, "gdfsgdsgsd sdgsdighjui teretiewrotrewut 345345345 rtjtireutireu huj"))) + _conl("go2!") + _conl(_var(_sharelist(AAA, hh), _dumparr(AAA))) + _conline() + A[1] = "h" + A[3] = "j" + t = "pizda" + if (match(t, /^pi(Z)da/, A)) { + _conl("match") + } else { + _conl("not match") + } + _conl(_dumparr(A)) + return + _pathSMA = "C:\\Program Files\\Altiris\\Altiris Agent\\" + DSPlugInPath = _pathSMA "Agents\\Deployment\\Agent\\" + DSAutoPath = _pathSMA + if (! _sysinfo(_SYS, _hostname)) { + _fatal("_sysinfo: unknown error") + } + _REG[""] + delete _REG[""] + _servoutput = _CHR["EOL"] _cmd("sc query state= all") + _dsbasepath = "\\\\CPU\\CPU\\DEV\\PROJECT\\_DS\\" + _rdreg(_REG, "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris") + _wrfile("rego.txt", _dumparr(_REG)) + _conl("fF") + #_______________________________________________________________________ + + c = _getreg_i1(DDD, "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Altiris Agent\\Plugin Objects\\\204~.*\224Install path", _REG) + #_________________________________________________________________________________________ + pp = _n("NAME", "NS") + #pp=_n() + #___________________________________________________________________________________ + p = _defsolution(pp, "DS Plug-in", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Altiris Agent\\Plugin Objects\\Agents\\") + ClientConfiguration = _defdll(p, "Client Configuration", "ClientConfiguration") + ClientImagingPrep = _defdll(p, "Client Inaging Preparation", "ClientImagingPrep") + ClientImaging = _defdll(p, "Client Imaging", "ClientImaging") + ClientPCT = _defdll(p, "Client PCT", "ClientPCT") + ClientRebootTo = _defdll(p, "Client Reboot To", "ClientRebootTo") + DeploymentAgent = _defdll(p, "Deployment Agent", "Deployment Agent") + DeploymentSolutionBaseAgent = _defdll(p, "Deployment Solution Base Agent", "Deployment Solution Base Agent") + ClientBCDEdit = _defile(p, "Client BCD Edit", "ClientBCDEdit.dll") + ClientCopyFile = _defile(p, "Client Copy File", "ClientCopyFile.dll") + ClientPreImage = _defile(p, "Client Pre Image", "ClientPreImage.dll") + ClientRebootTo = _defile(p, "Client Reboot To", "ClientRebootTo.dll") + _defile(p, "ConfigService.exe", "ConfigService.exe", "") + _defile(p, "config.dll", "config.dll", "") + _defsrv(p, "DS Plug-in Service", "Altiris Deployment Solution - System Configuration") + _defreg(p, "Deployment Agent Path", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Deployment\\AgentInstallPath.STR") + _defile(p, "Altiris_DeploymentSolutionAgent_7_1_x86.msi", (_SYS["OSArchitecture"] == "64-bit" ? "C:\\Program Files\\Altiris\\Altiris Agent\\Agents\\SoftwareManagement\\Software Delivery\\{9D76E4CA-377A-472D-A82E-EDAD77E7E4ED}\\cache\\Altiris_DeploymentSolutionAgent_7_1_x64.msi" : "C:\\Program Files\\Altiris\\Altiris Agent\\Agents\\SoftwareManagement\\Software Delivery\\{4B747D25-612F-48FC-B6B5-9916D1BB755C}\\cache\\Altiris_DeploymentSolutionAgent_7_1_x86.msi"), "") + _defdir(p, "Deployment Folder", a = gensub(/[^\\]*$/, "", 1, _rdsafe(_REG, "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Deployment\\AgentInstallPath.STR", "C:\\Program Files\\Altiris\\Altiris Agent\\Agents\\Deployment\\Agent\\"))) + #___________________________________________________________________________________ + p = _defsolution(pp, "DS Auto", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Altiris Agent\\Plugin Objects\\Agents\\") + _defdir(p, "C:\\Boot\\Altiris\\iso\\boot\\fonts\\", "C:\\Boot\\Altiris\\iso\\boot\\fonts\\") + _defdir(p, "C:\\Boot\\Altiris\\iso\\sources\\", "C:\\Boot\\Altiris\\iso\\sources\\") + _defile(p, "C:\\Boot\\Altiris\\iso\\autoinst.exe", "C:\\Boot\\Altiris\\iso\\autoinst.exe", "") + _defile(p, "C:\\Boot\\Altiris\\iso\\autoinst.ini", "C:\\Boot\\Altiris\\iso\\autoinst.ini", "") + _defile(p, "C:\\Boot\\Altiris\\iso\\autoutil.exe", "C:\\Boot\\Altiris\\iso\\autoutil.exe", "") + _defile(p, "C:\\Boot\\Altiris\\iso\\autoutil.ini", "C:\\Boot\\Altiris\\iso\\autoutil.ini", "") + _defile(p, "C:\\Boot\\Altiris\\iso\\bcdedit.exe", "C:\\Boot\\Altiris\\iso\\bcdedit.exe", "") + _defile(p, "C:\\Boot\\Altiris\\iso\\bootmgr", "C:\\Boot\\Altiris\\iso\\bootmgr", "") + _defile(p, "C:\\Boot\\Altiris\\iso\\bootsect.exe", "C:\\Boot\\Altiris\\iso\\bootsect.exe", "") + _defreg(p, "Deployment Automation reg.File", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\AutoUtil\\File.XSZ", "autoutil.exe") + _defreg(p, "Deployment Automation reg.Path", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\AutoUtil\\Path.XSZ", "%systemdrive%\\boot\\altiris\\iso") + #_________________________________________________________________________________________ + + _check(pp) + #_________________________________________________________________________________________ + + _conl(_report(pp)) + _wrfile("report.txt", _report(pp)) +} + +######################################################### + +function _SYSIO(c, t, P) +{ + switch (c) { + case "_lib_CMDLN": + return t + #___________________________________________________________ + + case "_lib_APPLY": return - hh = "CPU" - _conl("go1!") - _conl(_var(_sharepath(hh, "gdfsgdsgsd sdgsdighjui teretiewrotrewut 345345345 rtjtireutireu huj"))) - _conl("go2!") - _conl(_var(_sharelist(AAA, hh), _dumparr(AAA))) - _conline() - A[1] = "h" - A[3] = "j" - t = "pizda" - if (match(t, /^pi(Z)da/, A)) { - _conl("match") - } else { - _conl("not match") - } - _conl(_dumparr(A)) + #___________________________________________________________ + + case "_lib_HELP": + return + #___________________________________________________________ + + case "_lib_NAMEVER": + return _ln("_SYSIO 1.0") + #___________________________________________________________ + + case "_lib_BEGIN": + return + #___________________________________________________________ + + case "_lib_END": return - _pathSMA = "C:\\Program Files\\Altiris\\Altiris Agent\\" - DSPlugInPath = _pathSMA "Agents\\Deployment\\Agent\\" - DSAutoPath = _pathSMA - if (! _sysinfo(_SYS, _hostname)) { - _fatal("_sysinfo: unknown error") - } - _REG[""] - delete _REG[""] - _servoutput = _CHR["EOL"] _cmd("sc query state= all") - _dsbasepath = "\\\\CPU\\CPU\\DEV\\PROJECT\\_DS\\" - _rdreg(_REG, "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris") - _wrfile("rego.txt", _dumparr(_REG)) - _conl("fF") - c = _getreg_i1(DDD, "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Altiris Agent\\Plugin Objects\\\204~.*\224Install path", _REG) - pp = _n("NAME", "NS") - p = _defsolution(pp, "DS Plug-in", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Altiris Agent\\Plugin Objects\\Agents\\") - ClientConfiguration = _defdll(p, "Client Configuration", "ClientConfiguration") - ClientImagingPrep = _defdll(p, "Client Inaging Preparation", "ClientImagingPrep") - ClientImaging = _defdll(p, "Client Imaging", "ClientImaging") - ClientPCT = _defdll(p, "Client PCT", "ClientPCT") - ClientRebootTo = _defdll(p, "Client Reboot To", "ClientRebootTo") - DeploymentAgent = _defdll(p, "Deployment Agent", "Deployment Agent") - DeploymentSolutionBaseAgent = _defdll(p, "Deployment Solution Base Agent", "Deployment Solution Base Agent") - ClientBCDEdit = _defile(p, "Client BCD Edit", "ClientBCDEdit.dll") - ClientCopyFile = _defile(p, "Client Copy File", "ClientCopyFile.dll") - ClientPreImage = _defile(p, "Client Pre Image", "ClientPreImage.dll") - ClientRebootTo = _defile(p, "Client Reboot To", "ClientRebootTo.dll") - _defile(p, "ConfigService.exe", "ConfigService.exe", "") - _defile(p, "config.dll", "config.dll", "") - _defsrv(p, "DS Plug-in Service", "Altiris Deployment Solution - System Configuration") - _defreg(p, "Deployment Agent Path", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Deployment\\AgentInstallPath.STR") - _defile(p, "Altiris_DeploymentSolutionAgent_7_1_x86.msi", (_SYS["OSArchitecture"] == "64-bit" ? "C:\\Program Files\\Altiris\\Altiris Agent\\Agents\\SoftwareManagement\\Software Delivery\\{9D76E4CA-377A-472D-A82E-EDAD77E7E4ED}\\cache\\Altiris_DeploymentSolutionAgent_7_1_x64.msi" : "C:\\Program Files\\Altiris\\Altiris Agent\\Agents\\SoftwareManagement\\Software Delivery\\{4B747D25-612F-48FC-B6B5-9916D1BB755C}\\cache\\Altiris_DeploymentSolutionAgent_7_1_x86.msi"), "") - _defdir(p, "Deployment Folder", a = gensub(/[^\\]*$/, "", 1, _rdsafe(_REG, "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Deployment\\AgentInstallPath.STR", "C:\\Program Files\\Altiris\\Altiris Agent\\Agents\\Deployment\\Agent\\"))) - p = _defsolution(pp, "DS Auto", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Altiris Agent\\Plugin Objects\\Agents\\") - _defdir(p, "C:\\Boot\\Altiris\\iso\\boot\\fonts\\", "C:\\Boot\\Altiris\\iso\\boot\\fonts\\") - _defdir(p, "C:\\Boot\\Altiris\\iso\\sources\\", "C:\\Boot\\Altiris\\iso\\sources\\") - _defile(p, "C:\\Boot\\Altiris\\iso\\autoinst.exe", "C:\\Boot\\Altiris\\iso\\autoinst.exe", "") - _defile(p, "C:\\Boot\\Altiris\\iso\\autoinst.ini", "C:\\Boot\\Altiris\\iso\\autoinst.ini", "") - _defile(p, "C:\\Boot\\Altiris\\iso\\autoutil.exe", "C:\\Boot\\Altiris\\iso\\autoutil.exe", "") - _defile(p, "C:\\Boot\\Altiris\\iso\\autoutil.ini", "C:\\Boot\\Altiris\\iso\\autoutil.ini", "") - _defile(p, "C:\\Boot\\Altiris\\iso\\bcdedit.exe", "C:\\Boot\\Altiris\\iso\\bcdedit.exe", "") - _defile(p, "C:\\Boot\\Altiris\\iso\\bootmgr", "C:\\Boot\\Altiris\\iso\\bootmgr", "") - _defile(p, "C:\\Boot\\Altiris\\iso\\bootsect.exe", "C:\\Boot\\Altiris\\iso\\bootsect.exe", "") - _defreg(p, "Deployment Automation reg.File", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\AutoUtil\\File.XSZ", "autoutil.exe") - _defreg(p, "Deployment Automation reg.Path", "HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\AutoUtil\\Path.XSZ", "%systemdrive%\\boot\\altiris\\iso") - _check(pp) - _conl(_report(pp)) - _wrfile("report.txt", _report(pp)) - } - - function _SYSIO(c, t, P) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return _ln("_SYSIO 1.0") - case "_lib_BEGIN": - return - case "_lib_END": - return - } } +} - function _W(p, A, v) - { - if (isarray(v)) { - if (p) { - delete A[p] - A[p][""] - delete A[p][""] - _movarr(A[p], v) - } - return p - } +#_______________________________________________________________________ +######################################################################## + + +function _W(p, A, v) +{ + if (isarray(v)) { if (p) { delete A[p] - return (A[p] = v) + A[p][""] + delete A[p][""] + _movarr(A[p], v) } - return v + return p } - - function _Zexparr(S, s, t, i) - { - t = "" - if (isarray(S)) { - for (i in S) { - t = t ((isarray(S[i]) ? _Zexparr_i1(i) "\020" _Zexparr_i0(S[i]) "\021\021\020" : _Zexparr_i2(_Zexparr_i3(i) "\021" _Zexparr_i3(S[i])) "\020")) - } - } - if (s != "") { - gsub(/\x1B/, "\033;", s) - gsub(/\x10/, "\0330", s) - t = t "\021\021\020" s - } - gsub(/\x0A/, "\033:", t) - return t + if (p) { + delete A[p] + return (A[p] = v) } + return v +} - function _Zexparr_i0(S, t, i) - { +#_______________________________________________________________________ +function _Zexparr(S, s, t, i) +{ + ############################################## + t = "" + if (isarray(S)) { for (i in S) { t = t ((isarray(S[i]) ? _Zexparr_i1(i) "\020" _Zexparr_i0(S[i]) "\021\021\020" : _Zexparr_i2(_Zexparr_i3(i) "\021" _Zexparr_i3(S[i])) "\020")) } - return t - } - - function _Zexparr_i1(t) - { - gsub(/\x1B/, "\033;", t) - gsub(/\x11/, "\0331", t) - gsub(/\x10/, "\0330", t) - return t } - - function _Zexparr_i2(t) - { - gsub(/\x10/, "\0330", t) + if (s != "") { + gsub(/\x1B/, "\033;", s) + gsub(/\x10/, "\0330", s) + t = t "\021\021\020" s + } + gsub(/\x0A/, "\033:", t) + return t +} + +#_________________________________________________________________ +function _Zexparr_i0(S, t, i) +{ + for (i in S) { + t = t ((isarray(S[i]) ? _Zexparr_i1(i) "\020" _Zexparr_i0(S[i]) "\021\021\020" : _Zexparr_i2(_Zexparr_i3(i) "\021" _Zexparr_i3(S[i])) "\020")) + } + return t +} + +#_________________________________________________________________ +function _Zexparr_i1(t) +{ + gsub(/\x1B/, "\033;", t) + gsub(/\x11/, "\0331", t) + gsub(/\x10/, "\0330", t) + return t +} + +#_________________________________________________________________ +function _Zexparr_i2(t) +{ + gsub(/\x10/, "\0330", t) + return t +} + +#_________________________________________________________________ +function _Zexparr_i3(t) +{ + gsub(/\x1B/, "\033;", t) + gsub(/\x11/, "\0331", t) + return 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)) + gsub(/\x1B\x30/, "\020", t) + gsub(/\x1B\x3B/, "\033", t) return t } +} - function _Zexparr_i3(t) - { - gsub(/\x1B/, "\033;", t) - gsub(/\x11/, "\0331", t) - return t - } +#_________________________________________________________________ +function _Zimparr_i0(A, B, i) +{ + return ((i in A ? A[i] B[i] _Zimparr_i0(A, B, i + 1) : "")) +} - 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)) - gsub(/\x1B\x30/, "\020", t) - gsub(/\x1B\x3B/, "\033", t) - return t +#_________________________________________________________________ +function _Zimparr_i1(D, A, B, i, t, a, n) +{ + while (i in B) { + if ((t = A[i++]) == "\021\021") { + return i } - } - - function _Zimparr_i0(A, B, i) - { - return ((i in A ? A[i] B[i] _Zimparr_i0(A, B, i + 1) : "")) - } - - function _Zimparr_i1(D, A, B, i, t, a, n) - { - while (i in B) { - if ((t = A[i++]) == "\021\021") { - return i + gsub(/\x1B\x30/, "\020", t) + if ((a = index(t, "\021")) > 0) { + if (isarray(D[n = _Zimparr_i2(substr(t, 1, a - 1))])) { + delete D[n] } - gsub(/\x1B\x30/, "\020", t) - if ((a = index(t, "\021")) > 0) { - if (isarray(D[n = _Zimparr_i2(substr(t, 1, a - 1))])) { - delete D[n] - } - D[n] = _Zimparr_i2(substr(t, a + 1)) + D[n] = _Zimparr_i2(substr(t, a + 1)) + } else { + if (! isarray(D[t = _Zimparr_i2(t)])) { + delete D[t] + D[t][""] + delete D[t][""] + } + i = _Zimparr_i1(D[t], A, B, i) + } + } +} + +#_________________________________________________________________ +function _Zimparr_i2(t) +{ + gsub(/\x1B\x31/, "\021", t) + gsub(/\x1B\x3B/, "\033", t) + return t +} + +#_____________________________________________________________________________ +function _Zimport(t, p, A, c, i, n, B) +{ + ############################################## + if (p) { + c = split(t, B, /\x0A/) + for (i = 1; i <= c; i++) { + if ((t = B[i]) == "") { + continue + } + gsub(/\x1B\x3A/, "\n", t) + if (match(t, /^_ERRLOG: /)) { + _tLOG[n = _wLCHLD(p, _N())][""] + delete _tLOG[n][""] + _Zimparr(_tLOG[n], substr(t, 10)) } else { - if (! isarray(D[t = _Zimparr_i2(t)])) { - delete D[t] - D[t][""] - delete D[t][""] + if ((t = _pass(_IMPORT, t, p, A)) != "") { + gsub(/\x1B\x3B/, "\033", t) + _wLCHLD(p, _N(_tSTR, t)) } - i = _Zimparr_i1(D[t], A, B, i) } } - } - - function _Zimparr_i2(t) - { - gsub(/\x1B\x31/, "\021", t) - gsub(/\x1B\x3B/, "\033", t) - return t - } - - function _Zimport(t, p, A, c, i, n, B) - { - if (p) { - c = split(t, B, /\x0A/) - for (i = 1; i <= c; i++) { - if ((t = B[i]) == "") { - continue - } - gsub(/\x1B\x3A/, "\n", t) - if (match(t, /^_ERRLOG: /)) { - _tLOG[n = _wLCHLD(p, _N())][""] - delete _tLOG[n][""] - _Zimparr(_tLOG[n], substr(t, 10)) + return p + } else { + _expout(t) + } +} + +function _acc(A, a, t) +{ + if (t) { + if (_VLDMAXSTRING < length(t) + length(a)) { + if (a) { + if (_VLDMAXSTRING < length(t)) { + A[--A[_ARRPTR]] = a + A[--A[_ARRPTR]] = t } else { - if ((t = _pass(_IMPORT, t, p, A)) != "") { - gsub(/\x1B\x3B/, "\033", t) - _wLCHLD(p, _N(_tSTR, t)) - } + A[--A[_ARRPTR]] = a t } + } else { + A[++A[_ARRLEN]] = t } - return p - } else { - _expout(t) + return "" } + return (a t) } + return a +} - function _acc(A, a, t) - { - if (t) { - if (_VLDMAXSTRING < length(t) + length(a)) { - if (a) { - if (_VLDMAXSTRING < length(t)) { - A[--A[_ARRPTR]] = a - A[--A[_ARRPTR]] = t - } else { - A[--A[_ARRPTR]] = a t - } - } else { - A[++A[_ARRLEN]] = t - } - return "" - } - return (a t) - } - return a +function _accmpu(A, a, n) +{ + if (n) { + return (_mpufn0 = n) } - - function _accmpu(A, a, n) - { - if (n) { - return (_mpufn0 = n) - } - if (_mpuacc) { - if (_VLDMAXSTRING < length(_mpuacc) + length(a)) { - if (a) { - if (_VLDMAXSTRING < length(_mpuacc)) { - A[--A[_ARRLEN]] = a - A[--A[_ARRLEN]] = _mpuacc - } else { - A[--A[_ARRLEN]] = a _mpuacc - } - } else { + if (_mpuacc) { + if (_VLDMAXSTRING < length(_mpuacc) + length(a)) { + if (a) { + if (_VLDMAXSTRING < length(_mpuacc)) { + A[--A[_ARRLEN]] = a A[--A[_ARRLEN]] = _mpuacc + } else { + A[--A[_ARRLEN]] = a _mpuacc } - _mpuacc = "" } else { - _mpuacc = a _mpuacc + A[--A[_ARRLEN]] = _mpuacc } + _mpuacc = "" } else { - _mpuacc = a + _mpuacc = a _mpuacc } + } else { + _mpuacc = a } +} - function _add(S, sf, D, df) - { - if (sf in S) { - if (isarray(S[sf])) { - if (df in D) { - if (isarray(D[df])) { - return _extarr(D[df], S[sf]) - } - delete D[df] - } - D[df][""] - delete D[df][""] - return _extarr(D[df], S[sf]) - } else { +#_______________________________________________________________________ +function _add(S, sf, D, df) +{ + ################################################ + if (sf in S) { + if (isarray(S[sf])) { + if (df in D) { if (isarray(D[df])) { - delete D[df] + return _extarr(D[df], S[sf]) } - D[df] = D[df] S[sf] + delete D[df] } + D[df][""] + delete D[df][""] + return _extarr(D[df], S[sf]) + } else { + if (isarray(D[df])) { + delete D[df] + } + D[df] = D[df] S[sf] } } +} - function _addarr(D, S) - { - if (isarray(S)) { - _addarr_i0(D, S) - } - } - - function _addarr_i0(D, S, i) - { - for (i in S) { - if (isarray(S[i])) { - delete D[i] - D[i][""] - delete D[i][""] - _addarr_i0(D[i], S[i]) - } else { - delete D[i] - D[i] = S[i] - } - } +#_________________________________________________________________ +function _addarr(D, S) +{ + ############################################# + if (isarray(S)) { + _addarr_i0(D, S) } +} - function _addarrmask(D, S, M) - { - for (_addarrmaski0 in M) { - if (_addarrmaski0 in S) { - if (isarray(S[_addarrmaski0])) { - if (! isarray(D[_addarrmaski0])) { - delete D[_addarrmaski0] - D[_addarrmaski0][""] - delete D[_addarrmaski0][""] - } - if (isarray(M[_addarrmaski0])) { - _addarrmask(D[_addarrmaski0], S[_addarrmaski0], M[_addarrmaski0]) - } else { - _extarr_i0(D[_addarrmaski0], S[_addarrmaski0]) - } +#_____________________________________________________ +function _addarr_i0(D, S, i) +{ + for (i in S) { + if (isarray(S[i])) { + delete D[i] + D[i][""] + delete D[i][""] + _addarr_i0(D[i], S[i]) + } else { + delete D[i] + D[i] = S[i] + } + } +} + +#_______________________________________________________________________ +function _addarrmask(D, S, M) +{ + ############################################# + for (_addarrmaski0 in M) { + if (_addarrmaski0 in S) { + if (isarray(S[_addarrmaski0])) { + if (! isarray(D[_addarrmaski0])) { + delete D[_addarrmaski0] + D[_addarrmaski0][""] + delete D[_addarrmaski0][""] + } + if (isarray(M[_addarrmaski0])) { + _addarrmask(D[_addarrmaski0], S[_addarrmaski0], M[_addarrmaski0]) } else { - if (isarray(D[_addarrmaski0])) { - delete D[_addarrmaski0] - } - D[_addarrmaski0] = S[_addarrmaski0] + _extarr_i0(D[_addarrmaski0], S[_addarrmaski0]) } } else { - delete D[_addarrmaski0] + if (isarray(D[_addarrmaski0])) { + delete D[_addarrmaski0] + } + D[_addarrmaski0] = S[_addarrmaski0] } + } else { + delete D[_addarrmaski0] } } +} - 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 - } - a = BINMODE - BINMODE = "rw" - b = ORS - ORS = "" - ERRNO = "" - print(d) >> f - if (ERRNO) { - return "" - } - close(f) - BINMODE = a - ORS = b - if (ERRNO) { - return "" - } - return d - } - function _addlib(f) - { - _addf(_LIBAPI, f) - } +#_______________________________________________________________________ +function _addf(A, f) +{ + ##################################################### + A["B"][""] = A["F"][A["B"][f] = A["B"][""]] = f +} - function _addlist(A, v) - { - A[++A[0]] = v +#___________________________________________________________ +function _addfile(f, d, a, b) +{ + ################################## + if ((f = _wfilerdnehnd(f)) == "" || _filene(f) == "") { + ERRNO = "Filename error" + return } - - function _bearray(A) - { - if (isarray(A) || A == 0 && A == "") { - return 1 - } + a = BINMODE + BINMODE = "rw" + b = ORS + ORS = "" + ERRNO = "" + print(d) >> f + if (ERRNO) { + return "" } - - function _bframe(A, t, p) - { - return _bframe_i0(A, t, p, A[""]) + close(f) + BINMODE = a + ORS = b + if (ERRNO) { + return "" } - - function _bframe_i0(A, t, p, f) - { - return ((f ? _bframe_i0(A, t, p, A[f]) (@f(t, p)) : "")) + return d +} + +#_____________________________________________________________________________ +function _addlib(f) +{ + ########################################################### + _addf(_LIBAPI, f) +} + +#___________________________________________________________________________________ +#################################################################################### + + +#_______________________________________________________________________ +function _addlist(A, v) +{ + ################################################## + A[++A[0]] = v +} + +############################################ +#_______________________________________________________________________ +function _bearray(A) +{ + #################################################### + if (isarray(A) || A == 0 && A == "") { + return 1 } +} - function _cfguid(p, optr, pfx, sfx, hstrcnt, lstrchr) - { - delete _UIDOBL[p] - if (_isptr(optr)) { - if (optr == p) { - delete _UIDOBLV[p] - delete _UIDOBLV[_UIDOBLV[_UIDOBL[p] = p][""] = p][""] - } else { - if (optr in _UIDOBL) { - _UIDOBL[p] = _UIDOBL[optr] - } - } - } - _UIDPFX[p] = (_istr(pfx) ? pfx : "") - _UIDSFX[p] = (_istr(sfx) ? sfx : "") - if (_isptr(hstrcnt)) { - if (hstrcnt != p) { - _UIDCHR[p] = _UIDCHR[_UIDCNT[p] = _UIDCNT[hstrcnt]] - return p - } - hstrcnt = _NOP - } - _UIDCNTL[_UIDCNT[p] = p] = _cfguidchr(p, hstrcnt, lstrchr) - return p - } +#_________________________________________________________________ +function _bframe(A, t, p) +{ + ########################################### + return _bframe_i0(A, t, p, A[""]) +} - function _cfguidchr(p, h, l, H, L) - { - if (_isptr(l)) { - if (l != p) { - return (_UIDCHR[p] = _UIDCHR[l]) - } - _UIDCHR[p] = p - l = _NOP - } - _UIDCHR[p] = p - _splitstr(H, h, _UIDCHRH[_classys]) - _splitstr(L, l, H) - delete _UIDCHRH[_UIDCHRH[p][""] = p][""] - delete _UIDCHRL[_UIDCHRL[p][""] = p][""] - _cfguidh(p, H, L) - return _cfguidl(p, L, L) - } - - function _cfguidh(p, H, L, hi, h, li) - { - for (hi = 1; hi in H; hi++) { - h = H[hi] - for (li = 1; li in L; li++) { - _UIDCHRH[p][h L[li]] - } - } - } +#___________________________________________________________ +function _bframe_i0(A, t, p, f) +{ + return ((f ? _bframe_i0(A, t, p, A[f]) (@f(t, p)) : "")) +} - function _cfguidl(p, H, L, hi, h, hl, li) - { - for (hi = 1; hi in H; hi++) { - h = H[hi] - for (li = 1; li in L; li++) { - hl = _UIDCHRL[p][hl] = h L[li] - } - } - return hl - } +# add to _dumparr: checking that if element is undefined - function _check(p) - { - _dll_check(p) - _file_check(p) - _serv_check(p) - _reg_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 - BINMODE = "rw" - ERRNO = RT = _NUL - c | getline RS - BINMODE = _fio_cmdb - RS = _fio_cmda - if (ERRNO || 0 > (_exitcode = close(c))) { - return (RT = _NOP) - } - return RT - } - function _cmparr(A0, A1, R, a, i) - { - a = 0 - delete R - for (i in A0) { - if (! (i in A1)) { - a++ - R[i] = 0 - } else { - if (A0[i] != A1[i]) { - a++ - R[i] = 2 - } - } - } - for (i in A1) { - if (! (i in A0)) { - a++ - R[i] = 1 - } - } - return a - } - 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 - b = ORS - BINMODE = "rw" - ORS = "" - if (c > 1) { - if ((i = length(t = _tabtospc(A[1], ts, _conlastrln))) < _constatstrln) { - t = t _getchrln(" ", _constatstrln - i) - } - print(t B[1]) > _SYS_STDCON - for (i = 2; i < c; i++) { - print(_tabtospc(A[i], ts) B[i]) > _SYS_STDCON - } - print(_conlastr = _tabtospc(A[c], ts)) > _SYS_STDCON - fflush(_SYS_STDCON) - } else { - print(t = _tabtospc(t, ts, _conlastrln)) > _SYS_STDCON - fflush(_SYS_STDCON) - _conlastr = _conlastr t - } - if ((i = length(_conlastr)) >= _CON_WIDTH) { - _conlastr = substr(_conlastr, 1 + int(i / _CON_WIDTH) * _CON_WIDTH) - } - _conlastrln = length(_conlastr) - if (_constatstr) { - print((t = _constatgtstr(_constatstr, _CON_WIDTH - 1 - _conlastrln)) _CHR["CR"] _conlastr) > _SYS_STDCON - fflush(_SYS_STDCON) - _constatstrln = length(t) - } - BINMODE = a - ORS = b - RLENGTH = d - return r - } - RLENGTH = d - } - function _conin(t, a, b) - { - _constatpush() - _constat() - a = BINMODE - b = RS - BINMODE = "rw" - RS = "\n" - _con(t) - getline t < "CON" - close("CON") - _conlastrln = 0 - _conlastr = "" - gsub(/[\x0D\x0A]+/, "", t) - BINMODE = a - RS = b - _constatpop() - return t - } - function _conl(t, ts) - { - return _con(t ((t ~ /\x0A$/ ? "" : _CHR["EOL"])), ts) - } - function _conline(t, ts) - { - return _con(_chrline(t, ts)) - } - function _conlq(t, ts) - { - return _conl("`" 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) - } - _constatstrln = ln - ln = ORS - a = BINMODE - BINMODE = "rw" - ORS = "" - print(t _CHR["CR"] _conlastr) > _SYS_STDCON - fflush(_SYS_STDCON) - ORS = ln - BINMODE = a - return _constatstr - } - function _constatgtstr(t, ln, a, b) - { - if (ln < 1) { - return "" - } - if ((a = length(t)) <= ln) { - return t - } - if (ln < 11) { - return substr(t, a - ln + 1) - } - if (ln < 19) { - return ("..." substr(t, a - ln + 4)) - } - return (substr(t, 1, b = int((ln - 3) / 2)) "..." substr(t, a - ln + b + 4)) - } - function _constatpop() - { - if (_CONSTATPUSH[0] > 0) { - return _constat(_CONSTATPUSH[_CONSTATPUSH[0]--]) - } - return _constat("") - } - function _constatpush(t, ts) - { - _CONSTATPUSH[++_CONSTATPUSH[0]] = _constatstr - if (t) { - _constat(t, ts) - } - return _constatstr - } - function _creport(p, t, f, z) - { - _[p]["REPORT"] = _[p]["REPORT"] _ln(t ((f == "" ? "" : ": " f))) - } - function _defdir(pp, n, f, v, p) - { - _[p = _wLCHLD(pp, _n("TYPE", "defdir"))]["NAME"] = n - _[p]["DIR"] = f - return p - } - function _defdll(pp, n, rn, p) - { - _[p = _wLCHLD(pp, _n("TYPE", "defdll"))]["NAME"] = n - _[p]["REGPATH"] = _[pp]["REGPATH"] rn - _[p]["ERRHOST"] = pp - return p - } - function _defescarr(D, r, S, i, c, t) - { - if (isarray(S)) { - for (i = 0; i < 256; i++) { - if ((c = _CHR[i]) ~ r) { - D[c] = "\\" S[c] - t = t c - } else { - if (D[c] == "") { - D[c] = c - } - } - } + +#_______________________________________________________________________ +function _cfguid(p, optr, pfx, sfx, hstrcnt, lstrchr) +{ + #################### 0 # + delete _UIDOBL[p] + if (_isptr(optr)) { + if (optr == p) { + delete _UIDOBLV[p] + delete _UIDOBLV[_UIDOBLV[_UIDOBL[p] = p][""] = p][""] } else { - for (i = 0; i < 256; i++) { - if ((c = _CHR[i]) ~ r) { - D[c] = S c - if (S != "") { - t = t c - } - } else { - if (D[c] == "") { - D[c] = c - } - } + if (optr in _UIDOBL) { + _UIDOBL[p] = _UIDOBL[optr] } } - return t } - - function _defile(pp, n, f, v, p) - { - _[p = _wLCHLD(pp, _n("TYPE", "defile"))]["NAME"] = n - _[p]["FILE"] = f - if (! (v == 0 && v == "")) { - _[p]["RQVERSION"] = v + _UIDPFX[p] = (_istr(pfx) ? pfx : "") + _UIDSFX[p] = (_istr(sfx) ? sfx : "") + if (_isptr(hstrcnt)) { + if (hstrcnt != p) { + _UIDCHR[p] = _UIDCHR[_UIDCNT[p] = _UIDCNT[hstrcnt]] + return p } - return p + hstrcnt = _NOP } + _UIDCNTL[_UIDCNT[p] = p] = _cfguidchr(p, hstrcnt, lstrchr) + return 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 == "")) { - _[p]["VALUE"] = v +#_____________________________________________________ +function _cfguidchr(p, h, l, H, L) +{ + if (_isptr(l)) { + if (l != p) { + return (_UIDCHR[p] = _UIDCHR[l]) } + _UIDCHR[p] = p + l = _NOP + } + _UIDCHR[p] = p + _splitstr(H, h, _UIDCHRH[_classys]) + _splitstr(L, l, H) + delete _UIDCHRH[_UIDCHRH[p][""] = p][""] + delete _UIDCHRL[_UIDCHRL[p][""] = p][""] + _cfguidh(p, H, L) + return _cfguidl(p, L, L) +} + +#_______________________________________________ +function _cfguidh(p, H, L, hi, h, li) +{ + for (hi = 1; hi in H; hi++) { + h = H[hi] + for (li = 1; li in L; li++) { + _UIDCHRH[p][h L[li]] + } + } +} + +function _cfguidl(p, H, L, hi, h, hl, li) +{ + for (hi = 1; hi in H; hi++) { + h = H[hi] + for (li = 1; li in L; li++) { + hl = _UIDCHRL[p][hl] = h L[li] + } + } + return hl +} + +#____________________________________________________________________________________________________ +function _check(p) +{ + #################################################################################### + _dll_check(p) + _file_check(p) + _serv_check(p) + _reg_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 + BINMODE = "rw" + ERRNO = RT = _NUL + c | getline RS + BINMODE = _fio_cmdb + RS = _fio_cmda + if (ERRNO || 0 > (_exitcode = close(c))) { + return (RT = _NOP) } - - function _defsolution(pp, n, rn, p) - { - _[p = _wLCHLD(pp, _n("TYPE", "solution"))]["NAME"] = n - _[p]["REGPATH"] = rn - _[p]["ERRHOST"] = pp - return p - } - - function _defsrv(pp, n, f, v, p) - { - _[p = _wLCHLD(pp, _n("TYPE", "defsrv"))]["NAME"] = n - _[p]["SERVNAME"] = f - return 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") - _deletepfx(_WFILEROOTDIR, c) - _deletepfx(_FILEIO_RDTMP, c) - _deletepfx(_FILEIO_RDNETMP, c) - } else { - _conl("HUJ TEBE!") - return "" - } + return RT +} + +#_______________________________________________________________________ +function _cmparr(A0, A1, R, a, i) +{ + ########################################## + a = 0 + delete R + for (i in A0) { + if (! (i in A1)) { + a++ + R[i] = 0 } else { - a = _dir(A, f) - _cmd("del " f " /Q 2>NUL") - for (c in A) { - if (c ~ /\\$/) { - _cmd("rd " c " /S /Q 2>NUL") - _deletepfx(_WFILEROOTDIR, c) - _deletepfx(_FILEIO_RDTMP, c) - } - _deletepfx(_FILEIO_RDNETMP, c) + if (A0[i] != A1[i]) { + a++ + R[i] = 2 } } - return a } - - function _delay(t, a) - { - for (a = 1; a <= t; a++) { - _delayms() - } - } - - function _delayms(a) - { - for (a = 1; a <= _delay_perfmsdelay; a++) { + for (i in A1) { + if (! (i in A0)) { + a++ + R[i] = 1 } } + return a +} - function _deletepfx(A, f, B, le, i) - { - le = length(f) - for (i in A) { - if (substr(toupper(i), 1, le) == f) { - B[i] = A[i] - delete 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 + b = ORS + BINMODE = "rw" + ORS = "" + if (c > 1) { + if ((i = length(t = _tabtospc(A[1], ts, _conlastrln))) < _constatstrln) { + t = t _getchrln(" ", _constatstrln - i) } + print(t B[1]) > _SYS_STDCON + for (i = 2; i < c; i++) { + print(_tabtospc(A[i], ts) B[i]) > _SYS_STDCON + } + print(_conlastr = _tabtospc(A[c], ts)) > _SYS_STDCON + fflush(_SYS_STDCON) + } else { + print(t = _tabtospc(t, ts, _conlastrln)) > _SYS_STDCON + fflush(_SYS_STDCON) + _conlastr = _conlastr t + } + if ((i = length(_conlastr)) >= _CON_WIDTH) { + _conlastr = substr(_conlastr, 1 + int(i / _CON_WIDTH) * _CON_WIDTH) } + _conlastrln = length(_conlastr) + if (_constatstr) { + print((t = _constatgtstr(_constatstr, _CON_WIDTH - 1 - _conlastrln)) _CHR["CR"] _conlastr) > _SYS_STDCON + fflush(_SYS_STDCON) + _constatstrln = length(t) + } + BINMODE = a + ORS = b + RLENGTH = d + return r } - - 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] + RLENGTH = d +} + +#_______________________________________________________________________ +function _conin(t, a, b) +{ + ################################################# + _constatpush() + _constat() + a = BINMODE + b = RS + BINMODE = "rw" + RS = "\n" + _con(t) + getline t < "CON" + close("CON") + _conlastrln = 0 + _conlastr = "" + gsub(/[\x0D\x0A]+/, "", t) + BINMODE = a + RS = b + _constatpop() + return t +} + +#_______________________________________________________________________ +function _conl(t, ts) +{ + #################################################### + return _con(t ((t ~ /\x0A$/ ? "" : _CHR["EOL"])), ts) +} + +#_______________________________________________________________________ +function _conline(t, ts) +{ + ################################################# + return _con(_chrline(t, ts)) +} + +#___________________________________________________________________________________ +#################################################################################### + + + +function _conlq(t, ts) +{ + return _conl("`" 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) + } + _constatstrln = ln + ln = ORS + a = BINMODE + BINMODE = "rw" + ORS = "" + print(t _CHR["CR"] _conlastr) > _SYS_STDCON + fflush(_SYS_STDCON) + ORS = ln + BINMODE = a + return _constatstr +} + +#_________________________________________________________________ +function _constatgtstr(t, ln, a, b) +{ + if (ln < 1) { + return "" } - - function _deluid(p) - { - if (p in _CLASSPTR) { - _deluida0 = _CLASSPTR[p] - if (_deluida0 in _UIDOBL) { - _UIDOBLV[_UIDOBL[_deluida0]][p] - } - } - delete _CLASSPTR[p] - return _deluida0 + if ((a = length(t)) <= ln) { + return t } - - function _dir(A, rd, i, r, f, ds, pf, B, C) - { - delete A - gsub(/(^[ \t]*)|([ \t]*$)/, "", rd) - if (rd == "") { - return "" + if (ln < 11) { + return substr(t, a - ln + 1) + } + if (ln < 19) { + return ("..." substr(t, a - ln + 4)) + } + return (substr(t, 1, b = int((ln - 3) / 2)) "..." substr(t, a - ln + b + 4)) +} + +#_______________________________________________________________________ +function _constatpop() +{ + ################################################## + if (_CONSTATPUSH[0] > 0) { + return _constat(_CONSTATPUSH[_CONSTATPUSH[0]--]) + } + return _constat("") +} + +#_______________________________________________________________________ +function _constatpush(t, ts) +{ + ############################################# + _CONSTATPUSH[++_CONSTATPUSH[0]] = _constatstr + if (t) { + _constat(t, ts) + } + return _constatstr +} + +#___________________________________________________________________________________ +function _creport(p, t, f, z) +{ + _[p]["REPORT"] = _[p]["REPORT"] _ln(t ((f == "" ? "" : ": " f))) +} + +#_________________________________________________________________________________________ +function _defdir(pp, n, f, v, p) +{ + ############################################################# + _[p = _wLCHLD(pp, _n("TYPE", "defdir"))]["NAME"] = n + _[p]["DIR"] = f + return p +} + +#_________________________________________________________________________________________ +function _defdll(pp, n, rn, p) +{ + ############################################################## + _[p = _wLCHLD(pp, _n("TYPE", "defdll"))]["NAME"] = n + _[p]["REGPATH"] = _[pp]["REGPATH"] rn + _[p]["ERRHOST"] = pp + return p +} + +#___________________________________________________________ +function _defescarr(D, r, S, i, c, t) +{ + if (isarray(S)) { + for (i = 0; i < 256; i++) { + if ((c = _CHR[i]) ~ r) { + D[c] = "\\" S[c] + t = t c + } else { + if (D[c] == "") { + D[c] = c + } + } } - i = split(_cmd("dir \"" rd "\" 2>NUL"), B, /\x0D?\x0A/) - 3 - pf = (match(B[4], /Directory of ([^\x00-\x1F]+)/, C) ? C[1] ((C[1] ~ /\\$/ ? "" : "\\")) : "") - for (r = 0; i > 5; i--) { - if (match(B[i], /^([^ \t]*)[ \t]+([^ \t]*)[ \t]+((<DIR>)|([0-9\,]+))[ \t]+([^\x00-\x1F]+)$/, C)) { - if (C[6] !~ /^\.\.?$/) { - if (C[4]) { - ds = "D " - } else { - ds = C[5] " " - gsub(/\,/, "", ds) - } - if ((f = _filepath(pf C[6] ((C[4] ? "\\" : "")))) != "") { - A[f] = ds C[1] " " C[2] - r++ - } + } else { + for (i = 0; i < 256; i++) { + if ((c = _CHR[i]) ~ r) { + D[c] = S c + if (S != "") { + t = t c + } + } else { + if (D[c] == "") { + D[c] = c } } } - return r } - - function _dirtree(A, f, B) - { - gsub(/(^[ \t]*)|([ \t]*$)/, "", f) - delete A - A[""] - delete A[""] - _dirtree_i0(B, 8, split(_cmd("dir \"" f "\" /-C /S 2>NUL"), B, /\x0D?\x0A/), A, f = _filerd(f)) - return f + return t +} + +#_________________________________________________________________________________________ +function _defile(pp, n, f, v, p) +{ + ############################################################# + _[p = _wLCHLD(pp, _n("TYPE", "defile"))]["NAME"] = n + _[p]["FILE"] = f + if (! (v == 0 && v == "")) { + _[p]["RQVERSION"] = v + } + return 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 == "")) { + _[p]["VALUE"] = v + } +} + +#_______________________________________________________________________________________________ +function _defsolution(pp, n, rn, p) +{ + ############################################################### + _[p = _wLCHLD(pp, _n("TYPE", "solution"))]["NAME"] = n + _[p]["REGPATH"] = rn + _[p]["ERRHOST"] = pp + return p +} + +#_________________________________________________________________________________________ +function _defsrv(pp, n, f, v, p) +{ + ############################################################# + _[p = _wLCHLD(pp, _n("TYPE", "defsrv"))]["NAME"] = n + _[p]["SERVNAME"] = f + return 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") + _deletepfx(_WFILEROOTDIR, c) + _deletepfx(_FILEIO_RDTMP, c) + _deletepfx(_FILEIO_RDNETMP, c) + } else { + _conl("HUJ TEBE!") + return "" + } + } else { + a = _dir(A, f) + _cmd("del " f " /Q 2>NUL") + for (c in A) { + if (c ~ /\\$/) { + _cmd("rd " c " /S /Q 2>NUL") + _deletepfx(_WFILEROOTDIR, c) + _deletepfx(_FILEIO_RDTMP, c) + } + _deletepfx(_FILEIO_RDNETMP, c) + } + } + return a +} + +#_______________________________________________________________________ +function _delay(t, a) +{ + ################################################### + for (a = 1; a <= t; a++) { + _delayms() + } +} + +#_________________________________________________________________ +function _delayms(a) +{ + ############################################# + for (a = 1; a <= _delay_perfmsdelay; a++) { + } +} + +#_______________________________________________________________________ +function _deletepfx(A, f, B, le, i) +{ + ######################################## + le = length(f) + for (i in A) { + if (substr(toupper(i), 1, le) == f) { + B[i] = A[i] + delete A[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] +} + +#_______________________________________________________________________ +function _deluid(p) +{ + ################################################# 1 # + if (p in _CLASSPTR) { + _deluida0 = _CLASSPTR[p] + if (_deluida0 in _UIDOBL) { + _UIDOBLV[_UIDOBL[_deluida0]][p] + } + } + delete _CLASSPTR[p] + return _deluida0 +} + +#_______________________________________________________________________ +function _dir(A, rd, i, r, f, ds, pf, B, C) +{ + #################################### + delete A + gsub(/(^[ \t]*)|([ \t]*$)/, "", rd) + if (rd == "") { + return "" } - - function _dirtree_i0(B, i, c, A, f, lf, a, C) - { - delete A[f] - A[f][0] - delete A[f][0] - lf = length(f) - for (; i <= c; ) { - if (match(B[i], /^[ \t]*Directory of (.+)/, C)) { - if (substr(a = _filerd(C[1] "\\"), 1, lf) == f) { - i = _dirtree_i0(B, i + 4, c, A[f], a) + i = split(_cmd("dir \"" rd "\" 2>NUL"), B, /\x0D?\x0A/) - 3 + pf = (match(B[4], /Directory of ([^\x00-\x1F]+)/, C) ? C[1] ((C[1] ~ /\\$/ ? "" : "\\")) : "") + for (r = 0; i > 5; i--) { + if (match(B[i], /^([^ \t]*)[ \t]+([^ \t]*)[ \t]+((<DIR>)|([0-9\,]+))[ \t]+([^\x00-\x1F]+)$/, C)) { + if (C[6] !~ /^\.\.?$/) { + if (C[4]) { + ds = "D " } else { - return i + ds = C[5] " " + gsub(/\,/, "", ds) } - } else { - if (match(B[i++], /^([^ \t\-]+)\-([^ \t\-]+)\-([^ \t]+)[ \t]+([^ \t]+)[ \t]+([0-9]+)[ \t]+(.+)$/, C)) { - A[f][f C[6]] = C[5] " " C[1] "/" _CHR["MONTH"][C[2]] "/" C[3] " " C[4] + if ((f = _filepath(pf C[6] ((C[4] ? "\\" : "")))) != "") { + A[f] = ds C[1] " " C[2] + r++ } } } - return i } - - function _dll_check(pp) - { - _dllchktv = "" - _missfl = 1 - _tframe("_dll_check_i0", pp, _REG, pp) - 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 "'") + return r +} + +#_________________________________________________________________ +function _dirtree(A, f, B) +{ + ######################################### + gsub(/(^[ \t]*)|([ \t]*$)/, "", f) + delete A + A[""] + delete A[""] + _dirtree_i0(B, 8, split(_cmd("dir \"" f "\" /-C /S 2>NUL"), B, /\x0D?\x0A/), A, f = _filerd(f)) + return f +} + +#___________________________________________________________ +function _dirtree_i0(B, i, c, A, f, lf, a, C) +{ + delete A[f] + A[f][0] + delete A[f][0] + lf = length(f) + for (; i <= c; ) { + if (match(B[i], /^[ \t]*Directory of (.+)/, C)) { + if (substr(a = _filerd(C[1] "\\"), 1, lf) == f) { + i = _dirtree_i0(B, i + 4, c, A[f], a) + } else { + return i } } else { - if (! _missfl) { - _creport(pp, "agent not detected in registry") - } else { - _dllerr(pp, "agent not detected in registry but some registry entries exist:") - _tframe("_dll_check_i1", pp, pp) + if (match(B[i++], /^([^ \t\-]+)\-([^ \t\-]+)\-([^ \t]+)[ \t]+([^ \t]+)[ \t]+([0-9]+)[ \t]+(.+)$/, C)) { + A[f][f C[6]] = C[5] " " C[1] "/" _CHR["MONTH"][C[2]] "/" C[3] " " C[4] } } } + return i +} - function _dll_check_i0(p, R, pp, p2, i, i2, r, f, v, rs, d, tv, tf) - { - if (_[p]["TYPE"] == "defdll") { - r = toupper(_[p]["REGPATH"]) - rs = 0 - tf = 0 - tv = "" - for (i in R) { - if (toupper(substr(i, 1, length(r))) == r) { - if ((_chka0 = substr(i, 1 + length(r), 1)) == "" || _chka0 == "\\") { +#_______________________________________________________________________ +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 + 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 "'") + } + } else { + if (! _missfl) { + _creport(pp, "agent not detected in registry") + } else { + _dllerr(pp, "agent not detected in registry but some registry entries exist:") + _tframe("_dll_check_i1", pp, pp) + } + } +} + +#_______________________________________________ +function _dll_check_i0(p, R, pp, p2, i, i2, r, f, v, rs, d, tv, tf) +{ + if (_[p]["TYPE"] == "defdll") { + r = toupper(_[p]["REGPATH"]) + rs = 0 + tf = 0 + tv = "" + for (i in R) { + if (toupper(substr(i, 1, length(r))) == r) { + if ((_chka0 = substr(i, 1 + length(r), 1)) == "" || _chka0 == "\\") { + rs = 1 + _missfl = 1 + _[p]["." substr(gensub(/\....$/, "", 1, i), i2 = 2 + length(r), length(i) - i2 + 1)] = R[i] + if (chka0 != "") { rs = 1 - _missfl = 1 - _[p]["." substr(gensub(/\....$/, "", 1, i), i2 = 2 + length(r), length(i) - i2 + 1)] = R[i] - if (chka0 != "") { - rs = 1 - } } } } - if (rs) { - if ((i = ".Install Path") in _[p] && (i = ".Product Version") in _[p]) { - _[p]["STATUS"] = "PRESENT" - f = _[p][".Install Path"] - v = _[p][".Product Version"] - if (! (".Module" in _[p])) { - _[pp][".Product Version"] = v - _VAR["HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Deployment\\AgentInstallPath.STR"] = f - _[pp]["AGENT"] = p - _creport("OK: DLL DETECTED(" v "): " substr(_[p]["NAME"], 1, 112)) + } + #{ 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" + f = _[p][".Install Path"] + v = _[p][".Product Version"] + if (! (".Module" in _[p])) { + _[pp][".Product Version"] = v + _VAR["HKEY_LOCAL_MACHINE\\SOFTWARE\\Altiris\\Deployment\\AgentInstallPath.STR"] = f + _[pp]["AGENT"] = p + _creport("OK: DLL DETECTED(" v "): " substr(_[p]["NAME"], 1, 112)) + } else { + if (_dllchktv == "") { + _dllchktv = v } else { - if (_dllchktv == "") { - _dllchktv = v - } else { - if (v != _dllchktv) { - return _dllerr(p, "different versions detected: " _dllchktv "!=" v "'") - } - } - ERRNO = "" - if (_th1(_[p]["DATA"] = _rdfile(f), ERRNO)) { - delete _[p]["DATA"] - return _dllerr(p, "read lib: " ERRNO, f) - } - if (v != (_[p]["VERSION"] = _getfilever(f))) { - return _dllerr(p, "library file version mismatch: ==`" _[p]["VERSION"] "'; !=`" v "'", f) + if (v != _dllchktv) { + return _dllerr(p, "different versions detected: " _dllchktv "!=" v "'") } - _creport(p, "OK: LIBRARY DETECTED(" v "): " substr(f, 1, 100)) } - } else { - tf = 1 - _dllerr(p, "registry corrupt: `" i "' not present") + ERRNO = "" + if (_th1(_[p]["DATA"] = _rdfile(f), ERRNO)) { + delete _[p]["DATA"] + return _dllerr(p, "read lib: " ERRNO, f) + } + if (v != (_[p]["VERSION"] = _getfilever(f))) { + return _dllerr(p, "library file version mismatch: ==`" _[p]["VERSION"] "'; !=`" v "'", f) + } + _creport(p, "OK: LIBRARY DETECTED(" v "): " substr(f, 1, 100)) } } else { - _[p]["STATUS"] = "MISSED" + tf = 1 + _dllerr(p, "registry corrupt: `" i "' not present") } + } else { + _[p]["STATUS"] = "MISSED" } } +} - function _dll_check_i1(p, pp, p1, p2, p3, i) - { - if (_[p]["TYPE"] == "defdll") { - for (i in _[p]) { - if (i ~ /^\./) { - _dllerr(pp, " " _[p]["REGPATH"] "\\" substr(i, 2)) - } +#_______________________________________________ +function _dll_check_i1(p, pp, p1, p2, p3, i) +{ + if (_[p]["TYPE"] == "defdll") { + for (i in _[p]) { + if (i ~ /^\./) { + _dllerr(pp, " " _[p]["REGPATH"] "\\" substr(i, 2)) } } } +} - function _dllerr(p, t, f) - { - if (t !~ /\x00/) { - t = "ERROR: \000" t - } - _errfl = 1 - _[p]["ERROR"] = _[p]["ERROR"] _ln(t ((f == "" ? "" : ": " f))) +#___________________________________________________________________________________ +function _dllerr(p, t, f) +{ + if (t !~ /\x00/) { + t = "ERROR: \000" t } + _errfl = 1 + _[p]["ERROR"] = _[p]["ERROR"] _ln(t ((f == "" ? "" : ": " f))) +} - function _drawuid(p, cn, ch, o) - { - _conl("uid: " p) - _conl("\toblptr: " ((p in _UIDOBL ? _UIDOBL[p] "'" : "-"))) - if (p in _UIDOBL) { - if (! _isptr(o = _UIDOBL[p])) { - _conl(">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> oblptr not pointer") - } - if (! isarray(_UIDOBLV[o])) { - _conl(">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> no OBLV array at ptr") - } +function _drawuid(p, cn, ch, o) +{ + _conl("uid: " p) + _conl("\toblptr: " ((p in _UIDOBL ? _UIDOBL[p] "'" : "-"))) + if (p in _UIDOBL) { + if (! _isptr(o = _UIDOBL[p])) { + _conl(">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> oblptr not pointer") } - _conl("\tprefix: " ((p in _UIDPFX ? _UIDPFX[p] "'" : "-"))) - _conl("\tsuffix: " ((p in _UIDSFX ? _UIDSFX[p] "'" : "-"))) - _conl("\tcounters: " (cn = (p in _UIDCNT ? _UIDCNT[p] "'" : "-"))) - if (cn != "-") { - _conl("\t\tcntrL: " _UIDCNTL[_UIDCNT[p]] "'") - _conl("\t\tcntrH: " _UIDCNTH[_UIDCNT[p]] "'") - } - _conl("\tcharset: " (ch = (p in _UIDCHR ? _UIDCHR[p] "'" : "-"))) - if (ch != "-") { - _conl("chrH: ") - _conl(_dumparr(_UIDCHRH[_UIDCHR[p]])) - _conl() - _conl("chrL: ") - _conl(_dumparr(_UIDCHRL[_UIDCHR[p]])) - _conl() - } - } - - function _dumparr(A, t, lv, a) - { - b = PROCINFO["sorted_in"] - PROCINFO["sorted_in"] = "_lengthsort" - if (isarray(A)) { - delete _DUMPARR - _dumparrc = _dumparrd = "" - _dumparr_i1(A, lv = ((lv == "" ? 16 : (lv == 0 || lv + 0 != 0 ? lv : (lv == "-*" ? -3 : (lv ~ /^\+?\*$/ ? 3 : 16))))) + 0, (lv < 0 ? -1 : 1), 0, _tabtospc(t)) - PROCINFO["sorted_in"] = a - return _retarrd(_DUMPARR, _dumparrd, _dumparrd = "") - } - } - - function _dumparr_i1(A, lv, ls, ln, t, t2, i, a, f) - { - t2 = _getchrln(" ", length(t)) - if (ln == lv) { - if (ls > 0) { - for (i in A) { - ++a - } - } else { - for (i in A) { - (isarray(A[i]) ? ++a : "") - } - } - if (length(_dumparrd = _dumparrd t ((a > 0 ? " ... (x" a ")" : "")) _CHR["EOL"]) > 262144) { - _DUMPARR[++_dumparrc] = _dumparrd - _dumparrd = "" - } - return + if (! isarray(_UIDOBLV[o])) { + _conl(">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> no OBLV array at ptr") } - if (ls >= 0) { + } + _conl("\tprefix: " ((p in _UIDPFX ? _UIDPFX[p] "'" : "-"))) + _conl("\tsuffix: " ((p in _UIDSFX ? _UIDSFX[p] "'" : "-"))) + _conl("\tcounters: " (cn = (p in _UIDCNT ? _UIDCNT[p] "'" : "-"))) + if (cn != "-") { + _conl("\t\tcntrL: " _UIDCNTL[_UIDCNT[p]] "'") + _conl("\t\tcntrH: " _UIDCNTH[_UIDCNT[p]] "'") + } + _conl("\tcharset: " (ch = (p in _UIDCHR ? _UIDCHR[p] "'" : "-"))) + if (ch != "-") { + _conl("chrH: ") + _conl(_dumparr(_UIDCHRH[_UIDCHR[p]])) + _conl() + _conl("chrL: ") + _conl(_dumparr(_UIDCHRL[_UIDCHR[p]])) + _conl() + } +} + +#_______________________________________________________________________ +function _dumparr(A, t, lv, a) +{ + ############################################ + b = PROCINFO["sorted_in"] + PROCINFO["sorted_in"] = "_lengthsort" + if (isarray(A)) { + delete _DUMPARR + _dumparrc = _dumparrd = "" + _dumparr_i1(A, lv = ((lv == "" ? 16 : (lv == 0 || lv + 0 != 0 ? lv : (lv == "-*" ? -3 : (lv ~ /^\+?\*$/ ? 3 : 16))))) + 0, (lv < 0 ? -1 : 1), 0, _tabtospc(t)) + PROCINFO["sorted_in"] = a + return _retarrd(_DUMPARR, _dumparrd, _dumparrd = "") + } +} + +#___________________________________________________________ +function _dumparr_i1(A, lv, ls, ln, t, t2, i, a, f) +{ + t2 = _getchrln(" ", length(t)) + if (ln == lv) { + if (ls > 0) { for (i in A) { - if (! isarray(A[i])) { - if (length(_dumparrd = _dumparrd ((f ? t2 : t _nop(f = 1))) "[" i "]=" A[i] "'" _CHR["EOL"]) > 262144) { - _DUMPARR[++_dumparrc] = _dumparrd - _dumparrd = "" - } - } + ++a } - } - for (i in A) { - if (isarray(A[i])) { - _dumparr_i1(A[i], lv, ls, ln + ls, _th0((f ? t2 : t), f = 1) "[" i "]") + } else { + for (i in A) { + (isarray(A[i]) ? ++a : "") } } - if (! f) { - if (length(_dumparrd = _dumparrd t _CHR["EOL"]) > 262144) { - _DUMPARR[++_dumparrc] = _dumparrd - _dumparrd = "" - } + if (length(_dumparrd = _dumparrd t ((a > 0 ? " ... (x" a ")" : "")) _CHR["EOL"]) > 262144) { + _DUMPARR[++_dumparrc] = _dumparrd + _dumparrd = "" } + return } - - 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 " "))) + if (ls >= 0) { + for (i in A) { + if (! isarray(A[i])) { + if (length(_dumparrd = _dumparrd ((f ? t2 : t _nop(f = 1))) "[" i "]=" A[i] "'" _CHR["EOL"]) > 262144) { + _DUMPARR[++_dumparrc] = _dumparrd + _dumparrd = "" + } + } } - return s } - - function _dumpobj_i0(p, f, t) - { - if (f == "") { - return _dumpobj_i2(p, t) + for (i in A) { + if (isarray(A[i])) { + _dumparr_i1(A[i], lv, ls, ln + ls, _th0((f ? t2 : t), f = 1) "[" i "]") } - if (f == 0) { - return _dumpobj_i1(p, t " ") + } + if (! f) { + if (length(_dumparrd = _dumparrd t _CHR["EOL"]) > 262144) { + _DUMPARR[++_dumparrc] = _dumparrd + _dumparrd = "" } - return (_dumpobj_i1(p, t " ") _dumpobj_i2(p, _getchrln(" ", length(t)))) } +} - function _dumpobj_i1(p, t) - { - return _ln(t substr(((p in _tPREV ? "\253" _tPREV[p] : "")) " ", 1, 7) " " substr(((p in _tPARENT ? "\210" _tPARENT[p] : "")) " ", 1, 7) " " substr(((p in _tFCHLD ? _tFCHLD[p] : "")) "\205" ((p in _tQCHLD ? " (" _tQCHLD[p] ") " : "\205")) "\205" ((p in _tLCHLD ? _tLCHLD[p] : "")) " ", 1, 22) substr(((p in _tNEXT ? "\273" _tNEXT[p] : "")) " ", 1, 8)) +#___________________________________________________________________________________ +#################################################################################### + + +#___________________________________________________________________________________ +# OTHER tFUNCTIONs ################################################################# + +#_____________________________________________________________________________ +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 " "))) } + return s +} - function _dumpobj_i2(p, t) - { - return (_dumpobj_i3(_[p], t " ") _dumpobj_i3(_ptr[p], _getchrln(" ", length(t)) "`", "`")) +#___________________________________________________________ +function _dumpobj_i0(p, f, t) +{ + if (f == "") { + return _dumpobj_i2(p, t) } + if (f == 0) { + return _dumpobj_i1(p, t " ") + } + return (_dumpobj_i1(p, t " ") _dumpobj_i2(p, _getchrln(" ", length(t)))) +} + +#___________________________________________________________ +function _dumpobj_i1(p, t) +{ + return _ln(t substr(((p in _tPREV ? "\253" _tPREV[p] : "")) " ", 1, 7) " " substr(((p in _tPARENT ? "\210" _tPARENT[p] : "")) " ", 1, 7) " " substr(((p in _tFCHLD ? _tFCHLD[p] : "")) "\205" ((p in _tQCHLD ? " (" _tQCHLD[p] ") " : "\205")) "\205" ((p in _tLCHLD ? _tLCHLD[p] : "")) " ", 1, 22) substr(((p in _tNEXT ? "\273" _tNEXT[p] : "")) " ", 1, 8)) +} - function _dumpobj_i3(A, t, p, e, s, i, t2) - { - if (isarray(A)) { +#___________________________________________________________ +function _dumpobj_i2(p, t) +{ + return (_dumpobj_i3(_[p], t " ") _dumpobj_i3(_ptr[p], _getchrln(" ", length(t)) "`", "`")) +} + +#___________________________________________________________ +function _dumpobj_i3(A, t, p, e, s, i, t2) +{ + if (isarray(A)) { + for (i in A) { + t2 = _getchrln(" ", length(t)) for (i in A) { - t2 = _getchrln(" ", length(t)) - for (i in A) { - if (isarray(A[i])) { - s = s _dumpobj_i3(A[i], t "[" _dumpobj_i4(i) "]", p, _ln()) - } else { - s = s _ln(t "[" _dumpobj_i4(i) "]=" p _dumpobj_i4(A[i]) "'") - } - t = t2 + if (isarray(A[i])) { + s = s _dumpobj_i3(A[i], t "[" _dumpobj_i4(i) "]", p, _ln()) + } else { + s = s _ln(t "[" _dumpobj_i4(i) "]=" p _dumpobj_i4(A[i]) "'") } - return s + t = t2 } - return ((e == "" ? "" : t e)) + return s } - if (A == 0 && A == "") { - return - } - return _ln(t "=" _dumpobj_i4(p A) "'") + return ((e == "" ? "" : t e)) } - - function _dumpobj_i4(t) - { - if (length(t) > 64) { - return (substr(t, 1, 28) " ... " substr(t, length(t) - 28)) - } - return t - } - - function _dumpobj_nc(p, f, t) - { - return _dumpobj_i0(p, f, t "." p "{ ") + if (A == 0 && A == "") { + return } - - function _dumpobjm(p, f, t, s, t2) - { - t2 = _getchrln(" ", length(t)) - do { - s = s _dumpobj(p, f, t) - t = t2 - } while (p = _rNEXT(p)) - return s + return _ln(t "=" _dumpobj_i4(p A) "'") +} + +#___________________________________________________________ +function _dumpobj_i4(t) +{ + if (length(t) > 64) { + return (substr(t, 1, 28) " ... " substr(t, length(t) - 28)) + } + return 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) + t = t2 + } while (p = _rNEXT(p)) + return s +} + +#_________________________________________________________________ +function _dumpobjm_nc(p, f, t, s, t2) +{ + ################################ + t2 = _getchrln(" ", length(t)) + do { + s = s _dumpobj_nc(p, f, t) + t = t2 + } while (p = _rNEXT(p)) + return s +} + +function _dumpuidgen(p, pd, pc, ps) +{ + _conline("#" ++cntdm ": " p "'") + _conl() + if (p in _tuidel) { + _conl("DEL: " _var(pd = _tuidel[p])) + _conl(_dumparr(_tUIDEL[pd]) _ln()) + } + _conl("PFX: " _tUIDPFX[p] "'") + _conl("SFX: " _tUIDSFX[p] "'") + _conl("COUNT: " ((p in _tuidcnt ? (pc = _tuidcnt[p]) "'" : _th0("-", pc = -2)))) + _con("CHARS: ") + if (p in _tuidchr) { + _conl((ps = _tuidchr[p]) "'") + _conl("HCHR: " ((pc == -2 ? "-" : _tUIDCNTH[pc] "'"))) + _conl(_dumparr(_tUIDCHRH[ps]) _ln()) + _conl("LCHR: " ((pc == -2 ? "-" : _tUIDCNTL[pc] "'"))) + _conl(_dumparr(_tUIDCHRL[ps]) _ln()) + } else { + _conl("-") + } +} + +#_____________________________________________________________________________ +function _dumpval(v, n) +{ + _dumpstr = _dumpstr (v = _ln(((n == 0 && n == "" ? "RET" : n)) ": " ((v == 0 && v == "" ? "-" : v "'")))) + return v +} + +######################################################## + +function _eXTFN(c, t, P) +{ + switch (c) { + case "_lib_CMDLN": + return t + #___________________________________________________________ + + case "_lib_APPLY": + return + #___________________________________________________________ + + case "_lib_HELP": + return + #___________________________________________________________ + + case "_lib_NAMEVER": + return _ln("_extfn 1.0") + #___________________________________________________________ + + case "_lib_BEGIN": + return + #___________________________________________________________ + + case "_lib_END": + return } - - function _dumpobjm_nc(p, f, t, s, t2) - { - t2 = _getchrln(" ", length(t)) - do { - s = s _dumpobj_nc(p, f, t) - t = t2 - } while (p = _rNEXT(p)) - return s +} + +#_________________________________________________________________ +function _endpass(t) +{ + _endpass_v0 = t +} + +#_______________________________________________________________________ +function _err(t, a, b) +{ + ################################################### + a = BINMODE + b = ORS + BINMODE = "rw" + ORS = "" + print(t) > _SYS_STDERR + fflush(_SYS_STDERR) + BINMODE = a + ORS = b + return t +} + +#_________________________________________________________________ +function _errnl(t) +{ + ################################################ + return _err(t ((t ~ /\x0A$/ ? "" : _CHR["EOL"]))) +} + +#_______________________________________________________________________ +function _error(t, d, A) +{ + ################################################# + if (_ERRLOG_EF) { + A["TYPE"] = "ERROR" + A["TEXT"] = t + _log(A, d) + } +} + +#_______________________________________________________________________ +function _exit(c) +{ + ####################################################### + exit c +} + +#_____________________________________________________________________________ +function _export_data(t, i, A) +{ + ################################################# + A["DATA"] = t + A["ID"] = i + _expout("_DATA: " _Zexparr(A) "\n") +} + +#___________________________________________________________________________________ +#################################################################################### + +#_____________________________________________________________________________ +function _expout(t, d, a, b) +{ + #################################################### + a = BINMODE + b = ORS + BINMODE = "rw" + ORS = "" + print(t) > ((d ? d : d = _errlog_file)) + fflush(d) + BINMODE = a + ORS = b +} + +#_________________________________________________________________________________________ +########################################################################################## + + + + + + + + +function _extfn_init() +{ + ############################################################## + + _formatstrs_init() + _formatstrd_init() + _formatrexp_init() + _unformatstr_init() + _mac_init() +} + +function _faccl_i0(A, t, p, P, f, r) +{ + f = r = "" + if (isarray(A)) { + while (f = A[f]) { + r = (@f(t, p, P)) r + } + } + return r +} + +function _faccr_i0(A, t, p, P, f, r) +{ + f = r = "" + if (isarray(A)) { + while (f = A[f]) { + r = r @f(t, p, P) + } + } + return r +} + +#_______________________________________________________________________ +function _fatal(t, d, A) +{ + ################################################# + if (_ERRLOG_FF) { + A["TYPE"] = "FATAL" + A["TEXT"] = t + _log(A, d) + } + if (! d) { + exit + } +} + +function _fbaccl(A, t, p, P) +{ + return _faccl_i0(A["B"], t, p, P) +} + +function _fbaccr(A, t, p, P) +{ + return _faccr_i0(A["B"], t, p, P) +} + +function _ffaccl(A, t, p, P) +{ + return _faccl_i0(A["F"], t, p, P) +} + +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[""]) +} + +#___________________________________________________________ +function _fframe_i0(A, t, p, f) +{ + return ((f ? (@f(t, p)) _fframe_i0(A, t, p, A[f]) : "")) +} + +#_________________________________________________________________ +function _file(f) +{ + ################################################# + if ((f = _filerdnehnd(f)) == "") { + return "" } - - function _dumpuidgen(p, pd, pc, ps) - { - _conline("#" ++cntdm ": " p "'") - _conl() - if (p in _tuidel) { - _conl("DEL: " _var(pd = _tuidel[p])) - _conl(_dumparr(_tUIDEL[pd]) _ln()) - } - _conl("PFX: " _tUIDPFX[p] "'") - _conl("SFX: " _tUIDSFX[p] "'") - _conl("COUNT: " ((p in _tuidcnt ? (pc = _tuidcnt[p]) "'" : _th0("-", pc = -2)))) - _con("CHARS: ") - if (p in _tuidchr) { - _conl((ps = _tuidchr[p]) "'") - _conl("HCHR: " ((pc == -2 ? "-" : _tUIDCNTH[pc] "'"))) - _conl(_dumparr(_tUIDCHRH[ps]) _ln()) - _conl("LCHR: " ((pc == -2 ? "-" : _tUIDCNTL[pc] "'"))) - _conl(_dumparr(_tUIDCHRL[ps]) _ln()) + return ((f in _FILEXT ? _FILEXT[f] : "")) +} + +#_______________________________________________________________________ +function _file_check(p) +{ + if (1 || "AGENT" in _[p]) { + _tframe("_file_check_i0", p, p) + } +} + +#_______________________________________________ +function _file_check_i0(p, pp, p1, p2, f, v) +{ + if (_[p]["TYPE"] == "defile") { + f = _[p]["FILE"] + f = ((match(f, /^.:/) ? "" : _[_[pp]["AGENT"]][".Install Path"] "\\")) _[p]["FILE"] + if ("RQVERSION" in _[p]) { + v = _[p]["RQVERSION"] } else { - _conl("-") + v = _[pp][".Product Version"] } - } - - function _dumpval(v, n) - { - _dumpstr = _dumpstr (v = _ln(((n == 0 && n == "" ? "RET" : n)) ": " ((v == 0 && v == "" ? "-" : v "'")))) - return v - } - - function _eXTFN(c, t, P) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return _ln("_extfn 1.0") - case "_lib_BEGIN": - return - case "_lib_END": - return + ERRNO = "" + if (_th1(_[p]["DATA"] = _rdfile(f), ERRNO)) { + delete _[p]["DATA"] + return _dllerr(p, "read file: " ERRNO, f) + } + if (v != "" && v != (_[p]["VERSION"] = _getfilever(f))) { + return _dllerr(p, " file version mismatch: ==`" _[p]["VERSION"] "'; !=`" v "'", f) + } + _creport(p, substr("OK: FILE DETECTED" ((v == "" ? "" : "(" v ")")) ": " f, 1, 122)) + } else { + if (_[p]["TYPE"] == "defdir") { + if (_filexist(f = _[p]["DIR"])) { + _creport(p, substr("OK: DIR DETECTED: " f, 1, 112)) + } else { + _dllerr(p, "directory " f " is not detected") + } } } +} - function _endpass(t) - { - _endpass_v0 = t - } - - function _err(t, a, b) - { - a = BINMODE - b = ORS - BINMODE = "rw" - ORS = "" - print(t) > _SYS_STDERR - fflush(_SYS_STDERR) - BINMODE = a - ORS = b - return t +#_________________________________________________________________ +function _filed(f, dd, d) +{ + ########################################## + if ((f = _filerdnehnd(f)) == "") { + return "" } - - function _errnl(t) - { - return _err(t ((t ~ /\x0A$/ ? "" : _CHR["EOL"]))) + if (f in _FILEDIRFL) { + return _FILEDIR[f] } - - function _error(t, d, A) - { - if (_ERRLOG_EF) { - A["TYPE"] = "ERROR" - A["TEXT"] = t - _log(A, d) + if (f in _FILEROOT) { + if (d = filegetdrvdir(_FILEROOT[f])) { + _FILEDIRFL[f] } + return (_FILEDIR[f] = d _FILEDIR[f]) } - - function _exit(c) - { - exit c + if ((dd = (dd ? dd : _FILEIO_RD), f) in _FILEDIR) { + return _FILEDIR[dd, f] } - - function _export_data(t, i, A) - { - A["DATA"] = t - A["ID"] = i - _expout("_DATA: " _Zexparr(A) "\n") + if ((d = filedi(dd) _FILEDIR[f]) ~ /^\\/) { + return (_FILEDIR[dd, f] = d) } + return d +} - function _expout(t, d, a, b) - { - a = BINMODE - b = ORS - BINMODE = "rw" - ORS = "" - print(t) > ((d ? d : d = _errlog_file)) - fflush(d) - BINMODE = a - ORS = b +#_________________________________________________________________ +function _filen(f) +{ + ################################################ + if ((f = _filerdnehnd(f)) == "") { + return "" } + return ((f in _FILENAM ? _FILENAM[f] : "")) +} - function _extfn_init() - { - _formatstrs_init() - _formatstrd_init() - _formatrexp_init() - _unformatstr_init() - _mac_init() +#_________________________________________________________________ +function _filene(f) +{ + ############################################### + if ((f = _filerdnehnd(f)) == "") { + return "" } + return (((f in _FILENAM ? _FILENAM[f] : "")) ((f in _FILEXT ? _FILEXT[f] : ""))) +} - function _faccl_i0(A, t, p, P, f, r) - { - f = r = "" - if (isarray(A)) { - while (f = A[f]) { - r = (@f(t, p, P)) r - } - } - return r +#_________________________________________________________________ +function _filenotexist(f, a) +{ + ###################################### + if (f == "") { + return "" } - - function _faccr_i0(A, t, p, P, f, r) - { - f = r = "" - if (isarray(A)) { - while (f = A[f]) { - r = r @f(t, p, P) - } - } - return r + if ((a = _filepath(f)) == "") { + ERRNO = "Filepath error `" f "'" + return "" } - - function _fatal(t, d, A) - { - if (_ERRLOG_FF) { - A["TYPE"] = "FATAL" - A["TEXT"] = t - _log(A, d) - } - if (! d) { - exit - } + _cmd("if exist \"" a "\" exit 1 2>NUL") + if (_exitcode == 1) { + return (ERRNO = _NOP) } + return a +} - function _fbaccl(A, t, p, P) - { - return _faccl_i0(A["B"], t, p, P) +#_______________________________________________________________________ +function _filepath(f, dd) +{ + ################################################ + if ((f = _filerdnehnd(f)) == "") { + return "" } + return (filegetrootdir(f, dd) ((f in _FILENAM ? _FILENAM[f] : "")) ((f in _FILEXT ? _FILEXT[f] : ""))) +} - function _fbaccr(A, t, p, P) - { - return _faccr_i0(A["B"], t, p, P) +#_________________________________________________________________ +function _filer(f, dd) +{ + ############################################# + if ((f = _filerdnehnd(f)) == "") { + return "" } - - function _ffaccl(A, t, p, P) - { - return _faccl_i0(A["F"], t, p, P) + if (f in _FILEROOT) { + return _FILEROOT[f] } - - function _ffaccr(A, t, p, P) - { - return _faccr_i0(A["F"], t, p, P) + if ((dd = (dd ? dd : _FILEIO_RD), f) in _FILEROOT) { + return _FILEROOT[dd, f] } + return (_FILEROOT[dd, f] = fileri(dd)) +} - function _fframe(A, t, p) - { - return _fframe_i0(A, t, p, A[""]) +#_________________________________________________________________ +function _filerd(f, dd) +{ + ############################################ + if ((f = _filerdnehnd(f)) == "") { + return "" } + return filegetrootdir(f, dd) +} - function _fframe_i0(A, t, p, f) - { - return ((f ? (@f(t, p)) _fframe_i0(A, t, p, A[f]) : "")) +#_________________________________________________________________ +function _filerdn(f, dd) +{ + ########################################### + if ((f = _filerdnehnd(f)) == "") { + return "" } + return ((f in _FILENAM ? filegetrootdir(f, dd) _FILENAM[f] : "")) +} - function _file(f) - { - if ((f = _filerdnehnd(f)) == "") { - return "" - } - return ((f in _FILEXT ? _FILEXT[f] : "")) +#_________________________________________________________________ +function _filerdne(f, dd) +{ + ########################################## + if ((f = _filerdnehnd(f)) == "") { + return "" } - - function _file_check(p) - { - if (1 || "AGENT" in _[p]) { - _tframe("_file_check_i0", p, p) - } + if (f in _FILENAM) { + return (filegetrootdir(f, dd) _FILENAM[f] ((f in _FILEXT ? _FILEXT[f] : ""))) + } + if (f in _FILEXT) { + return (filegetrootdir(f, dd) _FILEXT[f]) } + return "" +} - function _file_check_i0(p, pp, p1, p2, f, v) - { - if (_[p]["TYPE"] == "defile") { - f = _[p]["FILE"] - f = ((match(f, /^.:/) ? "" : _[_[pp]["AGENT"]][".Install Path"] "\\")) _[p]["FILE"] - if ("RQVERSION" in _[p]) { - v = _[p]["RQVERSION"] +#___________________________________________________________ +function _filerdnehnd(st, c, r, d, n, A) +{ + if (st) { + if ((c = toupper(st)) in _FILECACHE) { + FLENGTH = length(st) + return _FILECACHE[c] + } + if (match(st, /^[ \t]*\\[ \t]*\\/)) { + if (match(substr(st, (FLENGTH = RLENGTH) + 1), /^[ \t]*([0-9A-Za-z\-]+)[ \t]*(\\[ \t]*([A-Za-z])[ \t]*\$[ \t]*)?(\\[ \t]*([0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+( +[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+)*[ \t]*\\)+[ \t]*)?(([0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+( +[0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+)*)[ \t]*)?/, A)) { + FLENGTH = FLENGTH + RLENGTH + d = ((A[3] ? "\\" A[3] "$" : "")) A[4] + gsub(/[ \t]*\\[ \t]*/, "\\", d) + if ((st = toupper((r = "\\\\" A[1]) d (n = A[8]))) in _FILECACHE) { + return (_FILECACHE[substr(c, 1, FLENGTH)] = _FILECACHE[st]) + } + _FILEDIR[c = _FILECACHE[substr(c, 1, FLENGTH)] = _FILECACHE[st] = ++_file_rootcntr] = d + _FILEDIRFL[c] + _FILEROOT[c] = r } else { - v = _[pp][".Product Version"] + FLENGTH = 0 + _filepath_err = "UNC" + return "" + } + } else { + match(st, /^(([ \t]*\.[ \t]*\\[ \t]*)|(([ \t]*([A-Za-z])[ \t]*(\:)[ \t]*)?([ \t]*(\\)[ \t]*)?))([ \t]*(([ \t]*[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+( +[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+)*[ \t]*\\)+)[ \t]*)?([ \t]*([0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+( +[0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+)*)[ \t]*)?/, A) + if (! (FLENGTH = RLENGTH)) { + return "" } - ERRNO = "" - if (_th1(_[p]["DATA"] = _rdfile(f), ERRNO)) { - delete _[p]["DATA"] - return _dllerr(p, "read file: " ERRNO, f) + d = A[8] A[10] + gsub(/[ \t]*\\[ \t]*/, "\\", d) + if ((st = toupper((r = A[5] A[6]) d (n = A[14]))) in _FILECACHE) { + return (_FILECACHE[substr(c, 1, FLENGTH)] = _FILECACHE[st]) } - if (v != "" && v != (_[p]["VERSION"] = _getfilever(f))) { - return _dllerr(p, " file version mismatch: ==`" _[p]["VERSION"] "'; !=`" v "'", f) + _FILEDIR[c = _FILECACHE[substr(c, 1, FLENGTH)] = _FILECACHE[st] = ++_file_rootcntr] = d + if (A[8]) { + _FILEDIRFL[c] } - _creport(p, substr("OK: FILE DETECTED" ((v == "" ? "" : "(" v ")")) ": " f, 1, 122)) - } else { - if (_[p]["TYPE"] == "defdir") { - if (_filexist(f = _[p]["DIR"])) { - _creport(p, substr("OK: DIR DETECTED: " f, 1, 112)) - } else { - _dllerr(p, "directory " f " is not detected") - } + if (r) { + _FILEROOT[c] = r } } - } - - function _filed(f, dd, d) - { - if ((f = _filerdnehnd(f)) == "") { - return "" - } - if (f in _FILEDIRFL) { - return _FILEDIR[f] - } - if (f in _FILEROOT) { - if (d = filegetdrvdir(_FILEROOT[f])) { - _FILEDIRFL[f] + if (n) { + if (match(n, /\.[^\.]*$/)) { + _FILEXT[c] = substr(n, RSTART) + _FILENAM[c] = substr(n, 1, RSTART - 1) + } else { + _FILENAM[c] = n } - return (_FILEDIR[f] = d _FILEDIR[f]) - } - if ((dd = (dd ? dd : _FILEIO_RD), f) in _FILEDIR) { - return _FILEDIR[dd, f] - } - if ((d = filedi(dd) _FILEDIR[f]) ~ /^\\/) { - return (_FILEDIR[dd, f] = d) } - return d + return c } + return "" +} - function _filen(f) - { - if ((f = _filerdnehnd(f)) == "") { - return "" - } - return ((f in _FILENAM ? _FILENAM[f] : "")) +#_______________________________________________________________________ +function _filexist(f, a) +{ + ################################################ + if (f == "") { + return "" } - - function _filene(f) - { - if ((f = _filerdnehnd(f)) == "") { - return "" - } - return (((f in _FILENAM ? _FILENAM[f] : "")) ((f in _FILEXT ? _FILEXT[f] : ""))) + if ((a = _filepath(f)) == "") { + ERRNO = "Filepath error `" f "'" + return "" } - - function _filenotexist(f, a) - { - if (f == "") { - return "" - } - if ((a = _filepath(f)) == "") { - ERRNO = "Filepath error `" f "'" - return "" - } - _cmd("if exist \"" a "\" exit 1 2>NUL") - if (_exitcode == 1) { - return (ERRNO = _NOP) - } + _cmd("if exist \"" a "\" exit 1 2>NUL") + if (_exitcode == 1) { return a } - - function _filepath(f, dd) - { - if ((f = _filerdnehnd(f)) == "") { - return "" + ERRNO = "File not found `" f "'" + return _NOP +} + +#_______________________________________________________________________ +function _fn(f, p0, p1, p2) +{ + ################################################ + if (f in FUNCTAB) { + return @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) + return _th0(_retarr(_TMP0[p]), _tdel(p)) + } + if (_isptr(A)) { + _TMP0[p = _n()][_ARRLEN] = 1 + _tframe4("_foreach_i1" ((r ? "~" r : "")), A, f, _TMP0[p], p0, p1) + return _th0(_retarr(_TMP0[p]), _tdel(p)) + } +} + +#_____________________________________________________ +function _foreach_i0(A, f, D, p0, p1, p2) +{ + for (i in A) { + if (isarray(A[i])) { + _foreach_i0(A[i], f, D, p0, p1, p2) + } else { + _gen(D, @f(A[i], p0, p1, p2)) } - return (filegetrootdir(f, dd) ((f in _FILENAM ? _FILENAM[f] : "")) ((f in _FILEXT ? _FILEXT[f] : ""))) } +} - function _filer(f, dd) - { - if ((f = _filerdnehnd(f)) == "") { - return "" - } - if (f in _FILEROOT) { - return _FILEROOT[f] - } - if ((dd = (dd ? dd : _FILEIO_RD), f) in _FILEROOT) { - return _FILEROOT[dd, f] - } - return (_FILEROOT[dd, f] = fileri(dd)) - } +#_____________________________________________________ +function _foreach_i1(p, f, D, p0, p1, p2) +{ + _gen(D, @f(p, p0, p1, p2)) +} - function _filerd(f, dd) - { - if ((f = _filerdnehnd(f)) == "") { - return "" - } - return filegetrootdir(f, dd) +#_____________________________________________________________________________ +function _formatrexp(t) +{ + _formatstrq0 = split(t, _FORMATSTRA, /[\/\x00-\x1F\x80-\xFF]/, _FORMATSTRB) + _formatstrs0 = "" + for (t = 1; t < _formatstrq0; t++) { + _formatstrs0 = _formatstrs0 _FORMATSTRA[t] _FORMATREXPESC[_FORMATSTRB[t]] } + return (_formatstrs0 _FORMATSTRA[t]) +} - function _filerdn(f, dd) - { - if ((f = _filerdnehnd(f)) == "") { - return "" - } - return ((f in _FILENAM ? filegetrootdir(f, dd) _FILENAM[f] : "")) - } +#___________________________________________________________ +function _formatrexp_init() +{ + _defescarr(_FORMATREXPESC, "[\\x00-\\x1F\\x80-\\xFF]", _QASC) + _defescarr(_FORMATREXPESC, "\\/", "\\") + _FORMATREXPESC["\t"] = "\\t" +} - function _filerdne(f, dd) - { - if ((f = _filerdnehnd(f)) == "") { - return "" - } - if (f in _FILENAM) { - return (filegetrootdir(f, dd) _FILENAM[f] ((f in _FILEXT ? _FILEXT[f] : ""))) - } - if (f in _FILEXT) { - return (filegetrootdir(f, dd) _FILEXT[f]) - } - return "" +#_____________________________________________________________________________ +function _formatstrd(t) +{ + _formatstrq0 = split(t, _FORMATSTRA, /["\x00-\x1F\x80-\xFF]/, _FORMATSTRB) + _formatstrs0 = "" + for (t = 1; t < _formatstrq0; t++) { + _formatstrs0 = _formatstrs0 _FORMATSTRA[t] _FORMATSTRDESC[_FORMATSTRB[t]] } + return (_formatstrs0 _FORMATSTRA[t]) +} + +#___________________________________________________________ +function _formatstrd_init() +{ + _defescarr(_FORMATSTRDESC, "[\\x00-\\x1F\\x80-\\xFF]", _QASC) + _defescarr(_FORMATSTRDESC, "[\\\\\"]", "\\") + _FORMATSTRDESC["\t"] = "\\t" +} + +#__________________________________________________________________________________ +#################################################################################### + - function _filerdnehnd(st, c, r, d, n, A) - { - if (st) { - if ((c = toupper(st)) in _FILECACHE) { - FLENGTH = length(st) - return _FILECACHE[c] - } - if (match(st, /^[ \t]*\\[ \t]*\\/)) { - if (match(substr(st, (FLENGTH = RLENGTH) + 1), /^[ \t]*([0-9A-Za-z\-]+)[ \t]*(\\[ \t]*([A-Za-z])[ \t]*\$[ \t]*)?(\\[ \t]*([0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+( +[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+)*[ \t]*\\)+[ \t]*)?(([0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+( +[0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+)*)[ \t]*)?/, A)) { - FLENGTH = FLENGTH + RLENGTH - d = ((A[3] ? "\\" A[3] "$" : "")) A[4] - gsub(/[ \t]*\\[ \t]*/, "\\", d) - if ((st = toupper((r = "\\\\" A[1]) d (n = A[8]))) in _FILECACHE) { - return (_FILECACHE[substr(c, 1, FLENGTH)] = _FILECACHE[st]) - } - _FILEDIR[c = _FILECACHE[substr(c, 1, FLENGTH)] = _FILECACHE[st] = ++_file_rootcntr] = d - _FILEDIRFL[c] - _FILEROOT[c] = r - } else { - FLENGTH = 0 - _filepath_err = "UNC" - return "" - } - } else { - match(st, /^(([ \t]*\.[ \t]*\\[ \t]*)|(([ \t]*([A-Za-z])[ \t]*(\:)[ \t]*)?([ \t]*(\\)[ \t]*)?))([ \t]*(([ \t]*[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+( +[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+)*[ \t]*\\)+)[ \t]*)?([ \t]*([0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+( +[0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+)*)[ \t]*)?/, A) - if (! (FLENGTH = RLENGTH)) { - return "" - } - d = A[8] A[10] - gsub(/[ \t]*\\[ \t]*/, "\\", d) - if ((st = toupper((r = A[5] A[6]) d (n = A[14]))) in _FILECACHE) { - return (_FILECACHE[substr(c, 1, FLENGTH)] = _FILECACHE[st]) - } - _FILEDIR[c = _FILECACHE[substr(c, 1, FLENGTH)] = _FILECACHE[st] = ++_file_rootcntr] = d - if (A[8]) { - _FILEDIRFL[c] - } - if (r) { - _FILEROOT[c] = r - } - } - if (n) { - if (match(n, /\.[^\.]*$/)) { - _FILEXT[c] = substr(n, RSTART) - _FILENAM[c] = substr(n, 1, RSTART - 1) - } else { - _FILENAM[c] = n - } - } - return c - } - return "" - } - function _filexist(f, a) - { - if (f == "") { - return "" - } - if ((a = _filepath(f)) == "") { - ERRNO = "Filepath error `" f "'" - return "" - } - _cmd("if exist \"" a "\" exit 1 2>NUL") - if (_exitcode == 1) { - return a - } - ERRNO = "File not found `" f "'" - return _NOP - } - function _fn(f, p0, p1, p2) - { - if (f in FUNCTAB) { - return @f(p0, p1, p2) - } +#___________________________________________________________________________________ +function _formatstrs(t) +{ + _formatstrq0 = split(t, _FORMATSTRA, /['\x00-\x1F\x80-\xFF]/, _FORMATSTRB) + _formatstrs0 = "" + for (t = 1; t < _formatstrq0; t++) { + _formatstrs0 = _formatstrs0 _FORMATSTRA[t] _FORMATSTRSESC[_FORMATSTRB[t]] } - - 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) - return _th0(_retarr(_TMP0[p]), _tdel(p)) - } - if (_isptr(A)) { - _TMP0[p = _n()][_ARRLEN] = 1 - _tframe4("_foreach_i1" ((r ? "~" r : "")), A, f, _TMP0[p], p0, p1) - return _th0(_retarr(_TMP0[p]), _tdel(p)) + return (_formatstrs0 _FORMATSTRA[t]) +} + +#___________________________________________________________ +function _formatstrs_init() +{ + _defescarr(_FORMATSTRSESC, "[\\x00-\\x1F\\x80-\\xFF]", _QASC) + _defescarr(_FORMATSTRSESC, "[\\\\']", "\\") + _FORMATSTRSESC["\t"] = "\\t" +} + +function _fpp(q, D, S) +{ + _conl() + _conline(q) + _conl() + q = _patharr0(S, q) + #_arregpath(D,S) + #_conl(_dumparr(D)) + _conl(_dumparr(S)) + _conl() + return q +} + +#_______________________________________________________________________ +######################################################################## + + + + + + + + + +function _fthru(A, c, p, B) +{ + return _fthru_i0(A, c, p, B, A[""]) +} + +#_________________________________________________________________ +function _fthru_i0(A, c, p, B, f) +{ + return ((f ? @f(c, _fthru_i0(A, c, p, B, A[f]), B) : "")) +} + +function _gen(D, t) +{ + if (length(D[D[_ARRLEN]] = D[D["."]] t) > _datablock_length) { + D[++D[_ARRLEN]] = "" + } +} + +#_____________________________________________________________________________ +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)) + } + return t +} + +#_____________________________________________________________________________ +function _get_errout(p) +{ + ####################################################### + return _tframe("_get_errout_i0", p) +} + +#_______________________________________________________________________ +function _get_errout_i0(p, t, n, a) +{ + return ((p in _tLOG ? _get_errout_i1(p) _get_errout_i3(p) : "")) +} + +#_________________________________________________________________ +function _get_errout_i1(p, t, n, a) +{ + if (p in _tLOG) { + n = "" + if (_tLOG[p]["TYPE"]) { + n = _tLOG[p]["TYPE"] ": " _get_errout_i2(p) + if (match(_tLOG[p]["TEXT"], /\x1F/)) { + t = n + gsub(/[^\t]/, " ", t) + return (_ln(n substr(_tLOG[p]["TEXT"], 1, RSTART - 1)) _ln(t substr(_tLOG[p]["TEXT"], RSTART + 1))) + } } - } + return _ln(n _tLOG[p]["TEXT"]) + } +} + +#_______________________________________________________________________ +function _get_errout_i2(p) +{ + return (("FILE" in _tLOG[p] ? _tLOG[p]["FILE"] (("LINE" in _tLOG[p] ? "(" _tLOG[p]["LINE"] ")" : "")) ": " : "")) +} + +#_______________________________________________________________________ +function _get_errout_i3(p, t, ts, cl, cp, cr, a, b) +{ + if ("LSTR" in _tLOG[p]) { + t = _tLOG[p]["FULLSTR"] + ts = _tLOG[p]["TS"] + cp = "^" + if ("CSTR" in _tLOG[p]) { + cr = _tLOG[p]["CSTR"] + cl = _tLOG[p]["CLSTR"] + if ("CPSTR" in _tLOG[p]) { + cp = _tLOG[p]["CPSTR"] + } + } + cr = substr(cr, length(cl) + length(cp) + 1) + return (_ln(_tabtospc(t, ts)) _ln(_getchrln(" ", a = length(_tabtospc(_tLOG[p]["LSTR"], ts))) _getchrln("-", b = length(_tabtospc(cl, ts, a))) _getchrln("^", b = length(_tabtospc(cp, ts, a = a + b))) _getchrln("-", length(_tabtospc(cr, ts, a + b))))) + } +} - function _foreach_i0(A, f, D, p0, p1, p2) - { - for (i in A) { - if (isarray(A[i])) { - _foreach_i0(A[i], f, D, p0, p1, p2) - } else { - _gen(D, @f(A[i], p0, p1, p2)) +#_____________________________________________________________________________ +function _get_logout(p) +{ + ####################################################### + return _tframe("_get_logout_i0", p) +} + +#_______________________________________________________________________ +function _get_logout_i0(p, t, n, a) +{ + if (p in _tLOG) { + n = (("DATE" in _tLOG[p] ? _tLOG[p]["DATE"] " " : "")) (("TIME" in _tLOG[p] ? _tLOG[p]["TIME"] " " : "")) + if (_tLOG[p]["TYPE"]) { + n = n _tLOG[p]["TYPE"] ": " (("FILE" in _tLOG[p] ? _tLOG[p]["FILE"] (("LINE" in _tLOG[p] ? "(" _tLOG[p]["LINE"] ")" : "")) ": " : "")) + if (match(_tLOG[p]["TEXT"], /\x1F/)) { + t = n + gsub(/[^\t]/, " ", t) + return (_ln(n substr(_tLOG[p]["TEXT"], 1, RSTART - 1)) _ln(t substr(_tLOG[p]["TEXT"], RSTART + 1))) + } + } + return _ln(n _tLOG[p]["TEXT"]) + } +} + +#_______________________________________________________________________ +function _getchrln(s, w) +{ + ################################################# + if (s == "") { + return + } + #if ( w!=w+0 || w<0 ) w=_CON_WIDTH + if (length(s) < w) { + if (s in _GETCHRLN) { + if (length(_getchrlnt0 = _GETCHRLN[s]) >= w) { + return substr(_getchrlnt0, 1, w) } - } + } else { + _getchrlnt0 = s s + } + while (length(_getchrlnt0) < w) { + _getchrlnt0 = _getchrlnt0 _getchrlnt0 + } + _GETCHRLN[s] = _getchrlnt0 + return substr(_getchrlnt0, 1, w) + } else { + return substr(s, 1, 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 + f = A[3] A[5] A[7] + _conl("_getfilepath(" f ") (" al ")") + if (b = _filepath(f)) { + if (length(f) <= FLENGTH) { + FLENGTH = al + return b + } + ERRNO = "Filepath `" f "' error" + } + } + FLENGTH = 0 +} + +function _getfilever(f) +{ + ############################################################# + split(_cmd(_fileverpath " \"" f "\""), _GETFILEVERA0, /[ \t]+/) + if (_GETFILEVERA0[5]) { + return _GETFILEVERA0[5] + } +} + +#_________________________________________________________________ +function _getime() +{ + ################################################ + return strftime("%H:%M:%S") +} + +#_________________________________________________________________ +function _getmpdir(f, dd) +{ + ########################################## + if (! dd || ! (dd = _filerd(dd))) { + dd = _FILEIO_TMPRD + } + if (f = (f ? _filerd(f, dd) : _filerd("_" ++_FILEIO_TMPCNTR "\\", dd))) { + _FILEIO_RDTMP[toupper(f)] + } + return f +} + +#_________________________________________________________________ +function _getmpfile(f, dd) +{ + ######################################### + if (! dd || ! (dd = _filerd(dd))) { + dd = _FILEIO_TMPRD + } + if (f = _filerdne((_filene(f) ? f : f "_" ++_FILEIO_TMPCNTR), dd)) { + _FILEIO_RDNETMP[toupper(f)] + } + return f +} + +#_______________________________________________________________________ +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) + return @_getperf_fn(o, t, a) + } + return 1 +} + +#___________________________________________________________ +function _getperf_(o, t, a) +{ + if (a >= _getperf_end) { + return 0 } - - function _foreach_i1(p, f, D, p0, p1, p2) - { - _gen(D, @f(p, p0, p1, p2)) + if (_getperf_opsecp != _getperf_opsec) { + _constat(((_constatstr == _getperf_stat ? _getperf_statstr : _getperf_statstr = _constatstr)) t " [TIME=" (a - _getperf_start) " sec(" (_getperf_opsecp = _getperf_opsec) " ops/sec)]") + _getperf_stat = _constatstr + } + return 1 +} + +#___________________________________________________________ +function _getperf_noe(o, t, a) +{ + if (_getperf_opsecp != _getperf_opsec) { + _constat(((_constatstr == _getperf_stat ? _getperf_statstr : _getperf_statstr = _constatstr)) t " [TIME=" (a - _getperf_start) " sec(" (_getperf_opsecp = _getperf_opsec) " ops/sec)]") + _getperf_stat = _constatstr + } + return 1 +} + +#___________________________________________________________ +function _getperf_noenot(o, t, a) +{ + return 1 +} + +#___________________________________________________________ +function _getperf_not(o, t, a) +{ + if (a < _getperf_end) { + return 1 } +} - function _formatrexp(t) - { - _formatstrq0 = split(t, _FORMATSTRA, /[\/\x00-\x1F\x80-\xFF]/, _FORMATSTRB) - _formatstrs0 = "" - for (t = 1; t < _formatstrq0; t++) { - _formatstrs0 = _formatstrs0 _FORMATSTRA[t] _FORMATREXPESC[_FORMATSTRB[t]] - } - return (_formatstrs0 _FORMATSTRA[t]) - } +#_________________________________________________________________________________________ +########################################################################################## - function _formatrexp_init() - { - _defescarr(_FORMATREXPESC, "[\\x00-\\x1F\\x80-\\xFF]", _QASC) - _defescarr(_FORMATREXPESC, "\\/", "\\") - _FORMATREXPESC["\t"] = "\\t" - } - function _formatstrd(t) - { - _formatstrq0 = split(t, _FORMATSTRA, /["\x00-\x1F\x80-\xFF]/, _FORMATSTRB) - _formatstrs0 = "" - for (t = 1; t < _formatstrq0; t++) { - _formatstrs0 = _formatstrs0 _FORMATSTRA[t] _FORMATSTRDESC[_FORMATSTRB[t]] - } - return (_formatstrs0 _FORMATSTRA[t]) - } - function _formatstrd_init() - { - _defescarr(_FORMATSTRDESC, "[\\x00-\\x1F\\x80-\\xFF]", _QASC) - _defescarr(_FORMATSTRDESC, "[\\\\\"]", "\\") - _FORMATSTRDESC["\t"] = "\\t" - } - function _formatstrs(t) - { - _formatstrq0 = split(t, _FORMATSTRA, /['\x00-\x1F\x80-\xFF]/, _FORMATSTRB) - _formatstrs0 = "" - for (t = 1; t < _formatstrq0; t++) { - _formatstrs0 = _formatstrs0 _FORMATSTRA[t] _FORMATSTRSESC[_FORMATSTRB[t]] - } - return (_formatstrs0 _FORMATSTRA[t]) - } - function _formatstrs_init() - { - _defescarr(_FORMATSTRSESC, "[\\x00-\\x1F\\x80-\\xFF]", _QASC) - _defescarr(_FORMATSTRSESC, "[\\\\']", "\\") - _FORMATSTRSESC["\t"] = "\\t" - } - function _fpp(q, D, S) - { - _conl() - _conline(q) - _conl() - q = _patharr0(S, q) - _conl(_dumparr(S)) - _conl() - return q - } - function _fthru(A, c, p, B) - { - return _fthru_i0(A, c, p, B, A[""]) - } - function _fthru_i0(A, c, p, B, f) - { - return ((f ? @f(c, _fthru_i0(A, c, p, B, A[f]), B) : "")) - } - function _gen(D, t) - { - if (length(D[D[_ARRLEN]] = D[D["."]] t) > _datablock_length) { - D[++D[_ARRLEN]] = "" - } - } - 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)) - } - return t - } - function _get_errout(p) - { - return _tframe("_get_errout_i0", p) - } - function _get_errout_i0(p, t, n, a) - { - return ((p in _tLOG ? _get_errout_i1(p) _get_errout_i3(p) : "")) - } - function _get_errout_i1(p, t, n, a) - { - if (p in _tLOG) { - n = "" - if (_tLOG[p]["TYPE"]) { - n = _tLOG[p]["TYPE"] ": " _get_errout_i2(p) - if (match(_tLOG[p]["TEXT"], /\x1F/)) { - t = n - gsub(/[^\t]/, " ", t) - return (_ln(n substr(_tLOG[p]["TEXT"], 1, RSTART - 1)) _ln(t substr(_tLOG[p]["TEXT"], RSTART + 1))) - } - } - return _ln(n _tLOG[p]["TEXT"]) - } - } - function _get_errout_i2(p) - { - return (("FILE" in _tLOG[p] ? _tLOG[p]["FILE"] (("LINE" in _tLOG[p] ? "(" _tLOG[p]["LINE"] ")" : "")) ": " : "")) - } - function _get_errout_i3(p, t, ts, cl, cp, cr, a, b) - { - if ("LSTR" in _tLOG[p]) { - t = _tLOG[p]["FULLSTR"] - ts = _tLOG[p]["TS"] - cp = "^" - if ("CSTR" in _tLOG[p]) { - cr = _tLOG[p]["CSTR"] - cl = _tLOG[p]["CLSTR"] - if ("CPSTR" in _tLOG[p]) { - cp = _tLOG[p]["CPSTR"] - } - } - cr = substr(cr, length(cl) + length(cp) + 1) - return (_ln(_tabtospc(t, ts)) _ln(_getchrln(" ", a = length(_tabtospc(_tLOG[p]["LSTR"], ts))) _getchrln("-", b = length(_tabtospc(cl, ts, a))) _getchrln("^", b = length(_tabtospc(cp, ts, a = a + b))) _getchrln("-", length(_tabtospc(cr, ts, a + b))))) - } - } - function _get_logout(p) - { - return _tframe("_get_logout_i0", p) - } - function _get_logout_i0(p, t, n, a) - { - if (p in _tLOG) { - n = (("DATE" in _tLOG[p] ? _tLOG[p]["DATE"] " " : "")) (("TIME" in _tLOG[p] ? _tLOG[p]["TIME"] " " : "")) - if (_tLOG[p]["TYPE"]) { - n = n _tLOG[p]["TYPE"] ": " (("FILE" in _tLOG[p] ? _tLOG[p]["FILE"] (("LINE" in _tLOG[p] ? "(" _tLOG[p]["LINE"] ")" : "")) ": " : "")) - if (match(_tLOG[p]["TEXT"], /\x1F/)) { - t = n - gsub(/[^\t]/, " ", t) - return (_ln(n substr(_tLOG[p]["TEXT"], 1, RSTART - 1)) _ln(t substr(_tLOG[p]["TEXT"], RSTART + 1))) - } - } - return _ln(n _tLOG[p]["TEXT"]) - } - } - function _getchrln(s, w) - { - if (s == "") { - return - } - if (length(s) < w) { - if (s in _GETCHRLN) { - if (length(_getchrlnt0 = _GETCHRLN[s]) >= w) { - return substr(_getchrlnt0, 1, w) - } - } else { - _getchrlnt0 = s s - } - while (length(_getchrlnt0) < w) { - _getchrlnt0 = _getchrlnt0 _getchrlnt0 - } - _GETCHRLN[s] = _getchrlnt0 - return substr(_getchrlnt0, 1, w) - } else { - return substr(s, 1, 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 - f = A[3] A[5] A[7] - _conl("_getfilepath(" f ") (" al ")") - if (b = _filepath(f)) { - if (length(f) <= FLENGTH) { - FLENGTH = al - return b - } - ERRNO = "Filepath `" f "' error" + +function _getreg_i1(D, r, R, a, i, il, ir, rc, B) +{ + a = IGNORECASE + IGNORECASE = 1 + r = "^" _torexp(r) + rc = 0 + zs = "" + for (i in R) { + if (match(i, r, B)) { + il = B[_torexp_pfxcntr] + ir = gensub(/....$/, "", 1, substr(i, 1 + B[_torexp_pfxcntr, "length"])) + if (! gsub(/^\\/, "", ir) && match(il, /[^\\]+$/)) { + ir = substr(il, RSTART) ir } + D[ir] = R[i] + rc++ } - FLENGTH = 0 } - - function _getfilever(f) - { - split(_cmd(_fileverpath " \"" f "\""), _GETFILEVERA0, /[ \t]+/) - if (_GETFILEVERA0[5]) { - return _GETFILEVERA0[5] - } + IGNORECASE = a + if (rc > 0) { + return rc } +} - function _getime() - { - return strftime("%H:%M:%S") - } +#_________________________________________________________________ +function _getsecond() +{ + ############################################# + return systime() +} - function _getmpdir(f, dd) - { - if (! dd || ! (dd = _filerd(dd))) { - dd = _FILEIO_TMPRD - } - if (f = (f ? _filerd(f, dd) : _filerd("_" ++_FILEIO_TMPCNTR "\\", dd))) { - _FILEIO_RDTMP[toupper(f)] - } - return f +#___________________________________________________________ +function _getsecondsync(a, c, b, c2) +{ + ########################## + a = systime() + while (a == systime()) { + ++c } + return (a + 1) +} - function _getmpfile(f, dd) - { - if (! dd || ! (dd = _filerd(dd))) { - dd = _FILEIO_TMPRD +#_______________________________________________________________________ +function _getuid(p) +{ + ################################################# 1 # + if (p in _UIDOBL) { + for (_tptr in _UIDOBLV[_getuida0 = _UIDOBL[p]]) { + delete _UIDOBLV[_getuida0][_tptr] + _CLASSPTR[_tptr] = p + return _tptr } - if (f = _filerdne((_filene(f) ? f : f "_" ++_FILEIO_TMPCNTR), dd)) { - _FILEIO_RDNETMP[toupper(f)] - } - return f } + _CLASSPTR[_tptr = _UIDPFX[p] _getuid_i0(_UIDCNT[p], _UIDCHRL[_tptr = _UIDCHR[p]], _UIDCHRH[_tptr]) _UIDSFX[p]] = p + return _tptr +} - 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) - return @_getperf_fn(o, t, a) +#_____________________________________________________ +function _getuid_i0(p, UL, UH) +{ + if ("" == (_tptr = UL[_UIDCNTL[p]])) { + for (_tptr in UH) { + delete UH[_tptr] + return ((_UIDCNTH[p] = _tptr) (_UIDCNTL[p] = UL[""])) } - return 1 + _fatal("out of UID") } + return (_UIDCNTH[p] (_UIDCNTL[p] = _tptr)) +} - function _getperf_(o, t, a) - { - if (a >= _getperf_end) { - return 0 - } - if (_getperf_opsecp != _getperf_opsec) { - _constat(((_constatstr == _getperf_stat ? _getperf_statstr : _getperf_statstr = _constatstr)) t " [TIME=" (a - _getperf_start) " sec(" (_getperf_opsecp = _getperf_opsec) " ops/sec)]") - _getperf_stat = _constatstr - } - return 1 - } +function _handle8494(t) +{ + return gensub(/(.)/, ".\\1", "G", t) +} - function _getperf_noe(o, t, a) - { - if (_getperf_opsecp != _getperf_opsec) { - _constat(((_constatstr == _getperf_stat ? _getperf_statstr : _getperf_statstr = _constatstr)) t " [TIME=" (a - _getperf_start) " sec(" (_getperf_opsecp = _getperf_opsec) " ops/sec)]") - _getperf_stat = _constatstr - } - return 1 +#_____________________________________________________________________________ +function _hexnum(n, l) +{ + ######################################################### + if (l + 0 < 1) { + l = 2 } + return sprintf("%." ((l + 0 < 1 ? 2 : l)) "X", n) +} - function _getperf_noenot(o, t, a) - { - return 1 +#_________________________________________________________________ +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) + } + _getperf_fn = "_nop" + return ("[TIME=" (_getperf_last - _getperf_start) " sec(" _getperf_opsec " ops/sec)]") + } + _conl("initiate _getperf") + _getperf_opstart = _getperf_opcurr = o + 0 + _getperf_opsec = _getperf_opsecp = _getperf_stat = _getperf_statstr = "" + _getperf_end = t + (_getperf_start = _getperf_last = _getsecondsync()) + _getperf_fn = ((t + 0 > 0 ? "_getperf_" : "_getperf_noe")) ((s ? "" : "not")) + return _getperf_start +} + +function _import_data(t, p, p2, a) +{ + if (match(t, /^_DATA: /)) { + _tDATA[a = _wLCHLD(p, _N())][""] + delete _tDATA[a][""] + _Zimparr(_tDATA[a], substr(t, 8)) + _conl("DATA: `" _tDATA[a]["ID"] "':`" _tDATA[a]["DATA"] "'") + return "" } - - function _getperf_not(o, t, a) - { - if (a < _getperf_end) { - return 1 + return t +} + +#_______________________________________________________________________ +function _info(t, d, A) +{ + ################################################## + if (_ERRLOG_IF) { + A["TYPE"] = "INFO" + A["TEXT"] = t + _log(A, d) + } +} + +# test with the different path types +# _conl(_ln("SRC:") _dumparr(S)); _conl(); + +function _ini(p, cs, dptr, pfx, sfx, hstr, lstr) +{ + return _inituid(p, cs, dptr, pfx, sfx, hstr, lstr, A) +} + +function _initfilever() +{ + _fileverpath = "\\\\CPU\\eGAWK\\LIB\\_filever\\_filever.exe" +} + +function _initrdreg() +{ + _RDREGTYPE["SZ"] = "STR" + _RDREGTYPE["DWORD"] = "W32" + _RDREGTYPE["QWORD"] = "W64" + _RDREGTYPE["BINARY"] = "BIN" + _RDREGTYPE["EXPAND_SZ"] = "XSZ" + _RDREGTYPE["MULTI_SZ"] = "MSZ" + _RDrdregfld = _rdregkey = 0 +} + +function _initregpath0() +{ + _REGPATH0REGDIR[""] = "HKEY_LOCAL_MACHINE" + _REGPATH0REGDIR["HKLM"] = "HKEY_LOCAL_MACHINE" + _REGPATH0REGDIR["HKEY_LOCAL_MACHINE"] = "HKEY_LOCAL_MACHINE" + _REGPATH0REGDIR["HKCR"] = "HKEY_CLASSES_ROOT" + _REGPATH0REGDIR["HKEY_CLASSES_ROOT"] = "HKEY_CLASSES_ROOT" + _REGPATH0REGDIR["HKCU"] = "HKEY_CURRENT_USER" + _REGPATH0REGDIR["HKEY_CURRENT_USER"] = "HKEY_CURRENT_USER" + _REGPATH0REGDIR["HKU"] = "HKEY_USERS" + _REGPATH0REGDIR["HKEY_USERS"] = "HKEY_USERS" + _REGPATH0REGDIR["HKCC"] = "HKEY_CURRENT_CONFIG" + _REGPATH0REGDIR["HKEY_CURRENT_CONFIG"] = "HKEY_CURRENT_CONFIG" + _REGPATH0REGDIR["HKPD"] = "HKEY_PERFORMANCE_DATA" + _REGPATH0REGDIR["HKEY_PERFORMANCE_DATA"] = "HKEY_PERFORMANCE_DATA" +} + +function _initshare() +{ + _sharextool = "\\\\CPU\\eGAWK\\LIB\\_share\\_share.exe" +} + +#_________________________________________ +function _initspecialuid() +{ + _NOINDEX = _getuid() + _LEN = _getuid() + _PTR = _getuid() + _NAME = _getuid() + _TYPE = _getuid() + _FORMAT = _getuid() +} + +function _initsys() +{ +} + +#_______________________________________________________________________ +function _inituid(p, cs, dptr, pfx, sfx, hstr, lstr, A) +{ + ################### 1 # + if (cs == 0 && cs == "") { + cs = p + p = _getuid() + } + _conl() + _conl() + _conl(cs) + if (match(cs, /^(([^:]*):)?(([^'\xB4]*\xB4.)*[^'\xB4]*)[']/, A)) { + pfx = A[3] + dptr = A[2] + } + if (match(cs = substr(cs, 1 + RLENGTH), /'(([^'\xB4]*\xB4.)*[^'\xB4]*)$/, A)) { + sfx = A[1] + cs = substr(cs, 1, RSTART - 1) + } + if (match(cs, /^(([`\^])(.*))/, A)) { + if (A[2] == "`") { + hstr = A[3] "~" + lstr = "" + } else { + lstr = A[3] "+" + hstr = "" + } + } else { + if (match(cs, /^(([^'\xB4\|]*\xB4.)*[^'\xB4\|]*)(\|(.*))?/, A)) { + hstr = A[1] + lstr = A[4] + } else { + ERRNO = "_inituid(): bad parameters" + return } } - - function _getreg_i1(D, r, R, a, i, il, ir, rc, B) - { - a = IGNORECASE - IGNORECASE = 1 - r = "^" _torexp(r) - rc = 0 - zs = "" - for (i in R) { - if (match(i, r, B)) { - il = B[_torexp_pfxcntr] - ir = gensub(/....$/, "", 1, substr(i, 1 + B[_torexp_pfxcntr, "length"])) - if (! gsub(/^\\/, "", ir) && match(il, /[^\\]+$/)) { - ir = substr(il, RSTART) ir + _conl(dptr ":" pfx "'" hstr "|" lstr "'" sfx) + return _cfguid(p, dptr, pfx, sfx, hstr, lstr) +} + +function _inituidefault(h, l, H, L) +{ + _classys = "" + delete _UIDOBLV[_UIDOBLV[_UIDOBL[_classys] = _classys][""] = _classys][""] + _UIDPFX[_classys] + _UIDSFX[_classys] + _UIDCNT[_classys] = _UIDCHR[_classys] = _CLASSPTR[_classys] = _classys + h = "AB" + l = h "01" + _splitstr(H, h) + _splitstr(L, l) + delete _UIDCHRH[_UIDCHRH[_classys][""] = _classys][""] + delete _UIDCHRL[_UIDCHRL[_classys][""] = _classys][""] + _UIDCNTH[_classys] + _cfguidh(_classys, H, L) + _UIDCNTL[_classys] = _cfguidl(_classys, L, L) + _CLASSFN[_classys]["del"] = "_tobjDEL" + _CLASSFN[_classys]["new"] = "_tobjNEW" + _drawuid(_classys) + _initspecialuid() +} + +#_______________________________________________________________________ +function _ins(S, sf, D, df) +{ + ################################################ + if (sf in S) { + if (isarray(S[sf])) { + if (df in D) { + if (isarray(D[df])) { + return _extarr(D[df], S[sf]) } - D[ir] = R[i] - rc++ + delete D[df] } - } - IGNORECASE = a - if (rc > 0) { - return rc - } + D[df][""] + delete D[df][""] + return _extarr(D[df], S[sf]) + } else { + if (isarray(D[df])) { + delete D[df] + } + D[df] = 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) +{ + A[f] = A[""] + A[""] = f +} + +# there is problem with string's format: i can;t easilly merge 2 charsets: comma-divided and every-char-divided strings + +#_______________________________________________________________________ +function _isptr(p) +{ + ################################################## 1 # + if (isarray(p)) { + is = _NOP + it = "A" + return 0 } - - function _getsecond() - { - return systime() + is = p + if (p == 0 && p == "") { + it = "-" + return 0 } - - function _getsecondsync(a, c, b, c2) - { - a = systime() - while (a == systime()) { - ++c - } - return (a + 1) + if (p in _CLASSPTR) { + return (it = "P") } + it = "S" + return 0 +} - function _getuid(p) - { - if (p in _UIDOBL) { - for (_tptr in _UIDOBLV[_getuida0 = _UIDOBL[p]]) { - delete _UIDOBLV[_getuida0][_tptr] - _CLASSPTR[_tptr] = p - return _tptr - } +#_______________________________________________________________________ +function _istr(p) +{ + ################################################### 1 # + if (isarray(p)) { + is = _NOP + it = "A" + return 0 + } + is = p + if (p == 0 && p == "") { + it = "-" + return 0 + } + return (it = (p == "" ? "s" : "S")) +} + +#_________________________________________________________________ +function _lengthsort(i1, v1, i2, v2) +{ + ############################## + return ((length(i1) < length(i2) ? -1 : (length(i1) > length(i2) ? 1 : (i1 < i2 ? -1 : 1)))) +} + +#_________________________________________________________________ +function _lib_APPLY() +{ + return _ffaccr(_LIBAPI, "_lib_APPLY") +} + +#_________________________________________________________________ +function _lib_BEGIN(A) +{ + return _ffaccr(_LIBAPI, "_lib_BEGIN", "", A) +} + +#_______________________________________________________________________ +function _lib_CMDLN(t) +{ + return _pass(_LIBAPI["F"], "_lib_CMDLN", t) +} + +#_________________________________________________________________ +function _lib_END(A) +{ + return _ffaccr(_LIBAPI, "_lib_END", "", A) +} + +#_________________________________________________________________ +function _lib_HELP() +{ + return _fbaccr(_LIBAPI, "_lib_HELP") +} + +#_________________________________________________________________ +function _lib_NAMEVER() +{ + return _fbaccr(_LIBAPI, "_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() + if (p) { + _tLOG[p = _wLCHLD(p, _N())][""] + delete _tLOG[p][""] + _movarr(_tLOG[p], A) + return p } - _CLASSPTR[_tptr = _UIDPFX[p] _getuid_i0(_UIDCNT[p], _UIDCHRL[_tptr = _UIDCHR[p]], _UIDCHRH[_tptr]) _UIDSFX[p]] = p - return _tptr + _expout("_ERRLOG: " _Zexparr(A) "\n") + } else { + B["TEXT"] = A + B["TYPE"] = "" + return _log(B, p) } +} - function _getuid_i0(p, UL, UH) - { - if ("" == (_tptr = UL[_UIDCNTL[p]])) { - for (_tptr in UH) { - delete UH[_tptr] - return ((_UIDCNTH[p] = _tptr) (_UIDCNTL[p] = UL[""])) +#_________________________________________________________________ +function _lspctab(t, ts, l, l1, l2, A) +{ + ################################ + while (match(t, /^(\t*)( *)((\t*)(.*))$/, A)) { + if (A[1, "length"] >= l) { + return substr(t, l + 1) + } + if (A[2]) { + if ((l1 = int(A[2, "length"] / ts)) >= (l2 = l - A[1, "length"])) { + return (substr(A[2], l2 * ts + 1) A[3]) } - _fatal("out of UID") + if (! A[4]) { + return A[5] + } + t = A[1] _getchrln("\t", l1) A[3] + } else { + return t } - return (_UIDCNTH[p] (_UIDCNTL[p] = _tptr)) } - - function _handle8494(t) - { - return gensub(/(.)/, ".\\1", "G", t) +} + +function _mac_init() +{ + _MACPFX["\204"] = "_macpfx84" + _MACPFX[""] = "_mpupfxsubret" + _MACPFX84SFX["\204"] = "_macpfx84" + _MACPFX84SFX["\224"] = "_macsfx94" + _MACPFX84SFX[""] = "_mpusfxsubret" + _VLDMAXSTRING = 1e+06 +} + +function _macpfx84(F, D, C, p1, p2, p3) +{ + return _mpusub(_MACPFX84SFX, D, C, D[_mpuptr++], p1, p2, p3) +} + +function _macsfx94(F, D, C, p1, p2, p3) +{ + return _mpuretsub(D, _handle8494(_mpuacc)) +} + +#_______________________________________________________________________ +function _movarr(D, S) +{ + ################################################### + delete D + D[""] + delete D[""] + _addarr(D, S) +} + +function _mpu(t, F, p1, p2, p3, D, C) +{ + if (patsplit(t, C, /[\x84\x93\x94]/, D) > 0) { + _conline("CODE") + _conl() + _conl(_dumparr(C)) + _conline("DATA") + _conl() + _conl(_dumparr(D)) + _mpuptr = 0 + _mpucc0 = "" + _mpusub(F, D, C, D[_mpuptr++], p1, p2, p3) + return _mpuacc } + return t +} - function _hexnum(n, l) - { - if (l + 0 < 1) { - l = 2 - } - return sprintf("%." ((l + 0 < 1 ? 2 : l)) "X", n) - } +# +# /rexpstr/ -> datastr +# (\x00\t\+)* -> 28 00 09 5B 2B 29 +# +# unesc all non-rexp characters: replace unesc of rexp-characters but do not remove it: \* -> \*, \x2A -> \*, \052 -> \*, \\ -> \# - function _igetperf(t, s, o) - { - if (t == 0 && t == "" && s == 0 && s == "" && o == 0 && o == "") { - if (_getperf_fn !~ /not$/ && _constatstr == _getperf_stat) { - _constat(_getperf_statstr) - } - _getperf_fn = "_nop" - return ("[TIME=" (_getperf_last - _getperf_start) " sec(" _getperf_opsec " ops/sec)]") - } - _conl("initiate _getperf") - _getperf_opstart = _getperf_opcurr = o + 0 - _getperf_opsec = _getperf_opsecp = _getperf_stat = _getperf_statstr = "" - _getperf_end = t + (_getperf_start = _getperf_last = _getsecondsync()) - _getperf_fn = ((t + 0 > 0 ? "_getperf_" : "_getperf_noe")) ((s ? "" : "not")) - return _getperf_start - } - - function _import_data(t, p, p2, a) - { - if (match(t, /^_DATA: /)) { - _tDATA[a = _wLCHLD(p, _N())][""] - delete _tDATA[a][""] - _Zimparr(_tDATA[a], substr(t, 8)) - _conl("DATA: `" _tDATA[a]["ID"] "':`" _tDATA[a]["DATA"] "'") - return "" - } - return t - } - function _info(t, d, A) - { - if (_ERRLOG_IF) { - A["TYPE"] = "INFO" - A["TEXT"] = t - _log(A, d) - } - } - function _ini(p, cs, dptr, pfx, sfx, hstr, lstr) - { - return _inituid(p, cs, dptr, pfx, sfx, hstr, lstr, A) - } - function _initfilever() - { - _fileverpath = "\\\\CPU\\eGAWK\\LIB\\_filever\\_filever.exe" - } - function _initrdreg() - { - _RDREGTYPE["SZ"] = "STR" - _RDREGTYPE["DWORD"] = "W32" - _RDREGTYPE["QWORD"] = "W64" - _RDREGTYPE["BINARY"] = "BIN" - _RDREGTYPE["EXPAND_SZ"] = "XSZ" - _RDREGTYPE["MULTI_SZ"] = "MSZ" - _RDrdregfld = _rdregkey = 0 - } - function _initregpath0() - { - _REGPATH0REGDIR[""] = "HKEY_LOCAL_MACHINE" - _REGPATH0REGDIR["HKLM"] = "HKEY_LOCAL_MACHINE" - _REGPATH0REGDIR["HKEY_LOCAL_MACHINE"] = "HKEY_LOCAL_MACHINE" - _REGPATH0REGDIR["HKCR"] = "HKEY_CLASSES_ROOT" - _REGPATH0REGDIR["HKEY_CLASSES_ROOT"] = "HKEY_CLASSES_ROOT" - _REGPATH0REGDIR["HKCU"] = "HKEY_CURRENT_USER" - _REGPATH0REGDIR["HKEY_CURRENT_USER"] = "HKEY_CURRENT_USER" - _REGPATH0REGDIR["HKU"] = "HKEY_USERS" - _REGPATH0REGDIR["HKEY_USERS"] = "HKEY_USERS" - _REGPATH0REGDIR["HKCC"] = "HKEY_CURRENT_CONFIG" - _REGPATH0REGDIR["HKEY_CURRENT_CONFIG"] = "HKEY_CURRENT_CONFIG" - _REGPATH0REGDIR["HKPD"] = "HKEY_PERFORMANCE_DATA" - _REGPATH0REGDIR["HKEY_PERFORMANCE_DATA"] = "HKEY_PERFORMANCE_DATA" - } - function _initshare() - { - _sharextool = "\\\\CPU\\eGAWK\\LIB\\_share\\_share.exe" - } - function _initspecialuid() - { - _NOINDEX = _getuid() - _LEN = _getuid() - _PTR = _getuid() - _NAME = _getuid() - _TYPE = _getuid() - _FORMAT = _getuid() - } - function _initsys() - { - } - function _inituid(p, cs, dptr, pfx, sfx, hstr, lstr, A) - { - if (cs == 0 && cs == "") { - cs = p - p = _getuid() - } - _conl() - _conl() - _conl(cs) - if (match(cs, /^(([^:]*):)?(([^'\xB4]*\xB4.)*[^'\xB4]*)[']/, A)) { - pfx = A[3] - dptr = A[2] - } - if (match(cs = substr(cs, 1 + RLENGTH), /'(([^'\xB4]*\xB4.)*[^'\xB4]*)$/, A)) { - sfx = A[1] - cs = substr(cs, 1, RSTART - 1) - } - if (match(cs, /^(([`\^])(.*))/, A)) { - if (A[2] == "`") { - hstr = A[3] "~" - lstr = "" - } else { - lstr = A[3] "+" - hstr = "" - } - } else { - if (match(cs, /^(([^'\xB4\|]*\xB4.)*[^'\xB4\|]*)(\|(.*))?/, A)) { - hstr = A[1] - lstr = A[4] - } else { - ERRNO = "_inituid(): bad parameters" - return - } - } - _conl(dptr ":" pfx "'" hstr "|" lstr "'" sfx) - return _cfguid(p, dptr, pfx, sfx, hstr, lstr) - } - - function _inituidefault(h, l, H, L) - { - _classys = "" - delete _UIDOBLV[_UIDOBLV[_UIDOBL[_classys] = _classys][""] = _classys][""] - _UIDPFX[_classys] - _UIDSFX[_classys] - _UIDCNT[_classys] = _UIDCHR[_classys] = _CLASSPTR[_classys] = _classys - h = "AB" - l = h "01" - _splitstr(H, h) - _splitstr(L, l) - delete _UIDCHRH[_UIDCHRH[_classys][""] = _classys][""] - delete _UIDCHRL[_UIDCHRL[_classys][""] = _classys][""] - _UIDCNTH[_classys] - _cfguidh(_classys, H, L) - _UIDCNTL[_classys] = _cfguidl(_classys, L, L) - _CLASSFN[_classys]["del"] = "_tobjDEL" - _CLASSFN[_classys]["new"] = "_tobjNEW" - _drawuid(_classys) - _initspecialuid() - } - - function _ins(S, sf, D, df) - { - if (sf in S) { - if (isarray(S[sf])) { - if (df in D) { - if (isarray(D[df])) { - return _extarr(D[df], S[sf]) - } - delete D[df] - } - D[df][""] - delete D[df][""] - return _extarr(D[df], S[sf]) - } else { - if (isarray(D[df])) { - delete D[df] - } - D[df] = 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) - { - A[f] = A[""] - A[""] = f - } - function _isptr(p) - { - if (isarray(p)) { - is = _NOP - it = "A" - return 0 - } - is = p - if (p == 0 && p == "") { - it = "-" - return 0 - } - if (p in _CLASSPTR) { - return (it = "P") - } - it = "S" - return 0 - } - function _istr(p) - { - if (isarray(p)) { - is = _NOP - it = "A" - return 0 - } - is = p - if (p == 0 && p == "") { - it = "-" - return 0 - } - return (it = (p == "" ? "s" : "S")) - } - function _lengthsort(i1, v1, i2, v2) - { - return ((length(i1) < length(i2) ? -1 : (length(i1) > length(i2) ? 1 : (i1 < i2 ? -1 : 1)))) - } - function _lib_APPLY() - { - return _ffaccr(_LIBAPI, "_lib_APPLY") - } - function _lib_BEGIN(A) - { - return _ffaccr(_LIBAPI, "_lib_BEGIN", "", A) - } - function _lib_CMDLN(t) - { - return _pass(_LIBAPI["F"], "_lib_CMDLN", t) - } - function _lib_END(A) - { - return _ffaccr(_LIBAPI, "_lib_END", "", A) - } - function _lib_HELP() - { - return _fbaccr(_LIBAPI, "_lib_HELP") - } - function _lib_NAMEVER() - { - return _fbaccr(_LIBAPI, "_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() - if (p) { - _tLOG[p = _wLCHLD(p, _N())][""] - delete _tLOG[p][""] - _movarr(_tLOG[p], A) - return p - } - _expout("_ERRLOG: " _Zexparr(A) "\n") - } else { - B["TEXT"] = A - B["TYPE"] = "" - return _log(B, p) - } - } - function _lspctab(t, ts, l, l1, l2, A) - { - while (match(t, /^(\t*)( *)((\t*)(.*))$/, A)) { - if (A[1, "length"] >= l) { - return substr(t, l + 1) - } - if (A[2]) { - if ((l1 = int(A[2, "length"] / ts)) >= (l2 = l - A[1, "length"])) { - return (substr(A[2], l2 * ts + 1) A[3]) - } - if (! A[4]) { - return A[5] - } - t = A[1] _getchrln("\t", l1) A[3] - } else { - return t - } - } - } - function _mac_init() - { - _MACPFX["\204"] = "_macpfx84" - _MACPFX[""] = "_mpupfxsubret" - _MACPFX84SFX["\204"] = "_macpfx84" - _MACPFX84SFX["\224"] = "_macsfx94" - _MACPFX84SFX[""] = "_mpusfxsubret" - _VLDMAXSTRING = 1e+06 - } - function _macpfx84(F, D, C, p1, p2, p3) - { - return _mpusub(_MACPFX84SFX, D, C, D[_mpuptr++], p1, p2, p3) - } - function _macsfx94(F, D, C, p1, p2, p3) - { - return _mpuretsub(D, _handle8494(_mpuacc)) - } - function _movarr(D, S) - { - delete D - D[""] - delete D[""] - _addarr(D, S) - } - function _mpu(t, F, p1, p2, p3, D, C) - { - if (patsplit(t, C, /[\x84\x93\x94]/, D) > 0) { - _conline("CODE") - _conl() - _conl(_dumparr(C)) - _conline("DATA") - _conl() - _conl(_dumparr(D)) - _mpuptr = 0 - _mpucc0 = "" - _mpusub(F, D, C, D[_mpuptr++], p1, p2, p3) - return _mpuacc - } - return t - } - function _mpudefaulthnd(F, D, C, p1, p2, p3) - { - _mpuretsub(D, _mpucc0) - } - function _mpupfxsubret(F, D, C, p1, p2, p3) - { - return 1 - } - function _mpuretsub(D, t) - { - _mpuacc = D[_mpuptr++] - _accmpu(D, t) - return 1 - } - function _mpusfxsubret(F, D, C, p1, p2, p3) - { - return -1 - } +function _mpudefaulthnd(F, D, C, p1, p2, p3) +{ + _mpuretsub(D, _mpucc0) +} - function _mpusub(F, D, C, d, p1, p2, p3, q) - { - q = D[_ARRLEN] - if (_VLDMAXSTRING < length(d)) { - D[--D[_ARRLEN]] = d - _mpuacc = "" +function _mpupfxsubret(F, D, C, p1, p2, p3) +{ + return 1 +} + +function _mpuretsub(D, t) +{ + _mpuacc = D[_mpuptr++] + _accmpu(D, t) + return 1 +} + +function _mpusfxsubret(F, D, C, p1, p2, p3) +{ + return -1 +} + +function _mpusub(F, D, C, d, p1, p2, p3, q) +{ + q = D[_ARRLEN] + if (_VLDMAXSTRING < length(d)) { + D[--D[_ARRLEN]] = d + _mpuacc = "" + } else { + _mpuacc = d + } + d = _mpucc0 + _conl("_mpusub enter: in `" _mpuacc "' / _mpuptr=" _mpuptr "'") + do { + if ((_mpucc0 = C[_mpuptr]) in F) { + if (isarray(F[_mpucc0])) { + _mpufn0 = F[_mpucc0] + } + _conl("FN: `" _mpucc0 "' > CALL: `" _mpufn0 "' : _mpuacc=" _mpuacc "'") } else { - _mpuacc = d - } - d = _mpucc0 - _conl("_mpusub enter: in `" _mpuacc "' / _mpuptr=" _mpuptr "'") - do { - if ((_mpucc0 = C[_mpuptr]) in F) { - if (isarray(F[_mpucc0])) { - _mpufn0 = F[_mpucc0] - } - _conl("FN: `" _mpucc0 "' > CALL: `" _mpufn0 "' : _mpuacc=" _mpuacc "'") - } else { - _mpufn0 = "_mpudefaulthnd" + _mpufn0 = "_mpudefaulthnd" + } + } while (! _accmpu(D, _mpuacc, @_mpufn0(F, D, C, p1, p2, p3))) + if (_mpufn0 == -1) { + _conl("WARNING: unclosed expression: `" d _mpuacc "'") + _mpuacc = d _mpuacc + } + _retarrm(D, q, "", (_mpufn0 == -1 ? _th0(d, _mpusubwrng("WARNING: unclosed expression", d _mpuacc)) : "")) + # collect: _mpuacc=_retarr(D) _mpuacc + _conl("mpusub exit: _mpuacc: `" _mpuacc "'") +} + +#_______________________________________________________________________ +function _n(F, v, p) +{ + ##################################################### + for (p in _UIDSDEL) { + delete _UIDSDEL[p] + delete _ptr[p] + delete _tPREV[p] + delete _tPARENT[p] + delete _tNEXT[p] + delete _tFCHLD[p] + delete _tQCHLD[p] + delete _tLCHLD[p] + delete _TMP0[p] + delete _TMP1[p] + delete _tLINK[p] + delete _tCLASS[p] + return _nN_i0(p, F, v) + } + for (p in _UIDS) { + delete _UIDS[p] + return _nN_i0(p, F, v) + } + return _nN_i0(_tgenuid(), F, v) +} + +#_____________________________________________________ +function _nN_i0(p, F, v) +{ + _[p][""] + delete _[p][""] + _ptr[p][""] + delete _ptr[p][""] + _TMP0[p][_ARRLEN] = _TMP1[p][_ARRLEN] = 0 + if (isarray(F)) { + delete F[p] + if (isarray(v)) { + F[p][""] + delete F[p][""] + _copyarr(F[p], v) + } else { + if (! (v == 0 && v == "")) { + F[p] = v } - } while (! _accmpu(D, _mpuacc, @_mpufn0(F, D, C, p1, p2, p3))) - if (_mpufn0 == -1) { - _conl("WARNING: unclosed expression: `" d _mpuacc "'") - _mpuacc = d _mpuacc } - _retarrm(D, q, "", (_mpufn0 == -1 ? _th0(d, _mpusubwrng("WARNING: unclosed expression", d _mpuacc)) : "")) - _conl("mpusub exit: _mpuacc: `" _mpuacc "'") - } - - function _n(F, v, p) - { - for (p in _UIDSDEL) { - delete _UIDSDEL[p] - delete _ptr[p] - delete _tPREV[p] - delete _tPARENT[p] - delete _tNEXT[p] - delete _tFCHLD[p] - delete _tQCHLD[p] - delete _tLCHLD[p] - delete _TMP0[p] - delete _TMP1[p] - delete _tLINK[p] - delete _tCLASS[p] - return _nN_i0(p, F, v) - } - for (p in _UIDS) { - delete _UIDS[p] - return _nN_i0(p, F, v) - } - return _nN_i0(_tgenuid(), F, v) - } - - function _nN_i0(p, F, v) - { - _[p][""] - delete _[p][""] - _ptr[p][""] - delete _ptr[p][""] - _TMP0[p][_ARRLEN] = _TMP1[p][_ARRLEN] = 0 - if (isarray(F)) { - delete F[p] + } else { + if (! (F == 0 && F == "")) { if (isarray(v)) { - F[p][""] - delete F[p][""] - _copyarr(F[p], v) + _[p][F][""] + delete _[p][F][""] + _copyarr(_[p][F], v) } else { - if (! (v == 0 && v == "")) { - F[p] = v - } - } - } else { - if (! (F == 0 && F == "")) { - if (isarray(v)) { - _[p][F][""] - delete _[p][F][""] - _copyarr(_[p][F], v) + if (v == 0 && v == "") { + _mpu(F, p) } else { - if (v == 0 && v == "") { - _mpu(F, p) - } else { - _[p][F] = v - } + _[p][F] = v } } } - return p } + return p +} - function _newclrdir(f) - { - if ((f = _filerd(f)) == "") { - return - } - _cmd("rd " f " /S /Q 2>NUL") +#_________________________________________________________________ +function _newclrdir(f) +{ + ############################################ + if ((f = _filerd(f)) == "") { + return + } + _cmd("rd " f " /S /Q 2>NUL") + _cmd("md " f " 2>NUL") + _WFILEROOTDIR[f] + return f +} + +#_______________________________________________________________________ +function _newdir(f) +{ + ##################################################### + if ((f = _filerd(f)) == "") { + return + } + if (! (f in _WFILEROOTDIR)) { _cmd("md " f " 2>NUL") _WFILEROOTDIR[f] - return f } - - function _newdir(f) - { - if ((f = _filerd(f)) == "") { + return f +} + +############################## +#_______________________________________________________________________ +function _nop(p0, p1, p2, p3) +{ +} + +#_____________________________________________________ +# _retarr(ARRAY,start,prefixtr,postfixtr) +# Return string collected from elements of ARRAY. +# The data elements in ARRAY have numeric indexes. By default it starts from element with index 1, but it is possible to locate elements starting from +# 0,-1,-.... The last data element in the ARRAY have the highest numeric index that is stored in ARRAY[_ARRLEN]. +# Optimized for very large data size. +# +# IN: ARRAY - source data array(is ARRAY is not array then return undefined) +# start - (optional) start index in ARRAY; if missed or have non-numeric value then start array index will be 1. +# prefixst - the string that will be inserted in the begin of generated return string +# postfix - the string that will be added at the end of generated return string +# MOD: - +# OUT: - +# RETURN: undefined - if ARRAY is not array; if ARRAY is empty; if start is higher than ARRAY last element index +# string - collected string: prefixtr-arraydata-postfixtr +#_________________________________________________________________ +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] + while (i < r) { + _ARRSTR = _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] + } + _ARRSTR = _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] v _retarr_i0(A, q, i) return } - if (! (f in _WFILEROOTDIR)) { - _cmd("md " f " 2>NUL") - _WFILEROOTDIR[f] - } - return f - } - - function _nop(p0, p1, p2, p3) - { + _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] v _retarr_i0(A, q, i) + return } - - 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] - while (i < r) { - _ARRSTR = _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] - } - _ARRSTR = _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] v _retarr_i0(A, q, i) - return - } + _ARRSTR = v + return +} + +#___________________________________________________________ +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] + while (i < r) { + _ARRSTR = _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] + } + _ARRSTR = _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] v _retarr_i0(A, q, i) + } else { _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] v _retarr_i0(A, q, i) - return } + } else { _ARRSTR = v - return } - - 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] - while (i < r) { - _ARRSTR = _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] + delete A + A[""] + delete A[""] +} + +#___________________________________________________________________________________ +#################################################################################### + +#___________________________________________________________________________________ +function _out(t, a, b) +{ + ############################################################### + a = BINMODE + b = ORS + BINMODE = "rw" + ORS = "" + print(t) > _SYS_STDOUT + fflush(_SYS_STDOUT) + BINMODE = a + ORS = b + return t +} + +#_________________________________________________________________ +function _outnl(t) +{ + ################################################ + return _out(t ((t ~ /\x0A$/ ? "" : _CHR["EOL"]))) +} + +function _p1(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + _qparamf0 = "_p" _QMAP[_qparamc1--] + return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s1, p1, p2, p3, p4, p5, p6, p7) +} + +function _p2(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + _qparamf0 = "_p" _QMAP[_qparamc1--] + return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s2, p1, p2, p3, p4, p5, p6, p7) +} + +function _p3(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + _qparamf0 = "_p" _QMAP[_qparamc1--] + return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s3, p1, p2, p3, p4, p5, p6, p7) +} + +function _p4(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + _qparamf0 = "_p" _QMAP[_qparamc1--] + return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s4, p1, p2, p3, p4, p5, p6, p7) +} + +function _p5(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + _qparamf0 = "_p" _QMAP[_qparamc1--] + return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s5, p1, p2, p3, p4, p5, p6, p7) +} + +function _p6(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + _qparamf0 = "_p" _QMAP[_qparamc1--] + return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s6, p1, p2, p3, p4, p5, p6, p7) +} + +function _p7(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + _qparamf0 = "_p" _QMAP[_qparamc1--] + return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s7, p1, p2, p3, p4, p5, p6, p7) +} + +function _p8(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + _qparamf0 = "_p" _QMAP[_qparamc1--] + return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s8, p1, p2, p3, p4, p5, p6, p7) +} + +#_______________________________________________________________________ +function _pass(A, f, t, p2, i, a) +{ + ########################################### + a = _endpass_v0 + _endpass_v0 = "" + i = 1 + while (t && i) { + i = "" + while ((i = A[i]) && t == (t = @i(f, t, p2))) { + } + } + if (i && _endpass_v0) { + A["!"] = 1 + t = _endpass_v0 + } else { + delete A["!"] + } + _endpass_v0 = a + return t +} + +# this is somnitelno: that / / . / / com 56 / / - is the DEV...; what is DEV ??? this already PROBLEM +#_____________________________________________________________________________ +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]))) { + D["type"] = "FILE" + A[1] = _patharr0_i0(A[1], D, "drive") + return _patharr0_i1(D, A, 1, q) + } + i = gensub(/ *([\.\?]) */, "\\1", "G", A[2]) + IGNORECASE = 1 + match(A[1], /^((https?)|(ftp)):$/) + IGNORECASE = 0 + if (RLENGTH > 0) { + D["type"] = toupper(substr(A[1], 1, RLENGTH - 1)) + _patharr0_i0(i, D, "site", "port") + } else { + if (A[1] == "") { + D["type"] = "UNC" + if (h > 2) { + D["host"] + A[2] = _patharr0_i0(A[2], D, "drive", "", "FILE") + return _patharr0_i1(D, A, 2, q) } - _ARRSTR = _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] v _retarr_i0(A, q, i) + if (i == "") { + return 1 + } + D["host"] = i + A[3] = _patharr0_i0(A[3], D, "drive", "", "FILE") } else { - _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] v _retarr_i0(A, q, i) + D["type"] = "FILE" + A[1] = _patharr0_i0(A[1], D, "drive") + return _patharr0_i1(D, A, 1, q) } - } else { - _ARRSTR = v } - delete A - A[""] - delete A[""] + return _patharr0_i1(D, A, 3, q) } +} - function _out(t, a, b) - { - a = BINMODE - b = ORS - BINMODE = "rw" - ORS = "" - print(t) > _SYS_STDOUT - fflush(_SYS_STDOUT) - BINMODE = a - ORS = b +#_____________________________________________________ +function _patharr0_i0(t, D, l, r, d, i) +{ + if (i = index(t, ":")) { + if (d) { + D["type"] = d + } + if (i > 1) { + D[l] = substr(t, 1, i - 1) + } + if ((t = substr(t, i + 1)) && r) { + D[r] = t + } return t + } else { + if (t && r) { + D[l] = t + } } + return t +} - function _outnl(t) - { - return _out(t ((t ~ /\x0A$/ ? "" : _CHR["EOL"]))) - } - - function _p1(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - _qparamf0 = "_p" _QMAP[_qparamc1--] - return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s1, p1, p2, p3, p4, p5, p6, p7) +#_____________________________________________________ +function _patharr0_i1(D, A, i, q, t, c) +{ + if (D["type"] == "UNC") { + if (t = A[i++]) { + D[0] = (D["share"] = D[++c] = t) "/" + } else { + return 1 + } } - - function _p2(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - _qparamf0 = "_p" _QMAP[_qparamc1--] - return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s2, p1, p2, p3, p4, p5, p6, p7) + while (i < q) { + D[0] = D[0] (D[++c] = A[i++]) "/" } - - function _p3(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - _qparamf0 = "_p" _QMAP[_qparamc1--] - return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s3, p1, p2, p3, p4, p5, p6, p7) + if (i == q) { + if (match(t = A[i], /\.[^\.]*$/)) { + if (RSTART > 1) { + D["name"] = substr(t, 1, RSTART - 1) + } + D["ext"] = substr(t, RSTART, RLENGTH) + } else { + if (t != "") { + D["name"] = t + } + } } + return 1 +} - function _p4(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - _qparamf0 = "_p" _QMAP[_qparamc1--] - return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s4, p1, p2, p3, p4, p5, p6, p7) - } +############################################################################# - function _p5(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - _qparamf0 = "_p" _QMAP[_qparamc1--] - return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s5, p1, p2, p3, p4, p5, p6, p7) - } - function _p6(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - _qparamf0 = "_p" _QMAP[_qparamc1--] - return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s6, p1, p2, p3, p4, p5, p6, p7) - } - function _p7(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { +function _pmap(m, s1, s2, s3, s4, s5, s6, s7, s8) +{ + if (match(m, /^([^\(]+)\(([^\)]*)\)$/, _QMAP)) { + _qparamf1 = _QMAP[1] + _QMAP[0] = "r" (_qparamc1 = split(_QMAP[2], _QMAP, "")) _qparamf0 = "_p" _QMAP[_qparamc1--] - return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s7, p1, p2, p3, p4, p5, p6, p7) - } - - function _p8(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - _qparamf0 = "_p" _QMAP[_qparamc1--] - return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8, s8, p1, p2, p3, p4, p5, p6, p7) - } - - function _pass(A, f, t, p2, i, a) - { - a = _endpass_v0 - _endpass_v0 = "" - i = 1 - while (t && i) { - i = "" - while ((i = A[i]) && t == (t = @i(f, t, p2))) { + return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8) + } +} + +function _pr0(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + return @_qparamf1() +} + +function _pr1(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + return @_qparamf1(p1) +} + +function _pr2(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + return @_qparamf1(p1, p2) +} + +function _pr3(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + return @_qparamf1(p1, p2, p3) +} + +function _pr4(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + return @_qparamf1(p1, p2, p3, p4) +} + +function _pr5(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + return @_qparamf1(p1, p2, p3, p4, p5) +} + +function _pr6(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + return @_qparamf1(p1, p2, p3, p4, p5, p6) +} + +function _pr7(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + return @_qparamf1(p1, p2, p3, p4, p5, p6, p7) +} + +function _pr8(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) +{ + return @_qparamf1(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 : "") + if (isarray(A)) { + delete _DUMPARR + _dumparrc = _dumparrd = "" + _printarr_i1(A, lv = ((lv == "" ? 16 : (lv == 0 || lv + 0 != 0 ? lv : (lv == "-*" ? -3 : (lv ~ /^\+?\*$/ ? 3 : 16))))) + 0, (lv < 0 ? -1 : 1), 0, _tabtospc(t)) + PROCINFO["sorted_in"] = a + return _retarrd(_DUMPARR, _dumparrd, _dumparrd = "") + } +} + +#___________________________________________________________ +function _printarr_i1(A, lv, ls, ln, t, t2, i, a, f) +{ + t2 = _getchrln(" ", length(t)) + if (ln == lv) { + if (ls > 0) { + for (i in A) { + ++a } - } - if (i && _endpass_v0) { - A["!"] = 1 - t = _endpass_v0 } else { - delete A["!"] + for (i in A) { + (isarray(A[i]) ? ++a : "") + } } - _endpass_v0 = a - return t + if (length(_dumparrd = _dumparrd t ((a > 0 ? " ... (x" a ")" : "")) _CHR["EOL"]) > 262144) { + _conl(_dumparrd) + _dumparrd = "" + } + return } - - 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]))) { - D["type"] = "FILE" - A[1] = _patharr0_i0(A[1], D, "drive") - return _patharr0_i1(D, A, 1, q) - } - i = gensub(/ *([\.\?]) */, "\\1", "G", A[2]) - IGNORECASE = 1 - match(A[1], /^((https?)|(ftp)):$/) - IGNORECASE = 0 - if (RLENGTH > 0) { - D["type"] = toupper(substr(A[1], 1, RLENGTH - 1)) - _patharr0_i0(i, D, "site", "port") - } else { - if (A[1] == "") { - D["type"] = "UNC" - if (h > 2) { - D["host"] - A[2] = _patharr0_i0(A[2], D, "drive", "", "FILE") - return _patharr0_i1(D, A, 2, q) - } - if (i == "") { - return 1 + if (ls >= 0) { + for (i in A) { + if (! _printarrexp || i ~ _printarrexp) { + if (! isarray(A[i])) { + if (length(_dumparrd = _dumparrd ((f ? t2 : t _nop(f = 1))) "[" i "]=" A[i] "'" _CHR["EOL"]) > 262144) { + _conl(_dumparrd) + _dumparrd = "" } - D["host"] = i - A[3] = _patharr0_i0(A[3], D, "drive", "", "FILE") - } else { - D["type"] = "FILE" - A[1] = _patharr0_i0(A[1], D, "drive") - return _patharr0_i1(D, A, 1, q) } } - return _patharr0_i1(D, A, 3, q) } } - - function _patharr0_i0(t, D, l, r, d, i) - { - if (i = index(t, ":")) { - if (d) { - D["type"] = d - } - if (i > 1) { - D[l] = substr(t, 1, i - 1) - } - if ((t = substr(t, i + 1)) && r) { - D[r] = t - } - return t - } else { - if (t && r) { - D[l] = t + for (i in A) { + if (isarray(A[i])) { + if (! _printarrexp || i ~ _printarrexp) { + _printarr_i1(A[i], lv, ls, ln + ls, _th0((f ? t2 : t), f = 1) "[" i "]") } } - return t } - - function _patharr0_i1(D, A, i, q, t, c) - { - if (D["type"] == "UNC") { - if (t = A[i++]) { - D[0] = (D["share"] = D[++c] = t) "/" - } else { - return 1 - } + if (! f) { + if (length(_dumparrd = _dumparrd t _CHR["EOL"]) > 262144) { + _conl(_dumparrd) + _dumparrd = "" } - while (i < q) { - D[0] = D[0] (D[++c] = A[i++]) "/" - } - if (i == q) { - if (match(t = A[i], /\.[^\.]*$/)) { - if (RSTART > 1) { - D["name"] = substr(t, 1, RSTART - 1) - } - D["ext"] = substr(t, RSTART, RLENGTH) + } +} + +function _qparam(qm, p0, p1, p2, p3, p4, p5, p6, p7) +{ + if (qm == qm + 0 && qm > 0) { + _qparamim = substr(" ", 1, qm) + } else { + if (qm != "") { + _qparamim = qm + } else { + _qparamim = " " + } + } + _qparamask = "" + return _qparam_i0(p0, p1, p2, p3, p4, p5, p6, p7) +} + +function _qparam_i0(p0, p1, p2, p3, p4, p5, p6, p7) +{ + _qparama0 = substr(_qparamim, 1, 1) + _qparamim = substr(_qparamim, 2) + switch (_qparama0) { + case "": + gsub(/ +$/, "", _qparamask) + return length(_qparamask) + default: + if (isarray(p0)) { + _qparama0 = "A" + } else { + if (p0 == "" && p0 == 0) { + _qparama0 = " " } else { - if (t != "") { - D["name"] = t + if (_isptr(p0)) { + _qparama0 = "P" + } else { + _qparama0 = "S" } } } - return 1 + case ".": + _qparamask = _qparamask _qparama0 + return _qparam_i0(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 + } + return c +} + +#_________________________________________________________________ +function _qstrq(t) +{ + ################################################ + gsub(/\\/, "\\\\", t) + gsub(/"/, "\\\"", t) + return t +} + +################################################################ +#_____________________________________________________________________________ +function _rEG(c, t, P, a, A) +{ + ##################################################### + switch (c) { + case "_lib_CMDLN": + #___________________________________________________________ + return t + #_____________________________________________________ + case "_lib_APPLY": + return + #_____________________________________________________ + case "_lib_HELP": + return + #_____________________________________________________ + case "_lib_NAMEVER": + return _ln("_reg 0.001") + #_____________________________________________________ + case "_lib_BEGIN": + return + #_____________________________________________________ + case "_lib_END": + return } +} - function _pmap(m, s1, s2, s3, s4, s5, s6, s7, s8) - { - if (match(m, /^([^\(]+)\(([^\)]*)\)$/, _QMAP)) { - _qparamf1 = _QMAP[1] - _QMAP[0] = "r" (_qparamc1 = split(_QMAP[2], _QMAP, "")) - _qparamf0 = "_p" _QMAP[_qparamc1--] - return @_qparamf0(s1, s2, s3, s4, s5, s6, s7, s8) +#_______________________________________________________________________ +function _rFBRO(p) +{ + ###################################################### + if (p) { + if (p in _tPARENT) { + return _tFCHLD[_tPARENT[p]] } + while (p in _tPREV) { + p = _tPREV[p] + } + return p } - - function _pr0(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - return @_qparamf1() - } - - function _pr1(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - return @_qparamf1(p1) - } - - function _pr2(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - return @_qparamf1(p1, p2) + return 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]] + } + while (p in _tNEXT) { + p = _tNEXT[p] + } + return p } - - function _pr3(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - return @_qparamf1(p1, p2, p3) + return p +} + +######################## p="" +#_______________________________________________________________________ +function _rLCHLD(p) +{ + ##################################################### + if (p && p in _tLCHLD) { + return _tLCHLD[p] + } + return "" +} + +#_______________________________________________________________________ +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]] + } + c = 1 + p1 = p + while (p1 in _tPREV) { + c++ + p1 = _tPREV[p1] + } + while (p in _tNEXT) { + c++ + p = _tNEXT[p] + } + return c } - - function _pr4(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - return @_qparamf1(p1, p2, p3, p4) + return p +} + +######################## p="" +#_______________________________________________________________________ +function _rQCHLD(p) +{ + ##################################################### + if (p && p in _tQCHLD) { + return _tQCHLD[p] + } + return "" +} + +#___________________________________________________________________________________ +# EMMULATED FUNCTIONAL FIELDS ###################################################### + +#_____________________________________________________________________________ +function _rSQFIRST(g, p, A) +{ + ##################################################### + if (isarray(A)) { + return _rSQFIRSTA(g, p, A) + } + _SQTOPTR[g] = p + _SQSTACK[g][0] = 0 + return _rsqgetptr(g, p) +} + +#_________________________________________________________________ +function _rSQFIRSTA(g, p, A) +{ + ######################################## + _SQTOPTR[g] = p + _SQSTACK[g][0] = 0 + if ((p = _rsqgetptr(g, p)) in A) { + return p } + return _rSQNEXTA(g, p, A) +} - function _pr5(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - return @_qparamf1(p1, p2, p3, p4, p5) +#_______________________________________________________________________ +function _rSQNEXT(g, p, A) +{ + ################################################ + if (isarray(A)) { + return _rSQNEXTA(g, p, A) } + return _rsqnext_i0(g, p) +} - function _pr6(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - return @_qparamf1(p1, p2, p3, p4, p5, p6) +#_________________________________________________________________ +function _rSQNEXTA(g, p, A) +{ + ######################################### + if (p == _SQTOPTR[g]) { + if (_SQSTACK[g][0] > 0) { + _SQTOPTR[g] = _SQSTACK[g][_SQSTACK[g][0]--] + return _rSQNEXTA(g, _SQSTACK[g][_SQSTACK[g][0]--], A) + } + return } - - function _pr7(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - return @_qparamf1(p1, p2, p3, p4, p5, p6, p7) + while (p in _tNEXT) { + if ((p = _rsqgetptr(g, _tNEXT[p])) in A) { + return p + } } + return ((p in _tPARENT ? _rSQNEXTA(g, _tPARENT[p], A) : "")) +} - function _pr8(s1, s2, s3, s4, s5, s6, s7, s8, p1, p2, p3, p4, p5, p6, p7, p8) - { - return @_qparamf1(p1, p2, p3, p4, p5, p6, p7, p8) - } +function _rconl(t) +{ + _rprt = _rprt _ln(t) +} - function _printarr(A, t, lv, r, a) - { - a = PROCINFO["sorted_in"] - PROCINFO["sorted_in"] = "_lengthsort" - _printarrexp = (r ? r : "") - if (isarray(A)) { - delete _DUMPARR - _dumparrc = _dumparrd = "" - _printarr_i1(A, lv = ((lv == "" ? 16 : (lv == 0 || lv + 0 != 0 ? lv : (lv == "-*" ? -3 : (lv ~ /^\+?\*$/ ? 3 : 16))))) + 0, (lv < 0 ? -1 : 1), 0, _tabtospc(t)) - PROCINFO["sorted_in"] = a - return _retarrd(_DUMPARR, _dumparrd, _dumparrd = "") - } - } +function _rconline(t) +{ + _rprt = _rprt _ln((t = " " t " ") _getchrln("_", _CON_WIDTH - length(t) - 1)) +} - function _printarr_i1(A, lv, ls, ln, t, t2, i, a, f) - { - t2 = _getchrln(" ", length(t)) - if (ln == lv) { - if (ls > 0) { - for (i in A) { - ++a - } - } else { - for (i in A) { - (isarray(A[i]) ? ++a : "") - } - } - if (length(_dumparrd = _dumparrd t ((a > 0 ? " ... (x" a ")" : "")) _CHR["EOL"]) > 262144) { - _conl(_dumparrd) - _dumparrd = "" - } - return - } - if (ls >= 0) { - for (i in A) { - if (! _printarrexp || i ~ _printarrexp) { - if (! isarray(A[i])) { - if (length(_dumparrd = _dumparrd ((f ? t2 : t _nop(f = 1))) "[" i "]=" A[i] "'" _CHR["EOL"]) > 262144) { - _conl(_dumparrd) - _dumparrd = "" - } - } - } - } - } - for (i in A) { - if (isarray(A[i])) { - if (! _printarrexp || i ~ _printarrexp) { - _printarr_i1(A[i], lv, ls, ln + ls, _th0((f ? t2 : t), f = 1) "[" i "]") +#___________________________________________________________ +function _rd_shortcut(D, f) +{ + if ((_shrtcutf0 = _filepath(f)) && _shortcut_nerr(_shrtcuta0 = _cmd(_shortcut_fpath " /A:Q /F:\"" _shrtcutf0 "\" 2>&1"), _shrtcutf0)) { + ERRNO = "" + split(_shrtcuta0, _SHRTCUTA0, /\x0D?\x0A/) + for (_shrtcuta0 in _SHRTCUTA0) { + for (f in _SHORTCUTRSTRUC) { + if (match(_SHRTCUTA0[_shrtcuta0], "^" f)) { + D[_SHORTCUTRSTRUC[f]] = substr(_SHRTCUTA0[_shrtcuta0], 1 + RLENGTH) } } } - if (! f) { - if (length(_dumparrd = _dumparrd t _CHR["EOL"]) > 262144) { - _conl(_dumparrd) - _dumparrd = "" - } - } } + return ((ERRNO ? ERRNO = "read shortcut: " ERRNO : _NOP)) +} - function _qparam(qm, p0, p1, p2, p3, p4, p5, p6, p7) - { - if (qm == qm + 0 && qm > 0) { - _qparamim = substr(" ", 1, qm) - } else { - if (qm != "") { - _qparamim = qm +#_______________________________________________________________________ +function _rdfile(f, i, A) +{ + ################################################ + if ((f = _filerdne(f)) == "" || _filene(f) == "") { + ERRNO = "Filename error" + return + } + _fio_cmda = RS + RS = ".{1,}" + _fio_cmdb = BINMODE + BINMODE = "rw" + ERRNO = RT = _NUL + getline RS < f + BINMODE = _fio_cmdb + RS = _fio_cmda + if (ERRNO == "") { + close(f) + } + if (ERRNO == "") { + return RT + } + return (RT = _NOP) +} + +#################################################################################### +# PUBLIC: +#_____________________________________________________________________________ +# fn _th0,_th1,_th2,_th3 +# USAGE: +# _th0(p1,p2,p3,p4) +# +# Each of this functions can have up to 4 parameters. +# _th0(p1,p2,p3,p4) return 1st parameter (p1) +# _th1(p1,p2,p3,p4) return 2nd parameter (p2) +# _th2(p1,p2,p3,p4) return 3rd parameter (p3) +# _th3(p1,p2,p3,p4) return 4th parameter (p4) +#_____________________________________________________________________________ +# fn _nop(p1,p2,p3,p4,p5,p6,p7,p8) +# USAGE: +# _nop() +# +# Does not do any action. No result returned. Up to 8 parameters. +#_____________________________________________________________________________ +# fn _exit(c) +# USAGE: +# _exit(code) +# +# This function do the same as GAWK-operator `exit code'. +#_____________________________________________________________________________ +# fn _getdate() +# fn _getime() +# fn _getsecond() +# 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/) + while (_rdregq0 > 0) { + _rdreg_i0(D) + } + return (_rdregfld + _rdregkey) +} + +#___________________________________________________________ +function _rdreg_i0(D, A) +{ + while (_rdregq0 > 0) { + if (match(_rdregp0 = _RDREGA0[_rdregq0--], / (.*) REG_((SZ)|(DWORD)|(QWORD)|(BINARY)|(EXPAND_SZ)|(MULTI_SZ)) (.*)$/, A)) { + if (! _rdreg_i0(D)) { + ++_rdregfld + D[_rdregp0 A[1] "." _RDREGTYPE[A[2]]] = A[9] + return } else { - _qparamim = " " + break } - } - _qparamask = "" - return _qparam_i0(p0, p1, p2, p3, p4, p5, p6, p7) - } - - function _qparam_i0(p0, p1, p2, p3, p4, p5, p6, p7) - { - _qparama0 = substr(_qparamim, 1, 1) - _qparamim = substr(_qparamim, 2) - switch (_qparama0) { - case "": - gsub(/ +$/, "", _qparamask) - return length(_qparamask) - default: - if (isarray(p0)) { - _qparama0 = "A" - } else { - if (p0 == "" && p0 == 0) { - _qparama0 = " " - } else { - if (_isptr(p0)) { - _qparama0 = "P" - } else { - _qparama0 = "S" - } - } + } else { + if (_rdregp0 ~ /^HK/) { + ++_rdregkey + return D[_rdregp0 = _rdregp0 "\\"] } - case ".": - _qparamask = _qparamask _qparama0 - return _qparam_i0(p1, p2, p3, p4, p5, p6, p7) } } + return 1 +} - 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 - } - return c - } +#_____________________________________________________________________________________________________ +###################################################################################################### - function _qstrq(t) - { - gsub(/\\/, "\\\\", t) - gsub(/"/, "\\\"", t) - return t - } - function _rEG(c, t, P, a, A) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return _ln("_reg 0.001") - case "_lib_BEGIN": - return - case "_lib_END": - return - } - } - function _rFBRO(p) - { - if (p) { - if (p in _tPARENT) { - return _tFCHLD[_tPARENT[p]] - } - while (p in _tPREV) { - p = _tPREV[p] - } - return p - } - return p - } - function _rFCHLD(p) - { - if (p && p in _tFCHLD) { - return _tFCHLD[p] - } - return "" - } - function _rLBRO(p) - { - if (p) { - if (p in _tPARENT) { - return _tLCHLD[_tPARENT[p]] - } - while (p in _tNEXT) { - p = _tNEXT[p] - } - return p - } - return p - } - function _rLCHLD(p) - { - if (p && p in _tLCHLD) { - return _tLCHLD[p] - } - return "" - } - function _rLINK(p) - { - return ((p in _tLINK ? _tLINK[p] : "")) - } - function _rNEXT(p) - { - if (p && p in _tNEXT) { - return _tNEXT[p] - } - return "" - } - function _rPARENT(p) - { - if (p && p in _tPARENT) { - return _tPARENT[p] - } - return "" - } - function _rPREV(p) - { - if (p && p in _tPREV) { - return _tPREV[p] - } - return "" - } - function _rQBRO(p, c, p1) - { - if (p) { - if (p in _tPARENT) { - return _tQCHLD[_tPARENT[p]] - } - c = 1 - p1 = p - while (p1 in _tPREV) { - c++ - p1 = _tPREV[p1] - } - while (p in _tNEXT) { - c++ - p = _tNEXT[p] - } - return c - } - return p - } - function _rQCHLD(p) - { - if (p && p in _tQCHLD) { - return _tQCHLD[p] - } - return "" - } - function _rSQFIRST(g, p, A) - { - if (isarray(A)) { - return _rSQFIRSTA(g, p, A) - } - _SQTOPTR[g] = p - _SQSTACK[g][0] = 0 - return _rsqgetptr(g, p) - } - function _rSQFIRSTA(g, p, A) - { - _SQTOPTR[g] = p - _SQSTACK[g][0] = 0 - if ((p = _rsqgetptr(g, p)) in A) { - return p - } - return _rSQNEXTA(g, p, A) - } - function _rSQNEXT(g, p, A) - { - if (isarray(A)) { - return _rSQNEXTA(g, p, A) - } - return _rsqnext_i0(g, p) - } - function _rSQNEXTA(g, p, A) - { - if (p == _SQTOPTR[g]) { - if (_SQSTACK[g][0] > 0) { - _SQTOPTR[g] = _SQSTACK[g][_SQSTACK[g][0]--] - return _rSQNEXTA(g, _SQSTACK[g][_SQSTACK[g][0]--], A) - } - return - } - while (p in _tNEXT) { - if ((p = _rsqgetptr(g, _tNEXT[p])) in A) { - return p - } - } - return ((p in _tPARENT ? _rSQNEXTA(g, _tPARENT[p], A) : "")) - } - function _rconl(t) - { - _rprt = _rprt _ln(t) - } - function _rconline(t) - { - _rprt = _rprt _ln((t = " " t " ") _getchrln("_", _CON_WIDTH - length(t) - 1)) - } - function _rd_shortcut(D, f) - { - if ((_shrtcutf0 = _filepath(f)) && _shortcut_nerr(_shrtcuta0 = _cmd(_shortcut_fpath " /A:Q /F:\"" _shrtcutf0 "\" 2>&1"), _shrtcutf0)) { - ERRNO = "" - split(_shrtcuta0, _SHRTCUTA0, /\x0D?\x0A/) - for (_shrtcuta0 in _SHRTCUTA0) { - for (f in _SHORTCUTRSTRUC) { - if (match(_SHRTCUTA0[_shrtcuta0], "^" f)) { - D[_SHORTCUTRSTRUC[f]] = substr(_SHRTCUTA0[_shrtcuta0], 1 + RLENGTH) - } - } - } - } - return ((ERRNO ? ERRNO = "read shortcut: " ERRNO : _NOP)) - } - function _rdfile(f, i, A) - { - if ((f = _filerdne(f)) == "" || _filene(f) == "") { - ERRNO = "Filename error" - return - } - _fio_cmda = RS - RS = ".{1,}" - _fio_cmdb = BINMODE - BINMODE = "rw" - ERRNO = RT = _NUL - getline RS < f - BINMODE = _fio_cmdb - RS = _fio_cmda - if (ERRNO == "") { - close(f) - } - if (ERRNO == "") { - return RT - } - return (RT = _NOP) - } - 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/) - while (_rdregq0 > 0) { - _rdreg_i0(D) - } - return (_rdregfld + _rdregkey) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +function _rdsafe(A, i, d) +{ + if (i in A) { + return A[i] } + return d +} - function _rdreg_i0(D, A) - { - while (_rdregq0 > 0) { - if (match(_rdregp0 = _RDREGA0[_rdregq0--], / (.*) REG_((SZ)|(DWORD)|(QWORD)|(BINARY)|(EXPAND_SZ)|(MULTI_SZ)) (.*)$/, A)) { - if (! _rdreg_i0(D)) { - ++_rdregfld - D[_rdregp0 A[1] "." _RDREGTYPE[A[2]]] = A[9] - return +#_______________________________________________________________________ +function _reg_check(p) +{ + _tframe("_reg_check_i0", p, p) +} + +#_______________________________________________ +function _reg_check_i0(p, pp, p1, p2) +{ + if (_[p]["TYPE"] == "defreg") { + if (_[p]["REGPATH"] in _REG) { + if ("VALUE" in _[p]) { + if (_[p]["VALUE"] == _REG[_[p]["REGPATH"]]) { + _creport(p, substr("OK: REGENTRY MATCH(==" _[p]["VALUE"] "): " _[p]["REGPATH"], 1, 126)) } else { - break + _dllerr(p, substr("REGENTRY NOT MATCH(!=" _[p]["VALUE"] "): " _[p]["REGPATH"], 1, 126)) } } else { - if (_rdregp0 ~ /^HK/) { - ++_rdregkey - return D[_rdregp0 = _rdregp0 "\\"] + if (_VAR[_[p]["REGPATH"]] == _REG[_[p]["REGPATH"]]) { + _creport(p, substr("OK: REGPATH MATCH(==" _VAR[_[p]["REGPATH"]] "): " _[p]["REGPATH"], 1, 126)) + } else { + _dllerr(p, substr("REGPATH NOT MATCH(!=" _VAR[_[p]["REGPATH"]] "): " _[p]["REGPATH"], 1, 126)) } } + } else { + _dllerr(p, substr("REGPATH NOT FOUND: " _[p]["REGPATH"], 1, 126)) } - return 1 - } - - function _rdsafe(A, i, d) - { - if (i in A) { - return A[i] - } - return d } +} - function _reg_check(p) - { - _tframe("_reg_check_i0", p, p) - } +#_____________________________________________________ +function _registryinit() +{ + _registrytmpfile = _getmpfile() +} - function _reg_check_i0(p, pp, p1, p2) - { - if (_[p]["TYPE"] == "defreg") { - if (_[p]["REGPATH"] in _REG) { - if ("VALUE" in _[p]) { - if (_[p]["VALUE"] == _REG[_[p]["REGPATH"]]) { - _creport(p, substr("OK: REGENTRY MATCH(==" _[p]["VALUE"] "): " _[p]["REGPATH"], 1, 126)) - } else { - _dllerr(p, substr("REGENTRY NOT MATCH(!=" _[p]["VALUE"] "): " _[p]["REGPATH"], 1, 126)) - } +# _rdregfld : gvar - number of readed registry fields by _rdreg() +# _rdregkey : gvar - number of readed registry keys by _rdreg() +#_____________________________________________________________________________ +function _regpath0(D, i, s, q, S) +{ + ############################################ 0 # + if (i = _patharr0(S, i)) { + if ("name" in S) { + D["name"] = S["name"] + } + if ("ext" in S) { + D["ext"] = S["ext"] + } + s = ((toupper(s = (i in S ? S[i] : "")) in _REGPATH0REGDIR ? D[++q] = _REGPATH0REGDIR[toupper(s)] : (D[++q] = _REGPATH0REGDIR[""]) "\\" (D[++q] = s))) "\\" + while (++i in S) { + s = s (D[++q] = S[i]) "\\" + } + if (s != "") { + D[0] = s + } + IGNORECASE = 1 + D["hostdir"] = "\\\\" (D["host"] = ("host" in S && ("" == (i = S["host"]) || "." == i || "?" == i || "localhost" == i) ? ENVIRON["COMPUTERNAME"] : i)) "\\" s + IGNORECASE = 0 + } +} + +#_________________________________________________________________________________________ +function _report(p) +{ + ####################################################################### + _report_t0 = _reportparnt = "" + _report_i0(p) + _tframe("_report_i0", p) + return _report_t0 +} + +function _report_i0(p, p0, p1, p2) +{ + if (p in _tPARENT) { + if (_reportparnt != (_reportparnt = _tPARENT[p])) { + _report_t0 = _report_t0 _ln() _ln((z = "_ " _[_tPARENT[p]]["NAME"] " ") _getchrln("_", _CON_WIDTH - length(z) - 2)) _ln(_getchrln("#", _CON_WIDTH - 2)) _ln() + } + } + if ("ERROR" in _[p]) { + _report_t0 = _report_t0 _reporterr(p, _[p]["ERROR"]) + } + if ("REPORT" in _[p]) { + _report_t0 = _report_t0 _ln(_[p]["REPORT"]) + } +} + +#___________________________________________________________________________________ +function _reporterr(p, t3, pp, t, t2) +{ + t = "" + pp = p + do { + ("NAME" in _[pp] ? t = _[pp]["NAME"] ": " t : "") + } while (pp = _rPARENT(pp)) + if (match(t3, /\x00/)) { + return (substr(t3, 1, RSTART - 1) t substr(t3, RSTART + 1)) + } + return (t t3) +} + +#___________________________________________________________________________________ +#################################################################################### + + + + +#_______________________________________________________________________ +# _CHR array +# +# _CHR[ASC-code decimal number]=="char" +# +# Contains 256 elements. The index is the decimal number from 0-255. +# The value is the single character with ASC-code equivalent to index number: +# +# _CHR[97] =="a" - character with ASC-code 97 is `a' +# +# This array is useful if you want to get character using it's ASC-code +#_________________________________________________________________ +# _ASC array +# +# _ASC[char]==number: ASC-code of char +# +# Contains 256 elements. The index is the any single character with ASC-code \x00-\xFF. +# The value is the number equivalent of character's ASC-code: +# +# _ASC["A"] ==65 - ASC-code of character `A' is 65 +# +# This array is useful if you want to get ASC-code of the character. +#_________________________________________________________________ +# _QASC array +# +# _QASC[char]=="string: octal ASC-code of char in 3-digit octal format" +# +# Contains 256 elements. The index is the any single charcter with ASC-code \x00-\xFF. +# The value is the octal number equivalent of character's ASC-code in fixed-length - 3-digit - string: +# +# _QASC["!"] =="041" - ASC-code of character `!' is 33(decimal) == 41(in octal) +# _QASC["\x0D"] =="015" +# +# This array is useful when some type of string escape conversion is performed. It allows quickly get +# replace string for the characters that can be specified only by character code in result string: +# +# "\x0D" -> "\\015" +#_______________________________________________________________________ + + + + + + + +#################################################################################### +# PUBLIC: +#_____________________________________________________________________________ +# fn _getchrln(ptt,len) +#_____________________________________________________________________________ +# fn _tabtospc(src,tabstep,xcoord) +#################################################################################### + +#_____________________________________________________________________________ +function _retarr(A, i, p, a, q) +{ + ################################################## + if (isarray(A)) { + i = (i == "" ? 0 : i + 0) + q = A[_ARRLEN] + 0 + if (i < q) { + return (p 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] _retarr_i0(A, q, i, a)) + } + } +} + +function _retarr_i0(A, q, i, a) +{ + if (i < q) { + return (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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] _retarr_i0(A, q, i, a)) + } + while (q < i) { + delete A[++q] + } + return 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))) + } + delete A + return v +} + +#_____________________________________________________ +function _retarrd_i0(A, i) +{ + if (i in A) { + return (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++] ((i in A ? _retarrd_i0(A, i) : ""))) + } + delete A +} + +#_______________________________________________________________________ +######################################################################## +#EXPERIMENTAL + +function _rexpfn(R, t, p) +{ + _REXPFN[""] = "" + while (t) { + t = _rxpfn(R, t, p) + } + return _REXPFN[""] +} + +function _rexpfnend(t) +{ + _REXPFN[""] = t +} + +#_____________________________________________________________________________ +function _rexpstr(r, i, c, A) +{ + ################################################### + c = split(r, A, "") + r = "" + for (i = 1; i <= c; i++) { + r = r _REXPSTR[A[i]] + } + return r +} + +#_____________________________________________________________________________ +function _rexpstr_i0(t, A, p0) +{ + return (_REXPSTR[t] = "\\" t) +} + +#___________________________________________________________ +function _rmtsharerr(h, t) +{ + gsub(/[\x0D\x0A]+/, "", t) + if (t ~ /^The command failed: 53/) { + ERRNO = "host not found: \\\\" h + } else { + ERRNO = t ": \\\\" h + } +} + +function _rpp(q, D, S) +{ + _conl() + _conline(q) + _conl() + _regpath0(D, q) + #_conl(_dumparr(D)) + + _conl(_ln("DEST:") _dumparr(D)) + _conl() + return q +} + +#_________________________________________________________________________________________ +function _rrdreg(DD, p, k, t, v, c, i, q, tT, A, B, C, D) +{ + ############################################# old; regedit + if (! _registrytmpfile) { + _registryinit() + } + _cmd("regedit /E \"" _registrytmpfile "\" \"" p "\" 2>&1") + q = patsplit(gensub(/[\x00\xFF\xFE]+/, "", "G", _rdfile(_registrytmpfile)), A, /\x0D?\x0A\[[^\]]+\]\x0D?\x0A/, B) + for (i = 1; i <= q; i++) { + p = gensub(/(^[ \t\x0D\x0A]*\[)|((\\)\\+)|(\][ \t\x0D\x0A]*$)/, "\\3", "G", A[i]) + DD[p "\\"] + delete C[split(B[i], C, /[\x0D\x0A]+/)] + for (c = 1; c in C; c++) { + tt = tt C[c] + if (gsub(/\\$/, "", tt)) { + continue + } + if (tt == "") { + continue + } + if (match(_th0(tt, tt = ""), /((^"(([^\\"]|\\.)*)")|(@))=(("(([^\\"]|\\.)*)")|(dword:([[:xdigit:]]{8}))|(hex(\(([27b])\))?:(.*)))$/, D)) { + if (D[7]) { + t = "STR" + v = _unstr(D[8]) } else { - if (_VAR[_[p]["REGPATH"]] == _REG[_[p]["REGPATH"]]) { - _creport(p, substr("OK: REGPATH MATCH(==" _VAR[_[p]["REGPATH"]] "): " _[p]["REGPATH"], 1, 126)) + if (D[10]) { + t = "W32" + v = D[11] } else { - _dllerr(p, substr("REGPATH NOT MATCH(!=" _VAR[_[p]["REGPATH"]] "): " _[p]["REGPATH"], 1, 126)) + v = D[15] + if (D[13]) { + switch (D[14]) { + case "2": + t = "XSZ" + break + case "7": + t = "MSZ" + break + default: + t = "W64" + } + } else { + t = "BIN" + } } } + DD[gensub(/(\\)\\+/, "\\1", "G", p "\\" _unstr(D[3] ((D[5] ? "(Default)" : ""))) "." t)] = v } else { - _dllerr(p, substr("REGPATH NOT FOUND: " _[p]["REGPATH"], 1, 126)) + _fatal("regedit: unknown output format(" c "): `" C[c] "'") } } } +} - function _registryinit() - { - _registrytmpfile = _getmpfile() - } - - function _regpath0(D, i, s, q, S) - { - if (i = _patharr0(S, i)) { - if ("name" in S) { - D["name"] = S["name"] - } - if ("ext" in S) { - D["ext"] = S["ext"] - } - s = ((toupper(s = (i in S ? S[i] : "")) in _REGPATH0REGDIR ? D[++q] = _REGPATH0REGDIR[toupper(s)] : (D[++q] = _REGPATH0REGDIR[""]) "\\" (D[++q] = s))) "\\" - while (++i in S) { - s = s (D[++q] = S[i]) "\\" - } - if (s != "") { - D[0] = s - } - IGNORECASE = 1 - D["hostdir"] = "\\\\" (D["host"] = ("host" in S && ("" == (i = S["host"]) || "." == i || "?" == i || "localhost" == i) ? ENVIRON["COMPUTERNAME"] : i)) "\\" s - IGNORECASE = 0 +#_________________________________________________________________ +function _rsqgetptr(g, p, A) +{ + if (p in _tLINK) { + _SQSTACK[g][++_SQSTACK[g][0]] = p + _SQSTACK[g][++_SQSTACK[g][0]] = _SQTOPTR[g] + while ((p = _tLINK[p]) in _tLINK) { + _con(".") } + _SQTOPTR[g] = p } - - function _report(p) - { - _report_t0 = _reportparnt = "" - _report_i0(p) - _tframe("_report_i0", p) - return _report_t0 - } - - function _report_i0(p, p0, p1, p2) - { - if (p in _tPARENT) { - if (_reportparnt != (_reportparnt = _tPARENT[p])) { - _report_t0 = _report_t0 _ln() _ln((z = "_ " _[_tPARENT[p]]["NAME"] " ") _getchrln("_", _CON_WIDTH - length(z) - 2)) _ln(_getchrln("#", _CON_WIDTH - 2)) _ln() - } - } - if ("ERROR" in _[p]) { - _report_t0 = _report_t0 _reporterr(p, _[p]["ERROR"]) - } - if ("REPORT" in _[p]) { - _report_t0 = _report_t0 _ln(_[p]["REPORT"]) - } + if (p in _tFCHLD) { + return _rsqgetptr(g, _tFCHLD[p]) } + return p +} - function _reporterr(p, t3, pp, t, t2) - { - t = "" - pp = p - do { - ("NAME" in _[pp] ? t = _[pp]["NAME"] ": " t : "") - } while (pp = _rPARENT(pp)) - if (match(t3, /\x00/)) { - return (substr(t3, 1, RSTART - 1) t substr(t3, RSTART + 1)) +#___________________________________________________________ +function _rsqnext_i0(g, p) +{ + if (p == _SQTOPTR[g]) { + if (_SQSTACK[g][0] > 0) { + _SQTOPTR[g] = _SQSTACK[g][_SQSTACK[g][0]--] + return _rsqnext_i0(g, _SQSTACK[g][_SQSTACK[g][0]--]) } - return (t t3) + return } - - function _retarr(A, i, p, a, q) - { - if (isarray(A)) { - i = (i == "" ? 0 : i + 0) - q = A[_ARRLEN] + 0 - if (i < q) { - return (p 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] _retarr_i0(A, q, i, a)) + if (p in _tNEXT) { + return _rsqgetptr(g, _tNEXT[p]) + } + return _rsqnext_i0(g, _tPARENT[p]) +} + +function _rtn(v, A) +{ + _conl() + _conline(_val(v) " : " _val(A)) + _conl() + _rtn2(v, A) + _conl() +} + +function _rtn2(v, A, r, t) +{ + r = (isarray(A) ? _typa(v, A) : _typ(v)) + if ("`" > _t0 && _t0) { + _conl("ggggg") + } + t = ((r ? "TRUE" : "FALSE")) " / " ((r > 0 ? r ">0" : r "!>0")) " / " ((r + 0 > 0 ? r "+0>0" : r "+0!>0")) " / " ((r + 0 != r ? r "+0!=" r : r "+0==" r)) " / " ((r && "`" > r ? "'`'>" r " && " r : "!('`'>" r " && " r ")")) + _conl("`" r "' : " t) + return r +} + +function _rxpfn(R, t, p, i, f, A) +{ + for (i in R) { + if (match(t, i, A)) { + f = R[i] + if (t != (t = @f(A, substr(t, RLENGTH + 1), p))) { + return t } } } + return _rexpfnend(t) +} - function _retarr_i0(A, q, i, a) - { - if (i < q) { - return (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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] _retarr_i0(A, q, i, a)) - } - while (q < i) { - delete A[++q] - } - return a +############################################################## +#_____________________________________________________________________________ +function _sHARE(c, t, P, a, A) +{ + ################################################### + switch (c) { + case "_lib_CMDLN": + #___________________________________________________________ + return t + #_____________________________________________________ + case "_lib_APPLY": + return + #_____________________________________________________ + case "_lib_HELP": + return + #_____________________________________________________ + case "_lib_NAMEVER": + return _ln("_share 1.000") + #_____________________________________________________ + case "_lib_BEGIN": + return + #_____________________________________________________ + case "_lib_END": + return } +} - 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))) - } - delete A - return v +################################################################ +#_____________________________________________________________________________ +function _sYS(c, t, P, a, A) +{ + ##################################################### + switch (c) { + case "_lib_CMDLN": + #___________________________________________________________ + return t + #_____________________________________________________ + case "_lib_APPLY": + return + #_____________________________________________________ + case "_lib_HELP": + return + #_____________________________________________________ + case "_lib_NAMEVER": + return + #_____________________________________________________ + case "_lib_BEGIN": + return + #_____________________________________________________ + case "_lib_END": + return } +} - function _retarrd_i0(A, i) - { - if (i in A) { - return (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++] ((i in A ? _retarrd_i0(A, i) : ""))) - } - delete A - } +#_______________________________________________________________________ +function _serv_check(p) +{ + _tframe("_serv_check_i0", p, p) +} - function _rexpfn(R, t, p) - { - _REXPFN[""] = "" - while (t) { - t = _rxpfn(R, t, p) +#_______________________________________________ +function _serv_check_i0(p, p0, p1, p2, p3, i, q, c) +{ + if (_[p]["TYPE"] == "defsrv") { + i = IGNORECASE + IGNORECASE = 1 + if (match(_servoutput, roi = "\\012DISPLAY_NAME: " _torexp(_[p]["SERVNAME"]))) { + _creport(p, "OK: SERVICE DETECTED: " substr(_[p]["SERVNAME"], 1, 112)) + } else { + _dllerr(p, "service " _[p]["SERVNAME"] " not detected") } - return _REXPFN[""] } + IGNORECASE = i +} - function _rexpfnend(t) - { - _REXPFN[""] = t +#_______________________________________________________________________ +function _setarrsort(f, a) +{ + ############################################## + a = PROCINFO["sorted_in"] + if (! f) { + delete PROCINFO["sorted_in"] + } else { + PROCINFO["sorted_in"] = f } + return a +} - function _rexpstr(r, i, c, A) - { - c = split(r, A, "") - r = "" - for (i = 1; i <= c; i++) { - r = r _REXPSTR[A[i]] +#_______________________________________________________________________ +function _setmpath(p, a) +{ + ################################################ + ERRNO = "" + if (p && (a = _filerd(p))) { + if (_FILEIO_TMPRD) { + _FILEIO_TMPATHS[_FILEIO_TMPRD] } - return r + #if ( _filexist(a) ) _del(a) + #_cmd("rd " a " /S /Q 2>NUL"); _cmd("del " a " /Q 2>NUL") + return (_FILEIO_TMPRD = a) + } else { + return _warning("`" p "': cannot set temporary folder" ((ERRNO ? ": " ERRNO : ""))) } +} - function _rexpstr_i0(t, A, p0) - { - return (_REXPSTR[t] = "\\" t) - } +#_________________________________________________________________________________________ +########################################################################################## - function _rmtsharerr(h, t) - { - gsub(/[\x0D\x0A]+/, "", t) - if (t ~ /^The command failed: 53/) { - ERRNO = "host not found: \\\\" h - } else { - ERRNO = t ": \\\\" h - } - } - function _rpp(q, D, S) - { - _conl() - _conline(q) - _conl() - _regpath0(D, q) - _conl(_ln("DEST:") _dumparr(D)) - _conl() - return q - } - function _rrdreg(DD, p, k, t, v, c, i, q, tT, A, B, C, D) - { - if (! _registrytmpfile) { - _registryinit() - } - _cmd("regedit /E \"" _registrytmpfile "\" \"" p "\" 2>&1") - q = patsplit(gensub(/[\x00\xFF\xFE]+/, "", "G", _rdfile(_registrytmpfile)), A, /\x0D?\x0A\[[^\]]+\]\x0D?\x0A/, B) - for (i = 1; i <= q; i++) { - p = gensub(/(^[ \t\x0D\x0A]*\[)|((\\)\\+)|(\][ \t\x0D\x0A]*$)/, "\\3", "G", A[i]) - DD[p "\\"] - delete C[split(B[i], C, /[\x0D\x0A]+/)] - for (c = 1; c in C; c++) { - tt = tt C[c] - if (gsub(/\\$/, "", tt)) { - continue - } - if (tt == "") { - continue - } - if (match(_th0(tt, tt = ""), /((^"(([^\\"]|\\.)*)")|(@))=(("(([^\\"]|\\.)*)")|(dword:([[:xdigit:]]{8}))|(hex(\(([27b])\))?:(.*)))$/, D)) { - if (D[7]) { - t = "STR" - v = _unstr(D[8]) - } else { - if (D[10]) { - t = "W32" - v = D[11] - } else { - v = D[15] - if (D[13]) { - switch (D[14]) { - case "2": - t = "XSZ" - break - case "7": - t = "MSZ" - break - default: - t = "W64" - } - } else { - t = "BIN" - } - } - } - DD[gensub(/(\\)\\+/, "\\1", "G", p "\\" _unstr(D[3] ((D[5] ? "(Default)" : ""))) "." t)] = v - } else { - _fatal("regedit: unknown output format(" c "): `" C[c] "'") - } - } - } - } - function _rsqgetptr(g, p, A) - { - if (p in _tLINK) { - _SQSTACK[g][++_SQSTACK[g][0]] = p - _SQSTACK[g][++_SQSTACK[g][0]] = _SQTOPTR[g] - while ((p = _tLINK[p]) in _tLINK) { - _con(".") - } - _SQTOPTR[g] = p - } - if (p in _tFCHLD) { - return _rsqgetptr(g, _tFCHLD[p]) - } - return p - } - function _rsqnext_i0(g, p) - { - if (p == _SQTOPTR[g]) { - if (_SQSTACK[g][0] > 0) { - _SQTOPTR[g] = _SQSTACK[g][_SQSTACK[g][0]--] - return _rsqnext_i0(g, _SQSTACK[g][_SQSTACK[g][0]--]) - } - return - } - if (p in _tNEXT) { - return _rsqgetptr(g, _tNEXT[p]) - } - return _rsqnext_i0(g, _tPARENT[p]) - } - function _rtn(v, A) - { - _conl() - _conline(_val(v) " : " _val(A)) - _conl() - _rtn2(v, A) - _conl() - } - function _rtn2(v, A, r, t) - { - r = (isarray(A) ? _typa(v, A) : _typ(v)) - if ("`" > _t0 && _t0) { - _conl("ggggg") - } - t = ((r ? "TRUE" : "FALSE")) " / " ((r > 0 ? r ">0" : r "!>0")) " / " ((r + 0 > 0 ? r "+0>0" : r "+0!>0")) " / " ((r + 0 != r ? r "+0!=" r : r "+0==" r)) " / " ((r && "`" > r ? "'`'>" r " && " r : "!('`'>" r " && " r ")")) - _conl("`" r "' : " t) - return r - } - function _rxpfn(R, t, p, i, f, A) - { - for (i in R) { - if (match(t, i, A)) { - f = R[i] - if (t != (t = @f(A, substr(t, RLENGTH + 1), p))) { - return t - } - } - } - return _rexpfnend(t) - } - function _sHARE(c, t, P, a, A) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return _ln("_share 1.000") - case "_lib_BEGIN": - return - case "_lib_END": - return - } - } - function _sYS(c, t, P, a, A) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return - case "_lib_BEGIN": - return - case "_lib_END": - return - } - } - function _serv_check(p) - { - _tframe("_serv_check_i0", p, p) - } - function _serv_check_i0(p, p0, p1, p2, p3, i, q, c) - { - if (_[p]["TYPE"] == "defsrv") { - i = IGNORECASE - IGNORECASE = 1 - if (match(_servoutput, roi = "\\012DISPLAY_NAME: " _torexp(_[p]["SERVNAME"]))) { - _creport(p, "OK: SERVICE DETECTED: " substr(_[p]["SERVNAME"], 1, 112)) - } else { - _dllerr(p, "service " _[p]["SERVNAME"] " not detected") - } - } - IGNORECASE = i - } - function _setarrsort(f, a) - { - a = PROCINFO["sorted_in"] - if (! f) { - delete PROCINFO["sorted_in"] - } else { - PROCINFO["sorted_in"] = f - } - return a - } - function _setmpath(p, a) - { - ERRNO = "" - if (p && (a = _filerd(p))) { - if (_FILEIO_TMPRD) { - _FILEIO_TMPATHS[_FILEIO_TMPRD] - } - return (_FILEIO_TMPRD = a) - } else { - return _warning("`" p "': cannot set temporary folder" ((ERRNO ? ": " ERRNO : ""))) - } - } - 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/)) { - gsub(/(^[^-]*\x0D?\x0A-+\x0D?\x0A[ \t]*)|(\x0D?\x0AThe command completed successfully.*$)/, "", c) - l = RLENGTH - 7 - split(c, A, /([ \t]*\x0D?\x0A)+[ \t]*/) - for (c in A) { - if (match(A[c], /((([^ \t:]+[ \t]+)*[^ \t:]+)[ \t]+)([A-Za-z])[ \t]*:/, B) && ++q) { - D[B[2]] = (A[c] ~ /\.\.\.$/ ? _sharepath(h, B[2]) : gensub(/[ \t\\\/]*$/, "\\\\", 1, substr(A[c], 1 + B[1, "length"], l - B[1, "length"]))) - } + + + + + +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/)) { + gsub(/(^[^-]*\x0D?\x0A-+\x0D?\x0A[ \t]*)|(\x0D?\x0AThe command completed successfully.*$)/, "", c) + l = RLENGTH - 7 + split(c, A, /([ \t]*\x0D?\x0A)+[ \t]*/) + for (c in A) { + if (match(A[c], /((([^ \t:]+[ \t]+)*[^ \t:]+)[ \t]+)([A-Za-z])[ \t]*:/, B) && ++q) { + D[B[2]] = (A[c] ~ /\.\.\.$/ ? _sharepath(h, B[2]) : gensub(/[ \t\\\/]*$/, "\\\\", 1, substr(A[c], 1 + B[1, "length"], l - B[1, "length"]))) } - return q } - return _rmtsharerr(h, c) + return q } + return _rmtsharerr(h, c) +} - 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]) - } - return _rmtsharerr(h, s) +#_____________________________________________________________________________ +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]) } + return _rmtsharerr(h, s) +} - function _shortcut(D, S) - { - if (isarray(D)) { - if (isarray(S)) { - _addarrmask(D, S, _SHORTCUTWSTRUC) +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 (S == 0 && S == "") { - _addarrmask(D, _SHORTCUTDEFAULT, _SHORTCUTWSTRUC) + if (_isnotfileptr(S)) { + # array* - define shortcut-specific elements in array by default values + _addarrmask(D, _[S], _SHORTCUTWSTRUC) } else { - if (_isnotfileptr(S)) { - _addarrmask(D, _[S], _SHORTCUTWSTRUC) - } else { - if (_rd_shortcut(D, S)) { - return - } + if (_rd_shortcut(D, S)) { + return } } } + } + # array,ptr* - copy from array _[ptr] to array shorcut-specific elements + } else { + if (D == 0 && D == "") { + return _NOP } else { - if (D == 0 && D == "") { - return _NOP - } else { - if (_isnotfileptr(D)) { - if (isarray(S)) { - _addarrmask(_[D], S, _SHORTCUTWSTRUC) + 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 (S == 0 && S == "") { - _addarrmask(_[D], _SHORTCUTDEFAULT, _SHORTCUTWSTRUC) + if (_isnotfileptr(S)) { + # ptr* - define shortcut-specifc elements in array _[ptr] by default values + _addarrmask(_[D], _[S], _SHORTCUTWSTRUC) } else { - if (_isnotfileptr(S)) { - _addarrmask(_[D], _[S], _SHORTCUTWSTRUC) - } else { - if (_rd_shortcut(_[D], S)) { - return - } + if (_rd_shortcut(_[D], S)) { + return } } } + } + # 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 { - if (isarray(S) && _wr_shortcut(D, S)) { + if (S == 0 && S == "" && _wr_shortcut(D, _SHORTCUTDEFAULT)) { return } else { - if (S == 0 && S == "" && _wr_shortcut(D, _SHORTCUTDEFAULT)) { + if (_isnotfileptr(S) && _wr_shortcut(D, _[S])) { return } else { - if (_isnotfileptr(S) && _wr_shortcut(D, _[S])) { + if (_rd_shortcut(_SHRTCUTA1, S) || _wr_shortcut(D, _SHRTCUTA1)) { return - } else { - if (_rd_shortcut(_SHRTCUTA1, S) || _wr_shortcut(D, _SHRTCUTA1)) { - return - } } } } } - } - } - return 1 - } - - function _shortcut_init(A, B, q) - { - _SHORTCUTERR[2] = "file not found" - _SHORTCUTERR[3] = "no such filepath" - _SHORTCUTERR["The system cannot find the file specified."] = "no such filepath" - _SHORTCUTERR[5] = "file is folder" - _SHORTCUTERR["Access is denied."] = "file is folder" - _SHORTCUTERR[123] = "filepath syntax error" - _SHORTCUTERR["The filename, directory name, or volume label syntax is incorrect."] = "filepath syntax error" - q = "target\t\t\t/T:\t\t\t\tTargetPath=\t\t\t\t\ttarget?\t\t\t;\t\t\t_target\t\t\t\t\t\t\tTargetPathExpanded=\t\t\t\t\t\t\t;\t\t\tparameters\t\t\t/P:\t\t\t\tArguments=\t\t\t\t\tparaneters?\t\t\t;\t\t\t_parameters\t\t\t\t\t\t\tArgumentsExpanded=\t\t\t\t\t\t\t;\t\t\tstartdir\t\t\t/W:\t\t\t\tWorkingDirectory=\t\t\t\tstartdir?\t\t\t;\t\t\t_startdir\t\t\t\t\t\t\tWorkingDirectoryExpanded=\t\t\t\t\t\t;\t\t\trunstyle\t\t\t/R:\t\t\t\tRunStyle=\t\t\t\t\t1\t\t\t\t;\t\t\ticon,index\t\t\t/I:\t\t\t\tIconLocation=\t\t\t\ticon,index?\t\t\t;\t\t\txicon,index\t\t\t\t\t\t\tIconLocationExpanded=\t\t\t\t\t\t\t;\t\t\tshortcut key\t\t/H:\t\t\t\tHotKey=\t\t\t\t\t0\t\t\t\t;\t\t\tdescription\t\t\t/D:\t\t\t\tDescription=\t\t\t\t_env4: default shortcut\t" - split(q, _SHRTCUTA0, /[ \t]*;[ \t]*/) - for (q in _SHRTCUTA0) { - if (match(_SHRTCUTA0[q], /^([^\t]+)\t+([^\t]+)(\t+([^\t]+)(\t+([^\t]+))?)?/, B)) { - if (B[3] == "") { - _SHORTCUTRSTRUC[B[2]] = B[1] + # 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 +} + +#________________________________________________ +function _shortcut_init(A, B, q) +{ + _SHORTCUTERR[2] = "file not found" + _SHORTCUTERR[3] = "no such filepath" + _SHORTCUTERR["The system cannot find the file specified."] = "no such filepath" + _SHORTCUTERR[5] = "file is folder" + _SHORTCUTERR["Access is denied."] = "file is folder" + _SHORTCUTERR[123] = "filepath syntax error" + _SHORTCUTERR["The filename, directory name, or volume label syntax is incorrect."] = "filepath syntax error" + q = "target\t\t\t/T:\t\t\t\tTargetPath=\t\t\t\t\ttarget?\t\t\t;\t\t\t_target\t\t\t\t\t\t\tTargetPathExpanded=\t\t\t\t\t\t\t;\t\t\tparameters\t\t\t/P:\t\t\t\tArguments=\t\t\t\t\tparaneters?\t\t\t;\t\t\t_parameters\t\t\t\t\t\t\tArgumentsExpanded=\t\t\t\t\t\t\t;\t\t\tstartdir\t\t\t/W:\t\t\t\tWorkingDirectory=\t\t\t\tstartdir?\t\t\t;\t\t\t_startdir\t\t\t\t\t\t\tWorkingDirectoryExpanded=\t\t\t\t\t\t;\t\t\trunstyle\t\t\t/R:\t\t\t\tRunStyle=\t\t\t\t\t1\t\t\t\t;\t\t\ticon,index\t\t\t/I:\t\t\t\tIconLocation=\t\t\t\ticon,index?\t\t\t;\t\t\txicon,index\t\t\t\t\t\t\tIconLocationExpanded=\t\t\t\t\t\t\t;\t\t\tshortcut key\t\t/H:\t\t\t\tHotKey=\t\t\t\t\t0\t\t\t\t;\t\t\tdescription\t\t\t/D:\t\t\t\tDescription=\t\t\t\t_env4: default shortcut\t" + split(q, _SHRTCUTA0, /[ \t]*;[ \t]*/) + for (q in _SHRTCUTA0) { + if (match(_SHRTCUTA0[q], /^([^\t]+)\t+([^\t]+)(\t+([^\t]+)(\t+([^\t]+))?)?/, B)) { + if (B[3] == "") { + _SHORTCUTRSTRUC[B[2]] = B[1] + } else { + if (B[5] == "") { + _SHORTCUTWSTRUC[_SHORTCUTRSTRUC[B[4]] = B[1]] = B[2] + delete _SHORTCUTDEFAULT[B[1]] } else { - if (B[5] == "") { - _SHORTCUTWSTRUC[_SHORTCUTRSTRUC[B[4]] = B[1]] = B[2] - delete _SHORTCUTDEFAULT[B[1]] - } else { - _SHORTCUTWSTRUC[_SHORTCUTRSTRUC[B[4]] = B[1]] = B[2] - _SHORTCUTDEFAULT[B[1]] = B[6] - } + _SHORTCUTWSTRUC[_SHORTCUTRSTRUC[B[4]] = B[1]] = B[2] + _SHORTCUTDEFAULT[B[1]] = B[6] } - } else { - _fatal("_shortcut.init: _shortcut_struc: syntax error: `" _SHRTCUTA0[q] "'") } - } - _SHRTCUTA1[""] - delete _SHRTCUTA1[""] - _shortcut_fpath = "\\\\localhost\\eGAWK\\LIB\\_shortcut\\_shortcut.exe" - } - - function _shortcut_nerr(t, s, A) - { - if (match(t, /\x0ASystem error (-?[0-9]+)[^\x0D\x0A]*[\x0D\x0A]+([^\x0D\x0A]+)/, A)) { - ERRNO = ((A[1] in _SHORTCUTERR ? _SHORTCUTERR[A[1]] : (A[2] in _SHORTCUTERR ? _SHORTCUTERR[A[2]] : tolower(gensub(/^(The )?(((.*)\.$)|(.*[^\.]$))/, "\\4\\5", "G", A[2])) "(" A[1] ")"))) ((s ? ": `" s "'" : "")) } else { - return 1 + _fatal("_shortcut.init: _shortcut_struc: syntax error: `" _SHRTCUTA0[q] "'") } } + _SHRTCUTA1[""] + delete _SHRTCUTA1[""] + _shortcut_fpath = "\\\\localhost\\eGAWK\\LIB\\_shortcut\\_shortcut.exe" +} - function _split_regpath() - { - _rpp(" / / / / ") - _rpp(" / / / / huj ") - _rpp(" / / / / huj / ") - _rpp(" / / / / huj / pizda.TSR ") - _rpp(" / / / / hklm ") - _rpp(" / / / / hklm / ") - _rpp(" / / / / hklm / huj ") - _rpp(" / / / / hklm / huj / ") - _rpp(" / / / / hklm / huj / \tpizda.TSR ") - _conl() - _conl("########################################################################################") - _conl() - _rpp(" / / / / hklm / software / altiris / fi le . ex t ") - _rpp(" / / . / / hkcr / software / altiris / fi le . ex t ") - _rpp(" / / ? / / hKcU / software / altiris / fi le . ex t ") - _rpp(" / / lOcAlHoSt / / hKu / software / altiris / fi le . ex t ") - _rpp(" / / ho st / / hKcc / software / altiris / fi le . ex t ") - _rpp(" / / ho st / / hKPd / software / altiris / fi le . ex t ") - _conl() - _conl("########################################################################################") - _conl() - } - - function _splitpath_test() - { - _conl() - _conl("########################################################################################") - _conl() - _fpp(" ") - _fpp(" fi le . ex t ") - _fpp(" di r0 / / ") - _fpp(" di r0 / / fi le . ex t ") - _fpp(" / ") - _fpp(" / fi le . ex t ") - _fpp(" / di r0 / / ") - _fpp(" / di r0 / / fi le . ex t ") - _conl() - _conl("########################################################################################") - _conl() - _fpp(" c : ") - _fpp(" c : fi le . ex t ") - _fpp(" c : di r0 / / ") - _fpp(" c : di r0 / / fi le . ex t ") - _fpp(" c : / / ") - _fpp(" c : / / fi le . ex t ") - _fpp(" c : / / di r0 / / ") - _fpp(" c : / / di r0 / / fi le . ex t ") - _conl() - _conl("########################################################################################") - _conl() - _fpp(" / / ") - _fpp(" / / ho st . hs t ") - _fpp(" / / ho st / / ") - _fpp(" / / ho st / / fi le . ex t ") - _fpp(" / / ho st / / di r0 / / ") - _fpp(" / / ho st / / di r0 / / fi le . ex t ") - _conl() - _conl("########################################################################################") - _conl() - _fpp(" / / ho st / / c : ") - _fpp(" / / ho st / / c : fi le . ex t ") - _fpp(" / / ho st / / c : di r0 / / ") - _fpp(" / / ho st / / c : di r0 / / fi le . ex t ") - _fpp(" / / ho st / / c : / / ") - _fpp(" / / ho st / / c : / / fi le . ex t ") - _fpp(" / / ho st / / c : / / di r0 / / ") - _fpp(" / / ho st / / c : / / di r0 / / fi le . ex t ") - _conl() - _conl("########################################################################################") - _conl() - _fpp(" http : / / / ") - _fpp(" http : / / / si te . ex t ") - _fpp(" http : / / / si te / / ") - _fpp(" http : / / / si te / / fi le . ex t ") - _fpp(" http : / / / si te / / di r0 / / ") - _fpp(" http : / / / si te / / di r0 / / fi le . ex t ") - _conl() - _conl("########################################################################################") - _conl() - _fpp(" ftp : / / / : po rt ") - _fpp(" ftp : / / / si te . ex t : po rt ") - _fpp(" ftp : / / / si te : po rt / / ") - _fpp(" ftp : / / / si te : po rt / / fi le . ex t ") - _fpp(" ftp : / / / si te : po rt / / di r0 / / ") - _fpp(" ftp : / / / si te : po rt / / di r0 / / fi le . ex t ") - _conl() - _conl("## //. ######################################################################################") - _conl() - _fpp(" / / . ") - _fpp(" / / . / / ") - _fpp(" / / . / / com 56 ") - _fpp(" / / . / / com 56 / / ") - _fpp(" / / . / / c : ") - _fpp(" / / . / / c : / / ") - _fpp(" / / . / / c : com 56 ") - _fpp(" / / . / / c : com 56 / / ") - _fpp(" / / . / / c : / / com 56 ") - _fpp(" / / . / / c : / / com 56 / / ") - _conl() - _conl("## //? ######################################################################################") - _conl() - _fpp(" / / ? ") - _fpp(" / / ? / / ") - _fpp(" / / ? / / com 56 ") - _fpp(" / / ? / / com 56 / / ") - _fpp(" / / ? / / c : ") - _fpp(" / / ? / / c : / / ") - _fpp(" / / ? / / c : com 56 ") - _fpp(" / / ? / / c : com 56 / / ") - _fpp(" / / ? / / c : / / com 56 ") - _fpp(" / / ? / / c : / / com 56 / / ") - _conl() - _conl("########################################################################################") - _conl() - _fpp(" / / / ") - _fpp(" / / / . hs t ") - _fpp(" / / / / fi le . ex t ") - _fpp(" / / / / di r0 / / ") - _fpp(" / / / / di r0 / / di r1 / fi le . ex t ") - _fpp(" / / / / c : ") - _fpp(" / / / / c : fi le . ex t ") - _fpp(" / / / / c : di r0 / / ") - _fpp(" / / / / c : di r0 / / fi le . ex t ") - _fpp(" / / / / c : / / ") - _fpp(" / / / / c : / / fi le . ex t ") - _fpp(" / / / / c : / / di r0 / / ") - _fpp(" / / / / c : / / di r0 / / fi le . ex t ") - _conl() - _conl("########################################################################################") - _conl() - return +#_____________________________________________________ +function _shortcut_nerr(t, s, A) +{ + if (match(t, /\x0ASystem error (-?[0-9]+)[^\x0D\x0A]*[\x0D\x0A]+([^\x0D\x0A]+)/, A)) { + ERRNO = ((A[1] in _SHORTCUTERR ? _SHORTCUTERR[A[1]] : (A[2] in _SHORTCUTERR ? _SHORTCUTERR[A[2]] : tolower(gensub(/^(The )?(((.*)\.$)|(.*[^\.]$))/, "\\4\\5", "G", A[2])) "(" A[1] ")"))) ((s ? ": `" s "'" : "")) + } else { + return 1 } - - function _splitstr(A, t, r) - { - if (_istr(t)) { - if (_splitstr_i0(A, t) > 0) { - return _splitstrp0 - } - if (_istr(r)) { - return _splitstr_i0(A, r) - } - } else { - if (it == "A") { - if (length(t) > 0) { - _movarr(A, t) - return (0 - length(A)) - } - } - _istr(r) - } +} + +function _split_regpath() +{ + _rpp(" / / / / ") + _rpp(" / / / / huj ") + _rpp(" / / / / huj / ") + _rpp(" / / / / huj / pizda.TSR ") + _rpp(" / / / / hklm ") + _rpp(" / / / / hklm / ") + _rpp(" / / / / hklm / huj ") + _rpp(" / / / / hklm / huj / ") + _rpp(" / / / / hklm / huj / \tpizda.TSR ") + _conl() + _conl("########################################################################################") + _conl() + _rpp(" / / / / hklm / software / altiris / fi le . ex t ") + _rpp(" / / . / / hkcr / software / altiris / fi le . ex t ") + _rpp(" / / ? / / hKcU / software / altiris / fi le . ex t ") + _rpp(" / / lOcAlHoSt / / hKu / software / altiris / fi le . ex t ") + _rpp(" / / ho st / / hKcc / software / altiris / fi le . ex t ") + _rpp(" / / ho st / / hKPd / software / altiris / fi le . ex t ") + _conl() + _conl("########################################################################################") + _conl() +} + +function _splitpath_test() +{ + _conl() + _conl("########################################################################################") + _conl() + _fpp(" ") + _fpp(" fi le . ex t ") + _fpp(" di r0 / / ") + _fpp(" di r0 / / fi le . ex t ") + _fpp(" / ") + _fpp(" / fi le . ex t ") + _fpp(" / di r0 / / ") + _fpp(" / di r0 / / fi le . ex t ") + _conl() + _conl("########################################################################################") + _conl() + _fpp(" c : ") + _fpp(" c : fi le . ex t ") + _fpp(" c : di r0 / / ") + _fpp(" c : di r0 / / fi le . ex t ") + _fpp(" c : / / ") + _fpp(" c : / / fi le . ex t ") + _fpp(" c : / / di r0 / / ") + _fpp(" c : / / di r0 / / fi le . ex t ") + _conl() + _conl("########################################################################################") + _conl() + _fpp(" / / ") + _fpp(" / / ho st . hs t ") + _fpp(" / / ho st / / ") + _fpp(" / / ho st / / fi le . ex t ") + _fpp(" / / ho st / / di r0 / / ") + _fpp(" / / ho st / / di r0 / / fi le . ex t ") + _conl() + _conl("########################################################################################") + _conl() + _fpp(" / / ho st / / c : ") + _fpp(" / / ho st / / c : fi le . ex t ") + _fpp(" / / ho st / / c : di r0 / / ") + _fpp(" / / ho st / / c : di r0 / / fi le . ex t ") + _fpp(" / / ho st / / c : / / ") + _fpp(" / / ho st / / c : / / fi le . ex t ") + _fpp(" / / ho st / / c : / / di r0 / / ") + _fpp(" / / ho st / / c : / / di r0 / / fi le . ex t ") + _conl() + _conl("########################################################################################") + _conl() + _fpp(" http : / / / ") + _fpp(" http : / / / si te . ex t ") + _fpp(" http : / / / si te / / ") + _fpp(" http : / / / si te / / fi le . ex t ") + _fpp(" http : / / / si te / / di r0 / / ") + _fpp(" http : / / / si te / / di r0 / / fi le . ex t ") + _conl() + _conl("########################################################################################") + _conl() + _fpp(" ftp : / / / : po rt ") + _fpp(" ftp : / / / si te . ex t : po rt ") + _fpp(" ftp : / / / si te : po rt / / ") + _fpp(" ftp : / / / si te : po rt / / fi le . ex t ") + _fpp(" ftp : / / / si te : po rt / / di r0 / / ") + _fpp(" ftp : / / / si te : po rt / / di r0 / / fi le . ex t ") + _conl() + _conl("## //. ######################################################################################") + _conl() + _fpp(" / / . ") + _fpp(" / / . / / ") + _fpp(" / / . / / com 56 ") + _fpp(" / / . / / com 56 / / ") + _fpp(" / / . / / c : ") + _fpp(" / / . / / c : / / ") + _fpp(" / / . / / c : com 56 ") + _fpp(" / / . / / c : com 56 / / ") + _fpp(" / / . / / c : / / com 56 ") + _fpp(" / / . / / c : / / com 56 / / ") + _conl() + _conl("## //? ######################################################################################") + _conl() + _fpp(" / / ? ") + _fpp(" / / ? / / ") + _fpp(" / / ? / / com 56 ") + _fpp(" / / ? / / com 56 / / ") + _fpp(" / / ? / / c : ") + _fpp(" / / ? / / c : / / ") + _fpp(" / / ? / / c : com 56 ") + _fpp(" / / ? / / c : com 56 / / ") + _fpp(" / / ? / / c : / / com 56 ") + _fpp(" / / ? / / c : / / com 56 / / ") + _conl() + _conl("########################################################################################") + _conl() + _fpp(" / / / ") + _fpp(" / / / . hs t ") + _fpp(" / / / / fi le . ex t ") + _fpp(" / / / / di r0 / / ") + _fpp(" / / / / di r0 / / di r1 / fi le . ex t ") + _fpp(" / / / / c : ") + _fpp(" / / / / c : fi le . ex t ") + _fpp(" / / / / c : di r0 / / ") + _fpp(" / / / / c : di r0 / / fi le . ex t ") + _fpp(" / / / / c : / / ") + _fpp(" / / / / c : / / fi le . ex t ") + _fpp(" / / / / c : / / di r0 / / ") + _fpp(" / / / / c : / / di r0 / / fi le . ex t ") + _conl() + _conl("########################################################################################") + _conl() + return +} + +#_______________________________________________________________________ +function _splitstr(A, t, r) +{ + ########################################### 1 # + if (_istr(t)) { + if (_splitstr_i0(A, t) > 0) { + return _splitstrp0 + } + if (_istr(r)) { + return _splitstr_i0(A, r) + } + } else { if (it == "A") { - if (length(r) > 0) { - _movarr(A, r) + if (length(t) > 0) { + _movarr(A, t) return (0 - length(A)) } } + _istr(r) } - - function _splitstr_i0(A, t, C) - { - if (2 > (_splitstrq0 = patsplit(t, _SPLITSTRA0, /([^,\xB4]*\xB4.)*[^,\xB4]*/))) { - _splitstrq0 = split(gensub(/\xB4(.)/, "\\1", "G", t), _SPLITSTRA0, "") + if (it == "A") { + if (length(r) > 0) { + _movarr(A, r) + return (0 - length(A)) } - delete A - _splitstri0 = _splitstrp0 = 0 - while (_splitstri0++ < _splitstrq0) { - if ((t = gensub(/\xB4(.)/, "\\1", "G", _SPLITSTRA0[_splitstri0])) in C || t == "") { - continue - } - C[A[++_splitstrp0] = t] - } - return _splitstrp0 } +} - function _strtorexp(t) - { - gsub(/[\\\.\?\*\+\-\(\)\{\}\[\]\^\$\/\|]/, "\\\\&", t) - t = split(t, _TOREXP_STRA, /[\x00-\x1F]/, _TOREXP_STRB) - _torexp_strt0 = "" - for (_torexp_stri0 = 1; _torexp_stri0 < t; _torexp_stri0++) { - _torexp_strt0 = _torexp_strt0 _TOREXP_STRA[_torexp_stri0] "\\" _QASC[_TOREXP_STRB[_torexp_stri0]] +#_____________________________________________________ +function _splitstr_i0(A, t, C) +{ + if (2 > (_splitstrq0 = patsplit(t, _SPLITSTRA0, /([^,\xB4]*\xB4.)*[^,\xB4]*/))) { + _splitstrq0 = split(gensub(/\xB4(.)/, "\\1", "G", t), _SPLITSTRA0, "") + } + delete A + _splitstri0 = _splitstrp0 = 0 + while (_splitstri0++ < _splitstrq0) { + if ((t = gensub(/\xB4(.)/, "\\1", "G", _SPLITSTRA0[_splitstri0])) in C || t == "") { + continue } - return (_torexp_strt0 _TOREXP_STRA[_torexp_stri0]) + C[A[++_splitstrp0] = t] } + return _splitstrp0 +} - function _subseqoff(r, B) - { - patsplit(r, B, /\x84[^\x94]*\x94/) - return gensub(/\x84[^\x94]*\x94/, "\204", "G", r) +#_______________________________________________ +function _strtorexp(t) +{ + gsub(/[\\\.\?\*\+\-\(\)\{\}\[\]\^\$\/\|]/, "\\\\&", t) + t = split(t, _TOREXP_STRA, /[\x00-\x1F]/, _TOREXP_STRB) + _torexp_strt0 = "" + for (_torexp_stri0 = 1; _torexp_stri0 < t; _torexp_stri0++) { + _torexp_strt0 = _torexp_strt0 _TOREXP_STRA[_torexp_stri0] "\\" _QASC[_TOREXP_STRB[_torexp_stri0]] } + return (_torexp_strt0 _TOREXP_STRA[_torexp_stri0]) +} - function _subseqon(B, r, F, f, s, e, q, i, A) - { - q = split(r, A, /\x84/) - r = "" - f = F[""] - for (i = 1; i < q; i++) { - s = substr(e = B[i], 2, 1) - s = (s in F ? F[s] : F[""]) - r = r (@f(A[i])) (@s(substr(e, 3, length(e) - 3))) - } - return (r (@f(A[i]))) - } +function _subseqoff(r, B) +{ + patsplit(r, B, /\x84[^\x94]*\x94/) + return gensub(/\x84[^\x94]*\x94/, "\204", "G", r) +} - 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 - _sysinfoq0 = _sysinfoq1 = split(_SYSINFOA0[1], _SYSINFOA0, / +/, _SYSINFOB0) - while (--_sysinfoq0 > 0) { - D[_sysinfof0] = gensub(/^ +| +$/, "", "G", substr(h, _sysinfol0 = _sysinfol0 - (_sysinfol1 = length(_sysinfof0 = _SYSINFOA0[_sysinfoq0]) + length(_SYSINFOB0[_sysinfoq0])), _sysinfol1)) - } - return (_sysinfoq1 - 1) - } +function _subseqon(B, r, F, f, s, e, q, i, A) +{ + q = split(r, A, /\x84/) + r = "" + f = F[""] + for (i = 1; i < q; i++) { + s = substr(e = B[i], 2, 1) + #_conl("curr r==`" r "': A[" i "]=`" A[i] "'") + #s=s in F ? _th0(F[s],_conl("handler `" F[s] "' for `" s "' ost=`" substr(e,3,length(e)-3) "'")) : _th0(F[""],_conl("default handler for `" s "'")) + s = (s in F ? F[s] : F[""]) + #_conl("`" f "'") + r = r (@f(A[i])) (@s(substr(e, 3, length(e) - 3))) } + return (r (@f(A[i]))) +} - function _tOBJ(c, t, P) - { - switch (c) { - case "_lib_CMDLN": - return t - case "_lib_APPLY": - return - case "_lib_HELP": - return - case "_lib_NAMEVER": - return _ln("_tOBJ 3.0") - case "_lib_BEGIN": - return - case "_lib_END": - return - case "_lib_CLEANUP": - return _tOBJ_CLEANUP() - } - } +#_____________________________________________________________________________ +# _rdreg(ARRAY,reg_path) +# Import into ARRAY the content of the whole registree tree with the higher point specified by reg_path. +# ARRAY will be filled by the strings with following format: +# +# HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\GnuWin32\CoreUtils\5.3.0\pck\InstallPath.STR=C:\Program Files (x86)\GnuWin32 +# where: +# HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\GnuWin32\CoreUtils\5.3.0\pck <- REG KEY PATH +# InstallPath <- DATA FIELD +# STR <- TYPE +# C:\Program Files (x86)\GnuWin32 <- VALUE +# TYPE: +# STR - REG_SZ (String Value) +# W32 - REG_DWORD (DWORD (32-bit) Value) +# W64 - REG_QWORD (QWORD (64-bit) Value) +# BIN - REG_BINARY (Binary Value) +# XSZ - REG_EXPAND_SZ (Expandable String Value) +# MSZ - REG_MULTI_SZ (Multi-String Value) +#_________________________________________________________________________________________ - function _tOBJ_CLEANUP(p) - { - for (p in UIDSDEL) { - delete _ptr[p] - delete _tPREV[p] - delete _tPARENT[p] - delete _tNEXT[p] - delete _tFCHLD[p] - delete _tQCHLD[p] - delete _tLCHLD[p] - delete _TMP0[p] - delete _TMP1[p] - delete _tLINK[p] - delete _tCLASS[p] - } - } - function _tabtospc(t, ts, xc, a, c, n, A, B) - { - if (! ts) { - ts = _TAB_STEP_DEFAULT - } - c = split("." t, A, /\t+/, B) - A[1] = substr(A[1], 2) - t = "" - for (n = 1; n <= c; n++) { - t = t A[n] _getchrln(" ", (xc = length(B[n]) * ts + int((a = xc + length(A[n])) / ts) * ts) - a) - } - return t - } - function _tapi(p, f, p0, p1, p2, p3, c) - { - c = p - do { - if (f in _[c]["API"]) { - f = _[c]["API"][f] - return @f(p, p0, p1, p2, p3) - } - c = _[c]["CLASS"] - } while ("CLASS" in _[c]) - } - function _tbframe(f, p, p0, p1) - { - delete _t_ENDF[++_t_ENDF[0]] - f = (p ? _tbframe_i0(f, p, p0, p1) : "") - --_t_ENDF[0] - return f - } +# HKCR HKEY_CLASSES_ROOT +# HKCU HKEY_CURRENT_USER +# HKLM HKEY_LOCAL_MACHINE +# HKU HKEY_USERS +# HKCC HKEY_CURRENT_CONFIG +# HKPD HKEY_PERFORMANCE_DATA - function _tbframe_i0(f, p, p0, p1, a) - { - while (p in _tLINK) { - p = _tLINK[p] - } - return ((p in _tLCHLD ? _tmbframe(f, _tLCHLD[p], p0, p1) : @f(p, p0, p1))) - } - function _tbframex(f, p, p0, p1) - { - delete _t_ENDF[++_t_ENDF[0]] - f = (p ? _tbframex_i0(f, p, p0, p1) : "") - --_t_ENDF[0] - return f - } - function _tbframex_i0(f, p, p0, p1) - { - while (p in _tLINK) { - p = _tLINK[p] - } - return ((p in _tLCHLD ? _tmbframex(f, _tLCHLD[p], p0, p1) : @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] - return f - } - function _tbpass_i0(f, p, p0, p1, a) - { - while (p in _tLINK) { - p = _tLINK[p] - } - return ((p in _tLCHLD ? _tmbpass(f, _tLCHLD[p], p0, p1) : @f(p, p0, p1))) - } - function _tbpassx(f, p, p0, p1) - { - delete _t_ENDF[++_t_ENDF[0]] - f = (p ? _tbpassx_i0(f, p, p0, p1) : "") - --_t_ENDF[0] - return f - } - function _tbpassx_i0(f, p, p0, p1) - { - while (p in _tLINK) { - p = _tLINK[p] - } - return ((p in _tLCHLD ? _tmbpassx(f, _tLCHLD[p], p0, p1) : @f(p, p0, p1))) - } - function _tbrochld(p, f, pp) - { - if (p) { - if (p in _tFCHLD) { - f = _tFCHLD[p] - delete _tFCHLD[p] - delete _tLCHLD[p] - if (p in _tPARENT) { - pp = _tPARENT[p] - delete _tPARENT[p] - if (p in _tPREV) { - _tNEXT[_tPREV[f] = _tPREV[p]] = f - delete _tPREV[p] - } else { - _tFCHLD[pp] = f - } - for (; f in _tNEXT; f = _tNEXT[f]) { - _tPARENT[f] = pp - } - _tPARENT[f] = pp - if (p in _tNEXT) { - _tPREV[_tNEXT[f] = _tNEXT[p]] = f - delete _tNEXT[p] - } else { - _tLCHLD[pp] = f - } - _tQCHLD[pp] = _tQCHLD[pp] + _tQCHLD[p] - 1 - delete _tQCHLD[p] - return f - } else { - delete _tQCHLD[p] - if (p in _tPREV) { - _tNEXT[_tPREV[f] = _tPREV[p]] = f - delete _tPREV[p] - } - for (; f in _tNEXT; f = _tNEXT[f]) { - delete _tPARENT[f] - } - delete _tPARENT[f] - if (p in _tNEXT) { - _tPREV[_tNEXT[f] = _tNEXT[p]] = f - delete _tNEXT[p] - } - return f - } - } else { - if (p in _tPARENT) { - pp = _tPARENT[p] - delete _tPARENT[p] - if (p in _tPREV) { - if (p in _tNEXT) { - _tNEXT[_tPREV[f] = _tPREV[p]] = f = _tNEXT[p] - delete _tNEXT[p] - } else { - delete _tNEXT[_tLCHLD[pp] = _tPREV[p]] - } - delete _tPREV[p] - _tQCHLD[pp]-- - } else { - if (p in _tNEXT) { - delete _tPREV[_tFCHLD[pp] = _tNEXT[p]] - delete _tNEXT[p] - _tQCHLD[pp]-- - } else { - delete _tFCHLD[pp] - delete _tLCHLD[pp] - delete _tQCHLD[pp] - } - } - } else { - if (p in _tPREV) { - if (p in _tNEXT) { - _tNEXT[_tPREV[f] = _tPREV[p]] = f = _tNEXT[p] - delete _tNEXT[p] - } else { - delete _tNEXT[_tPREV[p]] - } - delete _tPREV[p] - } else { - if (p in _tNEXT) { - delete _tPREV[_tNEXT[p]] - delete _tNEXT[p] - } - } - } - } - } - return p - } - 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]) { - if (isarray(_ptr[p][i])) { - _tdel_i1(_ptr[p][i]) - } else { - if (i = _ptr[p][i]) { - _tdel(i) - } - } - } - if (p in _tFCHLD) { - i = _tFCHLD[p] - do { - i = ((i in _tNEXT ? _tNEXT[i] : "")) _tdel_i0(i) - } while (i) - } - delete _[p] - _UIDSDEL[p] - } - } - function _tdel_i0(p, i) - { - for (i in _ptr[p]) { - if (isarray(_ptr[p][i])) { - _tdel_i1(_ptr[p][i]) - } else { - if (i = _ptr[p][i]) { - _tdel(i) - } - } - } - if (p in _tFCHLD) { - i = _tFCHLD[p] - do { - i = ((i in _tNEXT ? _tNEXT[i] : "")) _tdel_i0(i) - } while (i) - } - delete _[p] - _UIDSDEL[p] - } - function _tdel_i1(A, i) - { - for (i in A) { - if (isarray(A[i])) { - _tdel_i1(A[i]) - } else { - if (i = A[i]) { - _tdel(i) - } - } - } - } - function _tdelete(p, v) - { - if (p) { - _wLCHLD(_tDELPTR, p) - } - return v - } - function _tdelitem(p) - { - if (p) { - if ("HOST" in _PTR[p] && "ITEMNAME" in _[p]) { - return _wLCHLD(_PTR[_PTR[p]["HOST"]]["ITEM"][_[p]["ITEMNAME"]], p) - } - _tdelete(p) - return p - } - } - function _tend(a, b) - { - if (b == "") { - return (_t_ENDF[_t_ENDF[0]] = a) - } else { - return (_t_ENDF[_t_ENDF[0] + a] = b) + + + + + + + + + + + + + + + + + + + + + + + + + + +#___________________________________________________________________________________ +#################################################################################### + + + + + + + + + + + + + + + + + + + + + + + +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 + _sysinfoq0 = _sysinfoq1 = split(_SYSINFOA0[1], _SYSINFOA0, / +/, _SYSINFOB0) + while (--_sysinfoq0 > 0) { + D[_sysinfof0] = gensub(/^ +| +$/, "", "G", substr(h, _sysinfol0 = _sysinfol0 - (_sysinfol1 = length(_sysinfof0 = _SYSINFOA0[_sysinfoq0]) + length(_SYSINFOB0[_sysinfoq0])), _sysinfol1)) } + return (_sysinfoq1 - 1) } +} - function _texclude(p, v, pp) - { - if (p in _) { +######################################################### + +function _tOBJ(c, t, P) +{ + switch (c) { + case "_lib_CMDLN": + #___________________________________________________________ + return t + #___________________________________________________________ + case "_lib_APPLY": + return + #___________________________________________________________ + case "_lib_HELP": + return + #___________________________________________________________ + case "_lib_NAMEVER": + return _ln("_tOBJ 3.0") + #___________________________________________________________ + case "_lib_BEGIN": + return + #___________________________________________________________ + case "_lib_END": + return + #___________________________________________________________ + case "_lib_CLEANUP": + return _tOBJ_CLEANUP() + } +} + +#_______________________________________________________________________ +function _tOBJ_CLEANUP(p) +{ + ############################################## + for (p in UIDSDEL) { + delete _ptr[p] + delete _tPREV[p] + delete _tPARENT[p] + delete _tNEXT[p] + delete _tFCHLD[p] + delete _tQCHLD[p] + delete _tLCHLD[p] + delete _TMP0[p] + delete _TMP1[p] + delete _tLINK[p] + delete _tCLASS[p] + } +} + +#_______________________________________________________________________ +function _tabtospc(t, ts, xc, a, c, n, A, B) +{ + ################################## + if (! ts) { + ts = _TAB_STEP_DEFAULT + } + c = split("." t, A, /\t+/, B) + A[1] = substr(A[1], 2) + t = "" + for (n = 1; n <= c; n++) { + t = t A[n] _getchrln(" ", (xc = length(B[n]) * ts + int((a = xc + length(A[n])) / ts) * ts) - a) + } + return t +} + +#___________________________________________________________________________________ +#################################################################################### + + + + + + + +function _tapi(p, f, p0, p1, p2, p3, c) +{ + c = p + do { + if (f in _[c]["API"]) { + f = _[c]["API"][f] + return @f(p, p0, p1, p2, p3) + } + c = _[c]["CLASS"] + } while ("CLASS" in _[c]) +} + +#_____________________________________________________________________________ +function _tbframe(f, p, p0, p1) +{ + ################################################## + delete _t_ENDF[++_t_ENDF[0]] + f = (p ? _tbframe_i0(f, p, p0, p1) : "") + --_t_ENDF[0] + return f +} + +#___________________________________________________________ +function _tbframe_i0(f, p, p0, p1, a) +{ + while (p in _tLINK) { + p = _tLINK[p] + } + return ((p in _tLCHLD ? _tmbframe(f, _tLCHLD[p], p0, p1) : @f(p, p0, p1))) +} + +#_______________________________________________________________________ +function _tbframex(f, p, p0, p1) +{ + ########################################### + delete _t_ENDF[++_t_ENDF[0]] + f = (p ? _tbframex_i0(f, p, p0, p1) : "") + --_t_ENDF[0] + return f +} + +#___________________________________________________________ +function _tbframex_i0(f, p, p0, p1) +{ + while (p in _tLINK) { + p = _tLINK[p] + } + return ((p in _tLCHLD ? _tmbframex(f, _tLCHLD[p], p0, p1) : @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] + return f +} + +#___________________________________________________________ +function _tbpass_i0(f, p, p0, p1, a) +{ + while (p in _tLINK) { + p = _tLINK[p] + } + return ((p in _tLCHLD ? _tmbpass(f, _tLCHLD[p], p0, p1) : @f(p, p0, p1))) +} + +#_____________________________________________________________________________ +function _tbpassx(f, p, p0, p1) +{ + ################################################## + delete _t_ENDF[++_t_ENDF[0]] + f = (p ? _tbpassx_i0(f, p, p0, p1) : "") + --_t_ENDF[0] + return f +} + +#___________________________________________________________ +function _tbpassx_i0(f, p, p0, p1) +{ + while (p in _tLINK) { + p = _tLINK[p] + } + return ((p in _tLCHLD ? _tmbpassx(f, _tLCHLD[p], p0, p1) : @f(p, p0, p1))) +} + +#_____________________________________________________________________________ +function _tbrochld(p, f, pp) +{ + ################################################### # TEST!!! + if (p) { + if (p in _tFCHLD) { + f = _tFCHLD[p] + delete _tFCHLD[p] + delete _tLCHLD[p] + if (p in _tPARENT) { + pp = _tPARENT[p] + delete _tPARENT[p] + if (p in _tPREV) { + _tNEXT[_tPREV[f] = _tPREV[p]] = f + delete _tPREV[p] + } else { + _tFCHLD[pp] = f + } + for (; f in _tNEXT; f = _tNEXT[f]) { + _tPARENT[f] = pp + } + _tPARENT[f] = pp + if (p in _tNEXT) { + _tPREV[_tNEXT[f] = _tNEXT[p]] = f + delete _tNEXT[p] + } else { + _tLCHLD[pp] = f + } + _tQCHLD[pp] = _tQCHLD[pp] + _tQCHLD[p] - 1 + delete _tQCHLD[p] + return f + } else { + delete _tQCHLD[p] + if (p in _tPREV) { + _tNEXT[_tPREV[f] = _tPREV[p]] = f + delete _tPREV[p] + } + for (; f in _tNEXT; f = _tNEXT[f]) { + delete _tPARENT[f] + } + delete _tPARENT[f] + if (p in _tNEXT) { + _tPREV[_tNEXT[f] = _tNEXT[p]] = f + delete _tNEXT[p] + } + return f + } + } else { if (p in _tPARENT) { pp = _tPARENT[p] delete _tPARENT[p] if (p in _tPREV) { if (p in _tNEXT) { - _tPREV[_tNEXT[v] = _tNEXT[p]] = v = _tPREV[p] + _tNEXT[_tPREV[f] = _tPREV[p]] = f = _tNEXT[p] delete _tNEXT[p] } else { delete _tNEXT[_tLCHLD[pp] = _tPREV[p]] } delete _tPREV[p] + _tQCHLD[pp]-- } else { if (p in _tNEXT) { delete _tPREV[_tFCHLD[pp] = _tNEXT[p]] delete _tNEXT[p] + _tQCHLD[pp]-- } else { delete _tFCHLD[pp] delete _tLCHLD[pp] delete _tQCHLD[pp] - return p } } - --_tQCHLD[pp] } else { if (p in _tPREV) { if (p in _tNEXT) { - _tPREV[_tNEXT[v] = _tNEXT[p]] = v = _tPREV[p] + _tNEXT[_tPREV[f] = _tPREV[p]] = f = _tNEXT[p] delete _tNEXT[p] } else { delete _tNEXT[_tPREV[p]] @@ -4777,1133 +5735,1521 @@ } } } - return p - } - } - - 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] - return p - } - - function _tframe0(f, p, p0, p1, p2, p3, A) - { - if (_isptr(p)) { - if (isarray(f)) { - return _tframe0_i0(f, p) - } - _tframex_p0(A, f, 0) - return _th0(_tframe0_i0(A, p), --_TEND[_ARRLEN]) } } - - function _tframe0_i0(A, p, f) - { - if (p in _tLINK) { - _tframe_link = p - if ("`" in A) { - f = A["`"] - while (p in _tLINK) { - @f(p = _tLINK[p]) - } + return p +} + +#_________________________________________________________________ +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]) { + if (isarray(_ptr[p][i])) { + _tdel_i1(_ptr[p][i]) } else { - while (p in _tLINK) { - p = _tLINK[p] + if (i = _ptr[p][i]) { + _tdel(i) } } - } else { - _tframe_link = "" } if (p in _tFCHLD) { - return (_tframe0_i2(A, "^", p) _tframe0_i1(A, _tFCHLD[p])) + i = _tFCHLD[p] + do { + i = ((i in _tNEXT ? _tNEXT[i] : "")) _tdel_i0(i) + } while (i) } - return _tframe0_i2(A, ".", p) + delete _[p] + _UIDSDEL[p] } +} - function _tframe0_i1(A, p) - { - if (_TEND[_ARRLEN] in _TEND) { - return - } - if (p in _tNEXT) { - return (_tframe0_i0(A, p) _tframe0_i1(A, _tNEXT[p])) +#_____________________________________________________ +function _tdel_i0(p, i) +{ + for (i in _ptr[p]) { + if (isarray(_ptr[p][i])) { + _tdel_i1(_ptr[p][i]) + } else { + if (i = _ptr[p][i]) { + _tdel(i) + } } - return _tframe0_i0(A, p) } - - function _tframe0_i2(A, m, p) - { - _tframe_dlink = p - while (p in _tDLINK) { - p = _tDLINK[p] - } - if (m in A) { - if (m "~" in A) { - if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { - return - } + if (p in _tFCHLD) { + i = _tFCHLD[p] + do { + i = ((i in _tNEXT ? _tNEXT[i] : "")) _tdel_i0(i) + } while (i) + } + delete _[p] + _UIDSDEL[p] +} + +#_____________________________________________________ +function _tdel_i1(A, i) +{ + for (i in A) { + if (isarray(A[i])) { + _tdel_i1(A[i]) + } else { + if (i = A[i]) { + _tdel(i) } - m = A[m] - return @m(p) } } +} - function _tframe1(f, p, p0, p1, p2, p3, A) - { - if (_isptr(p)) { - if (isarray(f)) { - return _tframe1_i0(f, p, p0) - } - _tframex_p0(A, f, 1) - return _th0(_tframe1_i0(A, p, p0), --_TEND[_ARRLEN]) - } +#_____________________________________________________________________________ +function _tdelete(p, v) +{ + ####################################################### # REMAKE EXCLUDE + if (p) { + _wLCHLD(_tDELPTR, p) } + return v +} - function _tframe1_i0(A, p, p0) - { - _tframe_link = p - while (p in _tLINK) { - p = _tLINK[p] +#_________________________________________________________________ +function _tdelitem(p) +{ + ############################################# + if (p) { + if ("HOST" in _PTR[p] && "ITEMNAME" in _[p]) { + return _wLCHLD(_PTR[_PTR[p]["HOST"]]["ITEM"][_[p]["ITEMNAME"]], p) } - if (p in _tFCHLD) { - return (_tframe1_i2(A, "^", p, p0) _tframe1_i1(A, _tFCHLD[p], p0)) - } - return _tframe1_i2(A, ".", p, p0) + _tdelete(p) + return p } +} - function _tframe1_i1(A, p, p0) - { - if (_TEND[_ARRLEN] in _TEND) { - return - } - if (p in _tNEXT) { - return (_tframe1_i0(A, p, p0) _tframe1_i1(A, _tNEXT[p], p0)) - } - return _tframe1_i0(A, p, p0) +#_______________________________________________________________________ +function _tend(a, b) +{ + ##################################################### + if (b == "") { + return (_t_ENDF[_t_ENDF[0]] = a) + } else { + return (_t_ENDF[_t_ENDF[0] + a] = b) } +} - function _tframe1_i2(A, m, p, p0) - { - _tframe_dlink = p - while (p in _tDLINK) { - p = _tDLINK[p] - } - if (m in A) { - if (m "~" in A) { - if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { - return +#_____________________________________________________________________________ +function _texclude(p, v, pp) +{ + ################################################### # TEST!!! + if (p in _) { + if (p in _tPARENT) { + pp = _tPARENT[p] + delete _tPARENT[p] + if (p in _tPREV) { + if (p in _tNEXT) { + _tPREV[_tNEXT[v] = _tNEXT[p]] = v = _tPREV[p] + delete _tNEXT[p] + } else { + delete _tNEXT[_tLCHLD[pp] = _tPREV[p]] + } + delete _tPREV[p] + } else { + if (p in _tNEXT) { + delete _tPREV[_tFCHLD[pp] = _tNEXT[p]] + delete _tNEXT[p] + } else { + delete _tFCHLD[pp] + delete _tLCHLD[pp] + delete _tQCHLD[pp] + return p } } - m = A[m] - return @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) + --_tQCHLD[pp] + } else { + if (p in _tPREV) { + if (p in _tNEXT) { + _tPREV[_tNEXT[v] = _tNEXT[p]] = v = _tPREV[p] + delete _tNEXT[p] + } else { + delete _tNEXT[_tPREV[p]] + } + delete _tPREV[p] + } else { + if (p in _tNEXT) { + delete _tPREV[_tNEXT[p]] + delete _tNEXT[p] + } } - _tframex_p0(A, f, 2) - return _th0(_tframe2_i0(A, p, p0, p1), --_TEND[_ARRLEN]) } + return p } - - function _tframe2_i0(A, p, p0, p1) - { +} + +# _tDLINK progressive development: concrete _tDLINK function\processing algo; all frame's families support +#_____________________________________________________________________________ +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] + return p +} + +#_____________________________________________________________________________ +function _tframe0(f, p, p0, p1, p2, p3, A) +{ + ######################################### + if (_isptr(p)) { + if (isarray(f)) { + return _tframe0_i0(f, p) + } + _tframex_p0(A, f, 0) + return _th0(_tframe0_i0(A, p), --_TEND[_ARRLEN]) + } +} + +#_______________________________________________ +function _tframe0_i0(A, p, f) +{ + if (p in _tLINK) { _tframe_link = p - while (p in _tLINK) { - p = _tLINK[p] - } - if (p in _tFCHLD) { - return (_tframe2_i2(A, "^", p, p0, p1) _tframe2_i1(A, _tFCHLD[p], p0, p1)) + if ("`" in A) { + f = A["`"] + while (p in _tLINK) { + @f(p = _tLINK[p]) + } + } else { + while (p in _tLINK) { + p = _tLINK[p] + } } - return _tframe2_i2(A, ".", p, p0, p1) + } else { + _tframe_link = "" } - - function _tframe2_i1(A, p, p0, p1) - { - if (_TEND[_ARRLEN] in _TEND) { - return - } - if (p in _tNEXT) { - return (_tframe2_i0(A, p, p0, p1) _tframe2_i1(A, _tNEXT[p], p0, p1)) - } - return _tframe2_i0(A, p, p0, p1) + if (p in _tFCHLD) { + return (_tframe0_i2(A, "^", p) _tframe0_i1(A, _tFCHLD[p])) } + return _tframe0_i2(A, ".", p) +} - function _tframe2_i2(A, m, p, p0, p1) - { - _tframe_dlink = p - while (p in _tDLINK) { - p = _tDLINK[p] - } - if (m in A) { - if (m "~" in A) { - if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { - return - } - } - m = A[m] - return @m(p, p0, p1) - } +#_______________________________________________ +function _tframe0_i1(A, p) +{ + if (_TEND[_ARRLEN] in _TEND) { + return } + if (p in _tNEXT) { + return (_tframe0_i0(A, p) _tframe0_i1(A, _tNEXT[p])) + } + return _tframe0_i0(A, p) +} - function _tframe3(f, p, p0, p1, p2, p3, A) - { - if (_isptr(p)) { - if (isarray(f)) { - return _tframe3_i0(f, p, p0, p1, p2) +#_______________________________________________ +function _tframe0_i2(A, m, p) +{ + _tframe_dlink = p + while (p in _tDLINK) { + p = _tDLINK[p] + } + if (m in A) { + if (m "~" in A) { + if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { + return } - _tframex_p0(A, f, 3) - return _th0(_tframe3_i0(A, p, p0, p1, p2), --_TEND[_ARRLEN]) } + m = A[m] + return @m(p) } +} - function _tframe3_i0(A, p, p0, p1, p2) - { - _tframe_link = p - while (p in _tLINK) { - p = _tLINK[p] - } - if (p in _tFCHLD) { - return (_tframe3_i2(A, "^", p, p0, p1, p2) _tframe3_i1(A, _tFCHLD[p], p0, p1, p2)) +#_________________________________________________________________ +function _tframe1(f, p, p0, p1, p2, p3, A) +{ + ############################# + if (_isptr(p)) { + if (isarray(f)) { + return _tframe1_i0(f, p, p0) } - return _tframe3_i2(A, ".", p, p0, p1, p2) + _tframex_p0(A, f, 1) + return _th0(_tframe1_i0(A, p, p0), --_TEND[_ARRLEN]) } +} - function _tframe3_i1(A, p, p0, p1, p2) - { - if (_TEND[_ARRLEN] in _TEND) { - return - } - if (p in _tNEXT) { - return (_tframe3_i0(A, p, p0, p1, p2) _tframe3_i1(A, _tNEXT[p], p0, p1, p2)) - } - return _tframe3_i0(A, p, p0, p1, p2) +#_______________________________________________ +function _tframe1_i0(A, p, p0) +{ + _tframe_link = p + while (p in _tLINK) { + p = _tLINK[p] } - - function _tframe3_i2(A, m, p, p0, p1, p2) - { - _tframe_dlink = p - while (p in _tDLINK) { - p = _tDLINK[p] - } - if (m in A) { - if (m "~" in A) { - if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { - return - } - } - m = A[m] - return @m(p, p0, p1, p2) - } + if (p in _tFCHLD) { + return (_tframe1_i2(A, "^", p, p0) _tframe1_i1(A, _tFCHLD[p], p0)) } + return _tframe1_i2(A, ".", p, p0) +} - function _tframe4(f, p, p0, p1, p2, p3, A) - { - if (_isptr(p)) { - if (isarray(f)) { - return _tframe4_i0(f, p, p0, p1, p2, p3) - } - _tframex_p0(A, f, 4) - return _th0(_tframe4_i0(A, p, p0, p1, p2, p3), --_TEND[_ARRLEN]) - } +#_______________________________________________ +function _tframe1_i1(A, p, p0) +{ + if (_TEND[_ARRLEN] in _TEND) { + return } - - function _tframe4_i0(A, p, p0, p1, p2, p3) - { - _tframe_link = p - while (p in _tLINK) { - p = _tLINK[p] - } - if (p in _tFCHLD) { - return (_tframe4_i2(A, "^", p, p0, p1, p2, p3) _tframe4_i1(A, _tFCHLD[p], p0, p1, p2, p3)) - } - return _tframe4_i2(A, ".", p, p0, p1, p2, p3) + if (p in _tNEXT) { + return (_tframe1_i0(A, p, p0) _tframe1_i1(A, _tNEXT[p], p0)) } + return _tframe1_i0(A, p, p0) +} - function _tframe4_i1(A, p, p0, p1, p2, p3) - { - if (_TEND[_ARRLEN] in _TEND) { - return - } - if (p in _tNEXT) { - return (_tframe4_i0(A, p, p0, p1, p2, p3) _tframe4_i1(A, _tNEXT[p], p0, p1, p2, p3)) - } - return _tframe4_i0(A, p, p0, p1, p2, p3) +#_______________________________________________ +function _tframe1_i2(A, m, p, p0) +{ + _tframe_dlink = p + while (p in _tDLINK) { + p = _tDLINK[p] } - - function _tframe4_i2(A, m, p, p0, p1, p2, p3) - { - _tframe_dlink = p - while (p in _tDLINK) { - p = _tDLINK[p] - } - if (m in A) { - if (m "~" in A) { - if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { - return - } + if (m in A) { + if (m "~" in A) { + if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { + return } - m = A[m] - return @m(p, p0, p1, p2, p3) - } - } - - function _tframe_i0(f, p, p0, p1, p2, a) - { - while (p in _tLINK) { - p = _tLINK[p] } - return ((p in _tFCHLD ? _tmframe_i0(f, _tFCHLD[p], p0, p1, p2) : (p in _tDLINK ? @f(_tDLINK[p], p0, p1, p2) : @f(p, p0, p1, p2)))) + m = A[m] + return @m(p, p0) } +} - function _tframe_i1(F, p, p0, p1, p2, a) - { - while (p in _tLINK) { - p = _tLINK[p] +#_________________________________________________________________ +function _tframe2(f, p, p0, p1, p2, p3, A) +{ + ############################# + if (_isptr(p)) { + if (isarray(f)) { + return _tframe2_i0(f, p, p0, p1) } - return ((p in _tFCHLD ? (("." in F ? _th1(a = F["."], @a(p, p0, p1, p2)) : "")) _tmframe_i1(F, _tFCHLD[p], p0, p1, p2) : (">" in F ? _th1(a = F[">"], (p in _tDLINK ? @a(_tDLINK[p], p0, p1, p2) : @a(p, p0, p1, p2))) : ""))) + _tframex_p0(A, f, 2) + return _th0(_tframe2_i0(A, p, p0, p1), --_TEND[_ARRLEN]) } +} - function _tframex(f, p, p0, p1) - { - delete _t_ENDF[++_t_ENDF[0]] - f = (p ? _tframex_i0(f, p, p0, p1) : "") - --_t_ENDF[0] - return f +#_______________________________________________ +function _tframe2_i0(A, p, p0, p1) +{ + _tframe_link = p + while (p in _tLINK) { + p = _tLINK[p] } - - function _tframex_i0(f, p, p0, p1) - { - while (p in _tLINK) { - p = _tLINK[p] - } - return ((p in _tFCHLD ? _tmframex(f, _tFCHLD[p], p0, p1) : @f(p, p0, p1))) + if (p in _tFCHLD) { + return (_tframe2_i2(A, "^", p, p0, p1) _tframe2_i1(A, _tFCHLD[p], p0, p1)) } + return _tframe2_i2(A, ".", p, p0, p1) +} - function _tframex_p0(A, f, q, i, B, C) - { - _tframe_qparam = q - delete _TEND[++_TEND[_ARRLEN]] - if (match(f, /\~(.*)$/, B)) { - A["^~"] = A[".~"] = B[1] - f = substr(f, 1, RSTART - 1) - } - A["."] = A["^"] = f +#_______________________________________________ +function _tframe2_i1(A, p, p0, p1) +{ + if (_TEND[_ARRLEN] in _TEND) { return - q = split(f, B, /;/) - i = 0 - while (i < q) { - _tframex_p1(A, C[i]) - while (++i <= q) { - _tframex_p1(A, C[i], B[i]) - } - } } - - function _tframex_p1(A, v, i, r, B) - { - gsub(/[ \t]+/, "", v) - while (match(v, /^([^~]*)~\/(([^\/\\]*\\.)*[^\/\\]*)\//, B)) { - v = B[1] substr(v, RSTART + RLENGTH) - r = B[2] - } - if (i == "") { - if (v != "") { - A["."] = v - delete A["`"] - delete A["^"] - } - if (r != "") { - A[".~"] = A["`~"] = A["^~"] = r - } - } else { - if (match(v, /!/)) { - delete A[i] - } else { - A[i] = v - if (r != "") { - A[i "~"] = r - } - } - } + if (p in _tNEXT) { + return (_tframe2_i0(A, p, p0, p1) _tframe2_i1(A, _tNEXT[p], p0, p1)) } + return _tframe2_i0(A, p, p0, p1) +} - function _tgenuid(c) - { - for (_uidcntr in _UIDARR1) { - delete _UIDARR1[_uidcntr] - for (c in _UIDARR0) { - _UIDS[_uidcntr c] - } - delete _UIDS[_uidcntr c] - return (_uidcntr c) - } - return _fatal("_tUID: Out of UID range") +#_______________________________________________ +function _tframe2_i2(A, m, p, p0, p1) +{ + _tframe_dlink = p + while (p in _tDLINK) { + p = _tDLINK[p] } - - function _tgenuid_init(a, b, A) - { - _ptrlength = 4 - a = "\222\223\224\225\226\227\230\231\232" "\240\241\242\243\244\245\246\247" "\260\261\262\263\264\265\266\267\270\271\272\273\274\275\276\277" "\300\301\302\303\304\305\306\307\310\311\312\313\314\315\316\317" "\320\321\322\323\324\325\326\327\330\331\332\333\334\335\336\337" - split(a, A, "") - for (a in A) { - for (b in A) { - _UIDARR0[A[a] A[b]] _UIDARR1[A[a] A[b]] + if (m in A) { + if (m "~" in A) { + if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { + return } } - _uidcntr = A[a] A[b] + m = A[m] + return @m(p, p0, p1) } +} - function _tgetitem(p, n, a, b) - { - if (p) { - if (isarray(_PTR[p]["ITEM"]) && n in _PTR[p]["ITEM"]) { - a = _PTR[p]["ITEM"][n] - } else { - a = _PTR[p]["ITEM"][n] = _N() - } - if (! (b = _rFCHLD(a))) { - b = _wLCHLD(a, _N()) - _PTR[b]["HOST"] = p - _[b]["ITEMNAME"] = n - } - return b +#_________________________________________________________________ +function _tframe3(f, p, p0, p1, p2, p3, A) +{ + ############################# + if (_isptr(p)) { + if (isarray(f)) { + return _tframe3_i0(f, p, p0, p1, p2) } + _tframex_p0(A, f, 3) + return _th0(_tframe3_i0(A, p, p0, p1, p2), --_TEND[_ARRLEN]) } +} - function _tgetsp(p) - { - return _tSTACK[p][0] +#_______________________________________________ +function _tframe3_i0(A, p, p0, p1, p2) +{ + _tframe_link = p + while (p in _tLINK) { + p = _tLINK[p] } - - function _th0(p, p1, p2, p3) - { - return p - } - - function _th1(p0, p, p2, p3) - { - return p - } - - function _th10(p0, p1) - { - return (p1 p0) + if (p in _tFCHLD) { + return (_tframe3_i2(A, "^", p, p0, p1, p2) _tframe3_i1(A, _tFCHLD[p], p0, p1, p2)) } + return _tframe3_i2(A, ".", p, p0, p1, p2) +} - function _th2(p0, p1, r, p3) - { - return p +#_______________________________________________ +function _tframe3_i1(A, p, p0, p1, p2) +{ + if (_TEND[_ARRLEN] in _TEND) { + return } - - function _th3(p0, p1, p2, r) - { - return p + if (p in _tNEXT) { + return (_tframe3_i0(A, p, p0, p1, p2) _tframe3_i1(A, _tNEXT[p], p0, p1, p2)) } + return _tframe3_i0(A, p, p0, p1, p2) +} - function _tifend(l) - { - return ((_t_ENDF[0] + l in _t_ENDF ? (_t_ENDF[_t_ENDF[0] + l] ? _t_ENDF[_t_ENDF[0] + l] : 1) : "")) +#_______________________________________________ +function _tframe3_i2(A, m, p, p0, p1, p2) +{ + _tframe_dlink = p + while (p in _tDLINK) { + p = _tDLINK[p] } - - function _tinit_i0(D, S, i) - { - for (i in S) { - if (isarray(S[i])) { - if (! isarray(D[i][""])) { - delete D[i] - D[i][""] - delete D[i][""] - } - _N_i0(D[i], S[i]) - } else { - if (isarray(D[i])) { - delete D[i] - } - D[i] = S[i] + if (m in A) { + if (m "~" in A) { + if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { + return } } + m = A[m] + return @m(p, p0, p1, p2) } +} - function _tlist(L, p, f) - { - _tlisti1 = _tlisti0 = L[_ARRLEN] + 0 - if (f == 0 && f == "") { - _tlist_i0(L, p) - } else { - _tlistf0 = (f in _TAPI ? _TAPI[f] : f) - _tlist_i1(L, p) +#_________________________________________________________________ +function _tframe4(f, p, p0, p1, p2, p3, A) +{ + ############################# + if (_isptr(p)) { + if (isarray(f)) { + return _tframe4_i0(f, p, p0, p1, p2, p3) } - return (_tlisti0 - _tlisti1) + _tframex_p0(A, f, 4) + return _th0(_tframe4_i0(A, p, p0, p1, p2, p3), --_TEND[_ARRLEN]) } +} - function _tlist_i0(L, p, q, i) - { - if (isarray(p)) { - q = p[_ARRLEN] - i = 0 - while (i++ < q) { - _tlist_i0(L, p[i]) - } - return - } - if (p in _) { - while (p in _tLINK) { - p = _tLINK[p] - } - L[++_tlisti0] = p - if (p in _tFCHLD) { - for (p = _tFCHLD[p]; p; p = (p in _tNEXT ? _tNEXT[p] : "")) { - _tlist_i0(L, p) - } - } - } +#_______________________________________________ +function _tframe4_i0(A, p, p0, p1, p2, p3) +{ + _tframe_link = p + while (p in _tLINK) { + p = _tLINK[p] } + if (p in _tFCHLD) { + return (_tframe4_i2(A, "^", p, p0, p1, p2, p3) _tframe4_i1(A, _tFCHLD[p], p0, p1, p2, p3)) + } + return _tframe4_i2(A, ".", p, p0, p1, p2, p3) +} - function _tlist_i1(L, p) - { - if (isarray(p)) { - q = p[_ARRLEN] - i = 0 - while (i++ < q) { - _tlist_i1(L, p[i]) +#_______________________________________________ +function _tframe4_i1(A, p, p0, p1, p2, p3) +{ + if (_TEND[_ARRLEN] in _TEND) { + return + } + if (p in _tNEXT) { + return (_tframe4_i0(A, p, p0, p1, p2, p3) _tframe4_i1(A, _tNEXT[p], p0, p1, p2, p3)) + } + return _tframe4_i0(A, p, p0, p1, p2, p3) +} + +#_______________________________________________ +function _tframe4_i2(A, m, p, p0, p1, p2, p3) +{ + _tframe_dlink = p + while (p in _tDLINK) { + p = _tDLINK[p] + } + if (m in A) { + if (m "~" in A) { + if (! (_TYPEWORD in _[p]) || A[m "~"] !~ _[p][_TYPEWORD]) { + return } - return } - if (p in _) { - while (p in _tLINK) { - p = _tLINK[p] - } - if (_tlistf0 in _[p]) { - L[++_tlisti0] = p + m = A[m] + return @m(p, p0, p1, p2, p3) + } +} + +#___________________________________________________________ +function _tframe_i0(f, p, p0, p1, p2, a) +{ + while (p in _tLINK) { + p = _tLINK[p] + } + return ((p in _tFCHLD ? _tmframe_i0(f, _tFCHLD[p], p0, p1, p2) : (p in _tDLINK ? @f(_tDLINK[p], p0, p1, p2) : @f(p, p0, p1, p2)))) +} + +#___________________________________________________________ +function _tframe_i1(F, p, p0, p1, p2, a) +{ + while (p in _tLINK) { + p = _tLINK[p] + } + return ((p in _tFCHLD ? (("." in F ? _th1(a = F["."], @a(p, p0, p1, p2)) : "")) _tmframe_i1(F, _tFCHLD[p], p0, p1, p2) : (">" in F ? _th1(a = F[">"], (p in _tDLINK ? @a(_tDLINK[p], p0, p1, p2) : @a(p, p0, p1, p2))) : ""))) +} + +#_______________________________________________________________________ +function _tframex(f, p, p0, p1) +{ + ############################################ + delete _t_ENDF[++_t_ENDF[0]] + f = (p ? _tframex_i0(f, p, p0, p1) : "") + --_t_ENDF[0] + return f +} + +#___________________________________________________________ +function _tframex_i0(f, p, p0, p1) +{ + while (p in _tLINK) { + p = _tLINK[p] + } + return ((p in _tFCHLD ? _tmframex(f, _tFCHLD[p], p0, p1) : @f(p, p0, p1))) +} + +#_____________________________________________________ +function _tframex_p0(A, f, q, i, B, C) +{ + _tframe_qparam = q + delete _TEND[++_TEND[_ARRLEN]] + if (match(f, /\~(.*)$/, B)) { + A["^~"] = A[".~"] = B[1] + f = substr(f, 1, RSTART - 1) + } + A["."] = A["^"] = f + return + q = split(f, B, /;/) + i = 0 + while (i < q) { + _tframex_p1(A, C[i]) + while (++i <= q) { + _tframex_p1(A, C[i], B[i]) + } + } +} + +#_______________________________________________ +function _tframex_p1(A, v, i, r, B) +{ + gsub(/[ \t]+/, "", v) + while (match(v, /^([^~]*)~\/(([^\/\\]*\\.)*[^\/\\]*)\//, B)) { + v = B[1] substr(v, RSTART + RLENGTH) + r = B[2] + } + if (i == "") { + if (v != "") { + A["."] = v + delete A["`"] + delete A["^"] + } + if (r != "") { + A[".~"] = A["`~"] = A["^~"] = r + } + } else { + if (match(v, /!/)) { + delete A[i] + } else { + A[i] = v + if (r != "") { + A[i "~"] = r + } + } + } +} + +#_____________________________________________________ +# F v action +#----------------------------------------------------- +# - * no additional action +# A B delete A[p] and define A[p] as array; copy array B to array A[p] +# A - delete A[p] +# A "*" delete A[p]; A[p]="*" +# "*" B define _[p]["*"] as array; copy array B to array _[p]["*"] +# "*" - run _mpu program "*" for `p +# "*0" "*1" _[p]["*0"]="*1" +#___________________________________________________________ +function _tgenuid(c) +{ + for (_uidcntr in _UIDARR1) { + delete _UIDARR1[_uidcntr] + for (c in _UIDARR0) { + _UIDS[_uidcntr c] + } + delete _UIDS[_uidcntr c] + return (_uidcntr c) + } + return _fatal("_tUID: Out of UID range") +} + +#_____________________________________________________ +function _tgenuid_init(a, b, A) +{ + _ptrlength = 4 + a = "\222\223\224\225\226\227\230\231\232" "\240\241\242\243\244\245\246\247" "\260\261\262\263\264\265\266\267\270\271\272\273\274\275\276\277" "\300\301\302\303\304\305\306\307\310\311\312\313\314\315\316\317" "\320\321\322\323\324\325\326\327\330\331\332\333\334\335\336\337" + split(a, A, "") + for (a in A) { + for (b in A) { + _UIDARR0[A[a] A[b]] _UIDARR1[A[a] A[b]] + } + } + _uidcntr = A[a] A[b] +} + +# if ( F in _TCLASS ) { _[p]["CLASS"]=_TCLASS[F]; _tapi(p); return p } +# # ??? _mpu(F,p) ??? +# return p } +# _[p][F]=v; return p } + +#_______________________________________________________________________ +function _tgetitem(p, n, a, b) +{ + ############################################ + if (p) { + if (isarray(_PTR[p]["ITEM"]) && n in _PTR[p]["ITEM"]) { + a = _PTR[p]["ITEM"][n] + } else { + a = _PTR[p]["ITEM"][n] = _N() + } + if (! (b = _rFCHLD(a))) { + b = _wLCHLD(a, _N()) + _PTR[b]["HOST"] = p + _[b]["ITEMNAME"] = n + } + return b + } +} + +#_________________________________________________________________ +function _tgetsp(p) +{ + ############################################### + return _tSTACK[p][0] +} + +#################################################################################### + +#_____________________________________________________________________________ +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) +{ + return p +} + +#_________________________________________________________________ +function _tifend(l) +{ + ############################################### + return ((_t_ENDF[0] + l in _t_ENDF ? (_t_ENDF[_t_ENDF[0] + l] ? _t_ENDF[_t_ENDF[0] + l] : 1) : "")) +} + +# test _tbrochld fn; develope tOBJ r\w func specification for brochld func + +#_________________________________________________________________ +function _tinit_i0(D, S, i) +{ + for (i in S) { + if (isarray(S[i])) { + if (! isarray(D[i][""])) { + delete D[i] + D[i][""] + delete D[i][""] } - if (p in _tFCHLD) { - for (p = _tFCHLD[p]; p; p = (p in _tNEXT ? _tNEXT[p] : "")) { - _tlist_i1(L, p) - } + _N_i0(D[i], S[i]) + } else { + if (isarray(D[i])) { + delete D[i] } + D[i] = S[i] } } +} - 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] : "")) - } - return 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] : "") - } - return 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] : "")) - } - return p0 - } - 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] : "") - } - return p0 - } - 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] - return f - } - function _tmframe_i0(f, p, p0, p1, p2, t) - { - while (p && ! (_t_ENDF[0] in _t_ENDF)) { - t = t _tframe_i0(f, p, p0, p1, p2, p = (p in _tNEXT ? _tNEXT[p] : "")) - } - return t - } - function _tmframe_i1(F, p, p0, p1, p2, t) - { - while (p && ! (_t_ENDF[0] in _t_ENDF)) { - t = t _tframe_i1(F, p, p0, p1, p2, p = (p in _tNEXT ? _tNEXT[p] : "")) - } - return 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] : "") - } - return 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] : "")) - } - return p0 - } - 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] : "") - } - return p0 - } - function _torexp(r) - { - return _subseqon(_TOREXPB0, gensub(/(^[ \t]+)|(([ \t]*(\\)+)+[ \t]*)|([ \t]+$)/, "\\4", "G", _subseqoff(r, _TOREXPB0)), _TOREXPFN) - } - function _torexp_cmdstr(t) - { - return _strtorexp(gensub(/\^(.)/, "\\1", "G", t)) - } - function _torexp_fmask(t) - { - return gensub(/\\\*/, ".*", "G", gensub(/\\\?/, ".?", "G", _strtorexp(t))) - } - function _torexp_init() - { - _TOREXPFN[""] = "_strtorexp" - _TOREXPFN["~"] = "_torexp_rexp" - _TOREXPFN["="] = "_strtorexp" - _TOREXPFN[">"] = "_torexp_cmdstr" - _TOREXPFN["#"] = "_torexp_fmask" - _TOREXPFN["\""] = "_torexp_dqstr" - _TOREXPFN["'"] = "_torexp_sqstr" - } - function _torexp_rexp(t) - { - return t - } - function _tpass(f, p, p0, p1) - { - delete _t_ENDF[++_t_ENDF[0]] - f = (p ? _tpass_i0(f, p, p0, p1) : "") - --_t_ENDF[0] - return f - } - function _tpass_i0(f, p, p0, p1, a) - { - while (p in _tLINK) { - p = _tLINK[p] - } - return ((p in _tFCHLD ? _tmpass(f, _tFCHLD[p], p0, p1) : @f(p, p0, p1))) - } - function _tpassx(f, p, p0, p1) - { - delete _t_ENDF[++_t_ENDF[0]] - f = (p ? _tpassx_i0(f, p, p0, p1) : "") - --_t_ENDF[0] - return f - } - function _tpassx_i0(f, p, p0, p1) - { - while (p in _tLINK) { - p = _tLINK[p] - } - return ((p in _tFCHLD ? _tmpassx(f, _tFCHLD[p], p0, p1) : @f(p, p0, p1))) - } - function _tpop(p, aA, a) - { - if ((a = _tSTACK[p][0]) > 0) { - _tSTACK[p][0]-- - if (isarray(_tSTACK[p][a])) { - delete aA - _movarr(aA, _tSTACK[p][a]) - return - } - return _tSTACK[p][a] - } - _fatal("^" p ": Out of tSTACK") - } - function _tpush(p, aA, a) - { - if (isarray(aA)) { - delete _tSTACK[p][a = ++_tSTACK[p][0]] - _tSTACK[p][a][""] - delete _tSTACK[p][a][""] - _movarr(_tSTACK[p][a], aA) - return - } - delete _tSTACK[p][a = ++_tSTACK[p][0]] - return (_tSTACK[p][a] = aA) - } - - function _tr(n, cs, H) - { - _rconline(n ": " cs) - _rconl() - if (match(cs, /^((([^\xB4:\[\|\]]*\xB4.)*[^\xB4:\[\|\]]*):)?((([^\xB4\[\|\]]*\xB4.)*[^\xB4\[\|\]]*)\[)?(([^\xB4\|\]]*\xB4.)*[^\xB4\|\]]*)?(\|(\.)?(([^\xB4\]]*\xB4.)*[^\xB4\]]*))?(\](.*))?$/, H)) { - _rconl("delptr: " _une(H[2]) "'") - _rconl("pfxstr: " _une(H[5]) "'") - _rconl("hichr: " _une(H[7]) "'") - _rconl("lochr: " _une((H[10] ? H[7] "' and " H[11] "'" : H[11] "'"))) - _rconl("sfxstr: " _une(H[14]) "'") - } else { - _rconl("NOT MATCH!") - } - _rconl() - } - function _trace(t, d, A) - { - if (_ERRLOG_TF) { - A["TYPE"] = "TRACE" - A["TEXT"] = t - _log(A, d) - } - } - function _trunframe(f, p, p0, p1, p2) - { - return _tframe((f ? f : "_trunframe_i0"), p, p0, p1, p2) - } +#_______________________________________________________________________ +# _N(arr\str\mpuptr,val) \ _n(arr\str\mpuptr,val) +# This functions create new object and return ptr. +# _n() - creates object from list of deleted objects or if it's empty create new one, while _N() always create new one +# It is strongly recommended to use _N() for the objects that have some data outside of standart object arrays. Or - make routines +# that will clear outsided object data in case if object deleting. +# +# IN: arr\str\mpu,val - (both missed) just create obj and return ptr +# arr,val - create object and write arr[ptr]=val +# str,val - create object and write _[ptr][str]=val +# mpuptr - NOT ALLOWED (val missed) create object and run MPU-code specified by mpuptr with created object ptr as primary parameter +# MOD: - +# OUT: - +# RETURN: ptr - pointer to newly created object +#_________________________________________________________________ +# _tdel(ptr) +# This function exclude object from it's current structure and delete it. ptr can be later used by function: _n() for creating new object +# Also same story will occured with all chields and subchields of object specified by ptr. +# ??? What happened with linked py _ptr[ptr] objects ??? +# +# IN: ptr - pointer to object that will deleted +# MOD: - +# OUT: - +# RETURN: undefined +#_________________________________________________________________ +# _isptr(ptr) +# This function checks: is ptr is the object pointer that is currently exist? +# Unescaped remained data will be in data of src_dst_ptr. +# +# IN: ptr - string that will be tested +# MOD: - +# OUT: - +# RETURN: undefined - if ptr is not pointer to exist object +# ptr - if ptr is the pointer to exist object +#_________________________________________________________________ - function _trunframe_i0(p, p0, p1, p2, f) - { - if (p in _tFN) { - f = _tFN[p] - return @f(p, p0, p1, p2) - } - } - 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) - } +#_________________________________________________________________ +# +# TO DESIGN: +# +# create basic objectapi interface support +# modify everywhere checking ptr not by `if ( ptr )...', but by `if ( ptr in _ )...' +# _TMP0, _TMP1 name change to something like _DATA name ??? +# think about redesigning routines for not depending if ptr is exist in tsysarrs: reason: performance\light code - function _trunpassx(f, p, p0, p1) - { - return _tpassx((f ? f : "_trunframe_i0"), p, p0, p1) - } - function _tsetsp(p, v) - { - return (_tSTACK[p][0] = v) - } - function _tstini() - { - _ini("uidel:pfx'hstr|lstr'sfx") - _ini("uidel:pfx'hstr|lstr'") - _ini("uidel:'hstr|lstr'sfx") - _ini("uidel:'hstr|lstr'") - _ini("uidel:pfx'hstr'sfx") - _ini("uidel:pfx'hstr'") - _ini("uidel:'hstr'sfx") - _ini("uidel:'hstr'") - _conl() - _conl("########################################################################################") - _conl() - _ini("pfx'hstr|lstr'sfx") - _ini("pfx'hstr|lstr'") - _ini("'hstr|lstr'sfx") - _ini("'hstr|lstr'") - _ini("pfx'hstr'sfx") - _ini("pfx'hstr'") - _ini("'hstr'sfx") - _ini("'hstr'") - _conl() - _conl("########################################################################################") - _conl() - _ini("uidel:pfx'`cntptr'sfx") - _ini("uidel:pfx'`cntptr'") - _ini("uidel:'`cntptr'sfx") - _ini("uidel:'`cntptr'") - _conl() - _conl("########################################################################################") - _conl() - _ini("pfx'`cntptr'sfx") - _ini("pfx'`cntptr'") - _ini("'`cntptr'sfx") - _ini("'`cntptr'") - _conl() - _conl("########################################################################################") - _conl() - _ini("uidel:pfx'^chrptr'sfx") - _ini("uidel:pfx'^chrptr'") - _ini("uidel:'^chrptr'sfx") - _ini("uidel:'^chrptr'") - _conl() - _conl("########################################################################################") - _conl() - _ini("pfx'^chrptr'sfx") - _ini("pfx'^chrptr'") - _ini("'^chrptr'sfx") - _ini("'^chrptr'") - _conl() - _conl("########################################################################################") - _conl() - } - function _tstv(p, A, r, f) - { - if (f == "") { - f = "tst_splitstr" - } - @f(_NOP, A, p) - @f(AA0, A, p) - @f(AB0, A, p) - @f(AC0, A, p) - @f("", A, p) - @f("a", A, p) - @f("\264a", A, p) - @f("\264", A, p) - @f("a\264\264\264,ba\264\264\264,", A, p) - @f("\264,", A, p) - @f(",", A, p) - @f("\264a,", A, p) - @f("ab,", A, p) - @f("ab,\264", A, p) - @f("\264a\264,,ba", A, p) - @f(",a,,b\264,c,,\264a,,\264,,,", A, p) - } - function _typ(p) - { - return (_t0 = (isarray(p) ? "#" : (p == 0 ? (p == "" ? 0 : (p in _CLASSPTR ? "`" : (p ? 3 : 4))) : (p in _CLASSPTR ? "`" : (p + 0 == p ? 5 : (p ? 3 : 2)))))) - } - function _typa(p, A) - { - return (_t0 = (isarray(p) ? "#" : (p == 0 ? (p == "" ? 0 : (p in A ? "`" : (p ? 3 : 4))) : (p in A ? "`" : (p + 0 == p ? 5 : (p ? 3 : 2)))))) - } - function _tzend(a, b) - { - if (b == 0 && b == "") { - return (_TEND[_TEND[_ARRLEN]] = a) - } else { - return (_TEND[_TEND[_ARRLEN] + a] = b) - } - } - function _uidcyc(p, i) - { - _dumpuidgen(p) - for (i = 1; i < 64 * 8 * 6 - 1; i++) { - _conl(i ":" _var(_getuid(p))) - } - _dumpuidgen(p) - } - function _une(t) - { - return gensub(/\xB4(.)/, "\\1", "G", t) - } - function _unformatrexp(t) - { - _formatstrq0 = split(t, _FORMATSTRA, /(\\[0-9]{1,3})|(\\x[[:xdigit:]]+)|(\\.)/, _FORMATSTRB) - _formatstrs0 = "" - for (t = 1; t < _formatstrq0; t++) { - _formatstrs0 = _formatstrs0 _FORMATSTRA[t] ((_FORMATSTRB[t] in _QESCHR ? _QESCREXP[_FORMATSTRB[t]] : _QESCREXP[toupper(substr(_FORMATSTRB[t], length(_FORMATSTRB[t]) - 1))])) - } - return (_formatstrs0 _FORMATSTRA[t]) - } - function _unformatrexp_init(i, a) - { - _formatstrs0 = "\\^$.[]|()*+?{}-sSwW<>yB`'" - delete _FORMATSTRB - for (i = 0; i < 256; i++) { - _QESCREXP["\\" _CHR[i]] = (index(_formatstrs0, _CHR[i]) ? "\\" _CHR[i] : _CHR[i]) - } - for (i = 0; i < 256; i++) { - a = (index(_formatstrs0, _CHR[i]) ? "\\" : "") - _QESCREXP[sprintf("%.2X", i)] = a _CHR[i] - _QESCREXP["\\" sprintf("%.3o", i)] = a _CHR[i] - if (i < 8) { - _QESCREXP["\\" sprintf("%.1o", i)] = a _CHR[i] - } - if (i < 64) { - _QESCREXP["\\" sprintf("%.2o", i)] = a _CHR[i] - } - if (i < 16) { - _QESCREXP["\\x" sprintf("%.1X", i)] = _QESCREXP["\\x" sprintf("%.1x", i)] = a _CHR[i] - } - } - patsplit("a" 7 "b" 8 "f" 12 "n" 10 "r" 13 "t" 9 "v" 11, _FORMATSTRA, /[^0-9]/, _FORMATSTRB) - for (i in _FORMATSTRA) { - _QESCREXP["\\" _FORMATSTRA[i]] = _CHR[_FORMATSTRB[i] + 0] - } +function _tlist(L, p, f) +{ + _tlisti1 = _tlisti0 = L[_ARRLEN] + 0 + if (f == 0 && f == "") { + _tlist_i0(L, p) + } else { + _tlistf0 = (f in _TAPI ? _TAPI[f] : f) + _tlist_i1(L, p) } + return (_tlisti0 - _tlisti1) +} - function _unformatstr(t) - { - _formatstrq0 = split(t, _FORMATSTRA, /(\\[0-9]{1,3})|(\\x[[:xdigit:]]+)|(\\.)/, _FORMATSTRB) - _formatstrs0 = "" - for (t = 1; t < _formatstrq0; t++) { - _formatstrs0 = _formatstrs0 _FORMATSTRA[t] ((_FORMATSTRB[t] in _QESCHR ? _QESCHR[_FORMATSTRB[t]] : _QESCHR[toupper(substr(_FORMATSTRB[t], length(_FORMATSTRB[t]) - 1))])) +function _tlist_i0(L, p, q, i) +{ + if (isarray(p)) { + q = p[_ARRLEN] + i = 0 + while (i++ < q) { + _tlist_i0(L, p[i]) } - return (_formatstrs0 _FORMATSTRA[t]) + return } - - function _unformatstr_init(i) - { - for (i = 0; i < 256; i++) { - _QESCHR["\\" _CHR[i]] = _CHR[i] - } - for (i = 0; i < 256; i++) { - _QESCHR[sprintf("%.2X", i)] = _CHR[i] - _QESCHR["\\" sprintf("%.3o", i)] = _CHR[i] - if (i < 8) { - _QESCHR["\\" sprintf("%.1o", i)] = _CHR[i] - } - if (i < 64) { - _QESCHR["\\" sprintf("%.2o", i)] = _CHR[i] - } - if (i < 16) { - _QESCHR["\\x" sprintf("%.1X", i)] = _QESCHR["\\x" sprintf("%.1x", i)] = _CHR[i] - } - } - i = "a" 7 "b" 8 "f" 12 "n" 10 "r" 13 "t" 9 "v" 11 - patsplit(i, _FORMATSTRA, /[^0-9]/, _FORMATSTRB) - for (i in _FORMATSTRA) { - _QESCHR["\\" _FORMATSTRA[i]] = _CHR[_FORMATSTRB[i] + 0] + if (p in _) { + while (p in _tLINK) { + p = _tLINK[p] } - } - - function _uninit_del(A, i, p0) - { - _del(i) - } - - function _unstr(t) - { - return gensub(/\\(.)/, "\\1", "G", t) - } - - function _untmp(f, a) - { - if (f = filepath(f)) { - if (match(f, /\\$/)) { - _deletepfx(_FILEIO_RDTMP, a = toupper(f)) - _deletepfx(_FILEIO_RDNETMP, a) - } else { - delete _FILEIO_RDNETMP[toupper(f)] + L[++_tlisti0] = p + if (p in _tFCHLD) { + for (p = _tFCHLD[p]; p; p = (p in _tNEXT ? _tNEXT[p] : "")) { + _tlist_i0(L, p) } - return f } - return "" } +} - function _val(v, t) - { - if (isarray(v)) { - return (_dumparr(v) _ln(t)) - } - if (v == 0 && v == "") { - return (_ln("- (ERRNO=" ERRNO ")") _ln(t)) +function _tlist_i1(L, p) +{ + if (isarray(p)) { + q = p[_ARRLEN] + i = 0 + while (i++ < q) { + _tlist_i1(L, p[i]) } - return (_ln(v "'") _ln(t)) + return } - - function _val0(v) - { - if (isarray(v)) { - return _dumparr(v) - } - if (v == 0 && v == "") { - return "-" + if (p in _) { + while (p in _tLINK) { + p = _tLINK[p] } - return ("\"" v "\"") - } - - function _var(v, t) - { - if (isarray(v)) { - return (_dumparr(v) _ln(t)) + if (_tlistf0 in _[p]) { + L[++_tlisti0] = p } - if (v == 0 && v == "") { - return (_ln("- (ERRNO=" ERRNO ")") _ln(t)) + if (p in _tFCHLD) { + for (p = _tFCHLD[p]; p; p = (p in _tNEXT ? _tNEXT[p] : "")) { + _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] : "")) + } + return 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] : "") + } + return 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] : "")) + } + return p0 +} + +#_________________________________________________________________ +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] : "") + } + return p0 +} + +#_________________________________________________________________ +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] + return f +} + +#___________________________________________________________ +function _tmframe_i0(f, p, p0, p1, p2, t) +{ + while (p && ! (_t_ENDF[0] in _t_ENDF)) { + t = t _tframe_i0(f, p, p0, p1, p2, p = (p in _tNEXT ? _tNEXT[p] : "")) + } + return t +} + +#___________________________________________________________ +function _tmframe_i1(F, p, p0, p1, p2, t) +{ + while (p && ! (_t_ENDF[0] in _t_ENDF)) { + t = t _tframe_i1(F, p, p0, p1, p2, p = (p in _tNEXT ? _tNEXT[p] : "")) + } + return 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] : "") + } + return 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] : "")) + } + return p0 +} + +#_________________________________________________________________ +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] : "") + } + return p0 +} + +function _torexp(r) +{ + return _subseqon(_TOREXPB0, gensub(/(^[ \t]+)|(([ \t]*(\\)+)+[ \t]*)|([ \t]+$)/, "\\4", "G", _subseqoff(r, _TOREXPB0)), _TOREXPFN) +} + +function _torexp_cmdstr(t) +{ + return _strtorexp(gensub(/\^(.)/, "\\1", "G", t)) +} + +function _torexp_fmask(t) +{ + return gensub(/\\\*/, ".*", "G", gensub(/\\\?/, ".?", "G", _strtorexp(t))) +} + +#_______________________________________________ +function _torexp_init() +{ + _TOREXPFN[""] = "_strtorexp" + _TOREXPFN["~"] = "_torexp_rexp" + _TOREXPFN["="] = "_strtorexp" + _TOREXPFN[">"] = "_torexp_cmdstr" + _TOREXPFN["#"] = "_torexp_fmask" + _TOREXPFN["\""] = "_torexp_dqstr" + _TOREXPFN["'"] = "_torexp_sqstr" +} + +#_______________________________________________ +function _torexp_rexp(t) +{ + return t +} + +#_____________________________________________________________________________ +function _tpass(f, p, p0, p1) +{ + #################################################### + delete _t_ENDF[++_t_ENDF[0]] + f = (p ? _tpass_i0(f, p, p0, p1) : "") + --_t_ENDF[0] + return f +} + +#___________________________________________________________ +function _tpass_i0(f, p, p0, p1, a) +{ + while (p in _tLINK) { + p = _tLINK[p] + } + return ((p in _tFCHLD ? _tmpass(f, _tFCHLD[p], p0, p1) : @f(p, p0, p1))) +} + +#_____________________________________________________________________________ +function _tpassx(f, p, p0, p1) +{ + ################################################### + delete _t_ENDF[++_t_ENDF[0]] + f = (p ? _tpassx_i0(f, p, p0, p1) : "") + --_t_ENDF[0] + return f +} + +#___________________________________________________________ +function _tpassx_i0(f, p, p0, p1) +{ + while (p in _tLINK) { + p = _tLINK[p] + } + return ((p in _tFCHLD ? _tmpassx(f, _tFCHLD[p], p0, p1) : @f(p, p0, p1))) +} + +#_________________________________________________________________ +function _tpop(p, aA, a) +{ + ########################################### + if ((a = _tSTACK[p][0]) > 0) { + _tSTACK[p][0]-- + if (isarray(_tSTACK[p][a])) { + delete aA + _movarr(aA, _tSTACK[p][a]) + return } - return (_ln(v "'") _ln(t)) + return _tSTACK[p][a] } + _fatal("^" p ": Out of tSTACK") +} - function _verb(t, d, A) - { - if (_ERRLOG_VF) { - A["TYPE"] = "VERB" - A["TEXT"] = t - _log(A, d) - } +#_____________________________________________________________________________ +function _tpush(p, aA, a) +{ + ###################################################### + if (isarray(aA)) { + delete _tSTACK[p][a = ++_tSTACK[p][0]] + _tSTACK[p][a][""] + delete _tSTACK[p][a][""] + _movarr(_tSTACK[p][a], aA) + return } - - function _wFBRO(p, v, a) - { - if (p) { - if (v) { - for (a = p; a in _tPARENT; ) { - if ((a = _tPARENT[a]) == v) { - return v - } - } - if (p in _tPARENT) { - p = _tPARENT[p] - if (v in _tNEXT) { - if (v in _tPREV) { - _tPREV[_tNEXT[a] = _tNEXT[v]] = a = _tPREV[v] - delete _tPREV[v] - if (v in _tPARENT) { - if (p == (a = _tPARENT[v])) { - return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[p]] = v) - } - --_tQCHLD[a] - } - } else { - if (v in _tPARENT) { - if (p == (a = _tPARENT[v])) { - return v - } - delete _tPREV[_tFCHLD[a] = _tNEXT[v]] - --_tQCHLD[a] - } else { - delete _tPREV[_tNEXT[v]] - } - } - ++_tQCHLD[p] - return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[_tPARENT[v] = p]] = v) - } else { - if (v in _tPREV) { - if (v in _tPARENT) { - delete _tNEXT[_tLCHLD[a = _tPARENT[v]] = _tPREV[v]] - if (p == a) { - delete _tPREV[v] - return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[p]] = v) - } - --_tQCHLD[a] - } else { - delete _tNEXT[_tPREV[v]] - } - delete _tPREV[v] - } else { - if (v in _tPARENT) { - if (p == (a = _tPARENT[v])) { - return v - } - delete _tFCHLD[a] - delete _tLCHLD[a] - delete _tQCHLD[a] - } - } - ++_tQCHLD[p] - return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[_tPARENT[v] = p]] = v) - } - } else { - while (p in _tPREV) { - p = _tPREV[p] - } - if (v in _tPREV) { - if (v in _tPARENT) { - --_tQCHLD[a = _tPARENT[v]] - delete _tPARENT[v] - if (v in _tNEXT) { - _tNEXT[_tPREV[a] = _tPREV[v]] = a = _tNEXT[v] - } else { - delete _tNEXT[_tLCHLD[a] = _tPREV[v]] - } - } else { - if (v in _tNEXT) { - _tNEXT[_tPREV[a] = _tPREV[v]] = a = _tNEXT[v] - } else { - delete _tNEXT[_tPREV[v]] - } - } - delete _tPREV[v] - } else { - if (p == v) { - return v - } - if (v in _tPARENT) { - if (v in _tNEXT) { - delete _tPREV[_tFCHLD[a = _tPARENT[v]] = _tNEXT[v]] - --_tQCHLD[a] - } else { - delete _tLCHLD[a = _tPARENT[v]] - delete _tFCHLD[a] - delete _tQCHLD[a] - } - delete _tPARENT[v] - } else { - if (v in _tNEXT) { - delete _tPREV[_tNEXT[v]] - } - } - } - return (_tPREV[_tNEXT[v] = p] = v) - } - } else { - if (v == 0) { - return v - } - return v - } + delete _tSTACK[p][a = ++_tSTACK[p][0]] + return (_tSTACK[p][a] = aA) +} + +# prefix - +# prichr - aware character `{', `^',`]' +# sechr - aware character `.' as the first char of sechr, and character `}' +# suffix - aware character `]' +# cntptr - aware character `]' + +function _tr(n, cs, H) +{ + #_tuidinitcs[p]=cs + #2 uidel, 5 pfx, 7 hichr,11(10) lochr,14 suffix + _rconline(n ": " cs) + _rconl() + if (match(cs, /^((([^\xB4:\[\|\]]*\xB4.)*[^\xB4:\[\|\]]*):)?((([^\xB4\[\|\]]*\xB4.)*[^\xB4\[\|\]]*)\[)?(([^\xB4\|\]]*\xB4.)*[^\xB4\|\]]*)?(\|(\.)?(([^\xB4\]]*\xB4.)*[^\xB4\]]*))?(\](.*))?$/, H)) { + _rconl("delptr: " _une(H[2]) "'") + _rconl("pfxstr: " _une(H[5]) "'") + _rconl("hichr: " _une(H[7]) "'") + _rconl("lochr: " _une((H[10] ? H[7] "' and " H[11] "'" : H[11] "'"))) + _rconl("sfxstr: " _une(H[14]) "'") + } else { + _rconl("NOT MATCH!") + } + _rconl() +} + +#_______________________________________________________________________ +function _trace(t, d, A) +{ + ################################################# + if (_ERRLOG_TF) { + A["TYPE"] = "TRACE" + A["TEXT"] = t + _log(A, d) + } +} + +#_________________________________________________________________ +function _trunframe(f, p, p0, p1, p2) +{ + ################################# + return _tframe((f ? f : "_trunframe_i0"), p, p0, p1, p2) +} + +#_________________________________________________________________ +function _trunframe_i0(p, p0, p1, p2, f) +{ + if (p in _tFN) { + f = _tFN[p] + return @f(p, p0, p1, p2) + } +} + +#_________________________________________________________________ +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) +} + +# dptr - morg ptr; in case if object deleted then _CLASSPTR[ptr] will be deleted(object is death), but +# _tUIDEL[_CLASSPTR[ptr]] will be created that object can be resurrected from morg +# dptr can be any string containing any characters except `:'. It's not verified +# pfx,sfx - uid prefix str, and uid suffix str; this strings specifies string that can be inserted before/after +# uid generated by uid generator: +# +# class uid: pfx uidgen sfx +# +# Both can be any string(including ""), and can contains any character with B4-escaping feature. +# Note: that this strings cannot contains "'" character: it's should be escaped by B4-escaper. +# hstr,lstr - this values configure uid-generator itself. ther is a 3 combinations regarding its: +# +# hstr lstr function +# +# `ptr * - specify pointer to external uid-generator +# All uids and chars will be generated by external uid-generator +# * ^ptr - class will have it's own uid generator using external character set +# str str - class will have it's own uid generator with it's own character set +# character set inmplemented in hstr(high-charset) and in lstr(low-charset) in 2 ways: +# 1) "AB" "AB01" - this mean that high-charset contain chars: `A' and `B' +# low-charset contains chars: `A', `B', `0', `1' +# +# 2) "Az,By" "Ax,Bw,0v,1u" - this mean that high-charset contain chars: `Az' and `By' +# low-charset contains chars: `Ax', `Bw', `0v', `1u' +# Note: both: hstr and lstr cannot contain char `,' directly, but it's can uses +# B4-escaper to escape any char including `,' + + + +# !!!! in case of using `,' in hstr/lstr - the escaped `,' will leads to interpretate hstr and lstr as divided by `,' +# if parameters error then i should be more specific about what error in parameters detected +# document _inituid(): parameters; document cs: uid initialization string format +# test with escape char +# adv hstr and lstr splitting? +# chk if hstr len==0 ? +# return _tclass & report error? +# _tapi thru function + +# additional syntax checking ??? +# implement syntax and uid srv in docs +# add _dumpuid() ???? +# make performance measurement +# protection against badchar list +# additional feature to specify _getuid() to not resurrect uid; and informative that uid was ressurected or not +# build _defclass fn + +# _tuidinitcs ???? +# _tuidchrh[p] +# _tuidchrl[p] +# _tuidchr[p] +# _tuidcnt[p] +# _tUIDPFX[p] +# _tUIDSFX[p] +# _tUIDEL +# _tUIDCNTH +# _tUIDCNTL +# _tUIDCHRL +# _tUIDCHRH + +# create default class basic `new' and `del' functions + + + +function _tstini() +{ + _ini("uidel:pfx'hstr|lstr'sfx") + _ini("uidel:pfx'hstr|lstr'") + _ini("uidel:'hstr|lstr'sfx") + _ini("uidel:'hstr|lstr'") + _ini("uidel:pfx'hstr'sfx") + _ini("uidel:pfx'hstr'") + _ini("uidel:'hstr'sfx") + _ini("uidel:'hstr'") + _conl() + _conl("########################################################################################") + _conl() + _ini("pfx'hstr|lstr'sfx") + _ini("pfx'hstr|lstr'") + _ini("'hstr|lstr'sfx") + _ini("'hstr|lstr'") + _ini("pfx'hstr'sfx") + _ini("pfx'hstr'") + _ini("'hstr'sfx") + _ini("'hstr'") + _conl() + _conl("########################################################################################") + _conl() + _ini("uidel:pfx'`cntptr'sfx") + _ini("uidel:pfx'`cntptr'") + _ini("uidel:'`cntptr'sfx") + _ini("uidel:'`cntptr'") + _conl() + _conl("########################################################################################") + _conl() + _ini("pfx'`cntptr'sfx") + _ini("pfx'`cntptr'") + _ini("'`cntptr'sfx") + _ini("'`cntptr'") + _conl() + _conl("########################################################################################") + _conl() + _ini("uidel:pfx'^chrptr'sfx") + _ini("uidel:pfx'^chrptr'") + _ini("uidel:'^chrptr'sfx") + _ini("uidel:'^chrptr'") + _conl() + _conl("########################################################################################") + _conl() + _ini("pfx'^chrptr'sfx") + _ini("pfx'^chrptr'") + _ini("'^chrptr'sfx") + _ini("'^chrptr'") + _conl() + _conl("########################################################################################") + _conl() +} + +function _tstv(p, A, r, f) +{ + if (f == "") { + f = "tst_splitstr" + } + @f(_NOP, A, p) + @f(AA0, A, p) + @f(AB0, A, p) + @f(AC0, A, p) + @f("", A, p) + @f("a", A, p) + @f("\264a", A, p) + @f("\264", A, p) + @f("a\264\264\264,ba\264\264\264,", A, p) + @f("\264,", A, p) + @f(",", A, p) + @f("\264a,", A, p) + @f("ab,", A, p) + @f("ab,\264", A, p) + @f("\264a\264,,ba", A, p) + @f(",a,,b\264,c,,\264a,,\264,,,", A, p) +} + +function _typ(p) +{ + return (_t0 = (isarray(p) ? "#" : (p == 0 ? (p == "" ? 0 : (p in _CLASSPTR ? "`" : (p ? 3 : 4))) : (p in _CLASSPTR ? "`" : (p + 0 == p ? 5 : (p ? 3 : 2)))))) +} + +function _typa(p, A) +{ + return (_t0 = (isarray(p) ? "#" : (p == 0 ? (p == "" ? 0 : (p in A ? "`" : (p ? 3 : 4))) : (p in A ? "`" : (p + 0 == p ? 5 : (p ? 3 : 2)))))) +} + +#_____________________________________________________ +# _tframe0(hndstr,ptr) +# +# +# IN: +# MOD: +# OUT: +# RETURN: +# +# handler string: +# Handler-string divides to words. Word splitter is char ";" +# +# Note that handler-string processed left to right. This mean that next word(more rightly) will overwrite fields implemented before(leftmost). +# Note that if word-string contains more than one rexp-field then only last rexp-field(most rightly) will be applied. +#_______________________________________________ +# TO DESIGN: +# +# 0-4: complete design of tlink handler call +# 1-4: add new tlink handler call +# 1-4: add new run fn (changed rexp to different for each type: see _tframe0) +# +# hndstr: +# may be add rexp for each type of handler and also total rexp for all ??? ADDED (test) +# may be add separator char ";" ??? ADDED (test) +#_______________________________________________________________________ +function _tzend(a, b) +{ + ##################################################### + if (b == 0 && b == "") { + return (_TEND[_TEND[_ARRLEN]] = a) + } else { + return (_TEND[_TEND[_ARRLEN] + a] = b) + } +} + +function _uidcyc(p, i) +{ + _dumpuidgen(p) + for (i = 1; i < 64 * 8 * 6 - 1; i++) { + _conl(i ":" _var(_getuid(p))) + } + _dumpuidgen(p) +} + +function _une(t) +{ + return gensub(/\xB4(.)/, "\\1", "G", t) +} + +#___________________________________________________________________________________ +function _unformatrexp(t) +{ + _formatstrq0 = split(t, _FORMATSTRA, /(\\[0-9]{1,3})|(\\x[[:xdigit:]]+)|(\\.)/, _FORMATSTRB) + _formatstrs0 = "" + for (t = 1; t < _formatstrq0; t++) { + _formatstrs0 = _formatstrs0 _FORMATSTRA[t] ((_FORMATSTRB[t] in _QESCHR ? _QESCREXP[_FORMATSTRB[t]] : _QESCREXP[toupper(substr(_FORMATSTRB[t], length(_FORMATSTRB[t]) - 1))])) + } + return (_formatstrs0 _FORMATSTRA[t]) +} + +#___________________________________________________________ +function _unformatrexp_init(i, a) +{ + _formatstrs0 = "\\^$.[]|()*+?{}-sSwW<>yB`'" + delete _FORMATSTRB + for (i = 0; i < 256; i++) { + _QESCREXP["\\" _CHR[i]] = (index(_formatstrs0, _CHR[i]) ? "\\" _CHR[i] : _CHR[i]) + } + for (i = 0; i < 256; i++) { + a = (index(_formatstrs0, _CHR[i]) ? "\\" : "") + _QESCREXP[sprintf("%.2X", i)] = a _CHR[i] + _QESCREXP["\\" sprintf("%.3o", i)] = a _CHR[i] + if (i < 8) { + _QESCREXP["\\" sprintf("%.1o", i)] = a _CHR[i] + } + if (i < 64) { + _QESCREXP["\\" sprintf("%.2o", i)] = a _CHR[i] + } + if (i < 16) { + _QESCREXP["\\x" sprintf("%.1X", i)] = _QESCREXP["\\x" sprintf("%.1x", i)] = a _CHR[i] + } + } + patsplit("a" 7 "b" 8 "f" 12 "n" 10 "r" 13 "t" 9 "v" 11, _FORMATSTRA, /[^0-9]/, _FORMATSTRB) + for (i in _FORMATSTRA) { + _QESCREXP["\\" _FORMATSTRA[i]] = _CHR[_FORMATSTRB[i] + 0] + } +} + +#___________________________________________________________________________________ +function _unformatstr(t) +{ + _formatstrq0 = split(t, _FORMATSTRA, /(\\[0-9]{1,3})|(\\x[[:xdigit:]]+)|(\\.)/, _FORMATSTRB) + _formatstrs0 = "" + for (t = 1; t < _formatstrq0; t++) { + _formatstrs0 = _formatstrs0 _FORMATSTRA[t] ((_FORMATSTRB[t] in _QESCHR ? _QESCHR[_FORMATSTRB[t]] : _QESCHR[toupper(substr(_FORMATSTRB[t], length(_FORMATSTRB[t]) - 1))])) + } + return (_formatstrs0 _FORMATSTRA[t]) +} + +#___________________________________________________________ +function _unformatstr_init(i) +{ + for (i = 0; i < 256; i++) { + _QESCHR["\\" _CHR[i]] = _CHR[i] + } + for (i = 0; i < 256; i++) { + _QESCHR[sprintf("%.2X", i)] = _CHR[i] + _QESCHR["\\" sprintf("%.3o", i)] = _CHR[i] + if (i < 8) { + _QESCHR["\\" sprintf("%.1o", i)] = _CHR[i] + } + if (i < 64) { + _QESCHR["\\" sprintf("%.2o", i)] = _CHR[i] + } + if (i < 16) { + _QESCHR["\\x" sprintf("%.1X", i)] = _QESCHR["\\x" sprintf("%.1x", i)] = _CHR[i] + } + } + i = "a" 7 "b" 8 "f" 12 "n" 10 "r" 13 "t" 9 "v" 11 + patsplit(i, _FORMATSTRA, /[^0-9]/, _FORMATSTRB) + for (i in _FORMATSTRA) { + _QESCHR["\\" _FORMATSTRA[i]] = _CHR[_FORMATSTRB[i] + 0] + } +} + +#_____________________________________________________________________________ +function _uninit_del(A, i, p0) +{ + _del(i) +} + +#################################################################################### +# PUBLIC: +#_____________________________________________________________________________ +# var _SYS_STDOUT - (by default = "/dev/stdout") standart output pipe filename +# var _SYS_STDERR - (by default = "/dev/stderr") standart error output pipe filename +# var _SYS_STDCON - (by default = "CON") standart console output device +#_____________________________________________________________________________ +# var _CHR["CR"] - return cursor to the position 0 without newline(normally ="\x0D") +# var _CHR["EOL"] - return cursor to the position 0 & newline (MS:="\x0D\x0A" / UX:="\x0D") +# var _CON_WIDTH - console width(columns number) +#_____________________________________________________________________________ +# fn _cmd(c) - execute shell command c and return output +# fn _err - output string w\o any addition into _SYS_STDERR device +# fn _errnl - output string with addition _CHR["EOL"] at the end of the string into _SYS_STDERR device +# fn _out - output string w\o any addition into _SYS_STDOUT device +# fn _outnl - output string with addition _CHR["EOL"] at the end of the string into _SYS_STDOUT device +#_____________________________________________________________________________ +# fn _con(text[,tabspace]) +# fn _conl(text[,tabspace]) +# fn _conline(text[,tabspace]) +# fn _constat(status[,tabspace]) +# fn _constatpush([status[,tabspace]]) +# fn _constatpop() +#_______________________________________________________________________ +# var _constatstr +#################################################################################### + + +function _unstr(t) +{ + return gensub(/\\(.)/, "\\1", "G", t) +} + +#_________________________________________________________________ +function _untmp(f, a) +{ + ############################################# + if (f = filepath(f)) { + if (match(f, /\\$/)) { + _deletepfx(_FILEIO_RDTMP, a = toupper(f)) + _deletepfx(_FILEIO_RDNETMP, a) } else { - if (p == 0) { - return v - } - if (v) { - return _texclude(v) - } - return v + delete _FILEIO_RDNETMP[toupper(f)] } + return f } - - function _wFCHLD(p, v, a) - { - if (p) { - if (v) { - if (p == v) { + return "" +} + +#_____________________________________________________________________________ +function _val(v, t) +{ + if (isarray(v)) { + return (_dumparr(v) _ln(t)) + } + if (v == 0 && v == "") { + return (_ln("- (ERRNO=" ERRNO ")") _ln(t)) + } + return (_ln(v "'") _ln(t)) +} + +#_____________________________________________________________________________ +function _val0(v) +{ + if (isarray(v)) { + return _dumparr(v) + } + if (v == 0 && v == "") { + return "-" + } + return ("\"" v "\"") +} + +#_____________________________________________________________________________ +function _var(v, t) +{ + if (isarray(v)) { + return (_dumparr(v) _ln(t)) + } + if (v == 0 && v == "") { + return (_ln("- (ERRNO=" ERRNO ")") _ln(t)) + } + return (_ln(v "'") _ln(t)) +} + +#_______________________________________________________________________ +function _verb(t, d, A) +{ + ################################################## + if (_ERRLOG_VF) { + A["TYPE"] = "VERB" + A["TEXT"] = t + _log(A, d) + } +} + +#_________________________________________________________________ +function _wFBRO(p, v, a) +{ + ########################################### + if (p) { + if (v) { + for (a = p; a in _tPARENT; ) { + if ((a = _tPARENT[a]) == v) { return v } - for (a = p; a in _tPARENT; ) { - if ((a = _tPARENT[a]) == v) { - return v - } - } + } + ######################## v is parentesis of p + if (p in _tPARENT) { + p = _tPARENT[p] if (v in _tNEXT) { if (v in _tPREV) { _tPREV[_tNEXT[a] = _tNEXT[v]] = a = _tPREV[v] @@ -5925,11 +7271,8 @@ delete _tPREV[_tNEXT[v]] } } - if (p in _tFCHLD) { - ++_tQCHLD[p] - return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[_tPARENT[v] = p]] = v) - } - delete _tNEXT[v] + ++_tQCHLD[p] + return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[_tPARENT[v] = p]] = v) } else { if (v in _tPREV) { if (v in _tPARENT) { @@ -5953,167 +7296,184 @@ delete _tQCHLD[a] } } - if (p in _tFCHLD) { - ++_tQCHLD[p] - return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[_tPARENT[v] = p]] = v) - } + ++_tQCHLD[p] + return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[_tPARENT[v] = p]] = v) } - _tQCHLD[p] = 1 - return (_tFCHLD[_tPARENT[v] = p] = _tLCHLD[p] = v) } else { - if (v == 0) { - if (p in _tFCHLD) { - v = _tFCHLD[p] - delete _tFCHLD[p] - delete _tLCHLD[p] - delete _tQCHLD[p] - do { - delete _tPARENT[v] - } while (v in _tNEXT && (v = _tNEXT[v])) + while (p in _tPREV) { + p = _tPREV[p] + } + if (v in _tPREV) { + if (v in _tPARENT) { + --_tQCHLD[a = _tPARENT[v]] + delete _tPARENT[v] + if (v in _tNEXT) { + _tNEXT[_tPREV[a] = _tPREV[v]] = a = _tNEXT[v] + } else { + delete _tNEXT[_tLCHLD[a] = _tPREV[v]] + } + } else { + if (v in _tNEXT) { + _tNEXT[_tPREV[a] = _tPREV[v]] = a = _tNEXT[v] + } else { + delete _tNEXT[_tPREV[v]] + } + } + delete _tPREV[v] + } else { + if (p == v) { + return v + } + if (v in _tPARENT) { + if (v in _tNEXT) { + delete _tPREV[_tFCHLD[a = _tPARENT[v]] = _tNEXT[v]] + --_tQCHLD[a] + } else { + delete _tLCHLD[a = _tPARENT[v]] + delete _tFCHLD[a] + delete _tQCHLD[a] + } + delete _tPARENT[v] + } else { + if (v in _tNEXT) { + delete _tPREV[_tNEXT[v]] + } } } - return v + return (_tPREV[_tNEXT[v] = p] = v) } } else { - if (p == 0) { + 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 } +} - function _wLBRO(p, v, a) - { - if (p) { - if (v) { - for (a = p; a in _tPARENT; ) { - if ((a = _tPARENT[a]) == v) { - return v - } +#_________________________________________________________________ +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 } - if (p in _tPARENT) { - p = _tPARENT[p] - if (v in _tPREV) { - if (v in _tNEXT) { - _tNEXT[_tPREV[a] = _tPREV[v]] = a = _tNEXT[v] - delete _tNEXT[v] - if (v in _tPARENT) { - if (p == (a = _tPARENT[v])) { - return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[p]] = v) - } - --_tQCHLD[a] - } - } else { - if (v in _tPARENT) { - if (p == (a = _tPARENT[v])) { - return v - } - delete _tNEXT[_tLCHLD[a] = _tPREV[v]] - --_tQCHLD[a] - } else { - delete _tNEXT[_tPREV[v]] - } - } - ++_tQCHLD[p] - return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[_tPARENT[v] = p]] = v) - } else { - if (v in _tNEXT) { - if (v in _tPARENT) { - delete _tPREV[_tFCHLD[a = _tPARENT[v]] = _tNEXT[v]] - if (p == a) { - delete _tNEXT[v] - return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[p]] = v) - } - --_tQCHLD[a] - } else { - delete _tPREV[_tNEXT[v]] - } - delete _tNEXT[v] - } else { - if (v in _tPARENT) { - if (p == (a = _tPARENT[v])) { - return v - } - delete _tLCHLD[a] - delete _tFCHLD[a] - delete _tQCHLD[a] - } + } + ######################## v is parentesis of p + if (v in _tNEXT) { + if (v in _tPREV) { + _tPREV[_tNEXT[a] = _tNEXT[v]] = a = _tPREV[v] + delete _tPREV[v] + if (v in _tPARENT) { + if (p == (a = _tPARENT[v])) { + return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[p]] = v) } - ++_tQCHLD[p] - return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[_tPARENT[v] = p]] = v) + --_tQCHLD[a] } } else { - while (p in _tNEXT) { - p = _tNEXT[p] + if (v in _tPARENT) { + if (p == (a = _tPARENT[v])) { + return v + } + delete _tPREV[_tFCHLD[a] = _tNEXT[v]] + --_tQCHLD[a] + } else { + delete _tPREV[_tNEXT[v]] } - if (v in _tNEXT) { - if (v in _tPARENT) { - --_tQCHLD[a = _tPARENT[v]] - delete _tPARENT[v] - if (v in _tPREV) { - _tPREV[_tNEXT[a] = _tNEXT[v]] = a = _tPREV[v] - } else { - delete _tPREV[_tFCHLD[a] = _tNEXT[v]] - } - } else { - if (v in _tPREV) { - _tPREV[_tNEXT[a] = _tNEXT[v]] = a = _tPREV[v] - } else { - delete _tPREV[_tNEXT[v]] - } + } + if (p in _tFCHLD) { + ++_tQCHLD[p] + return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[_tPARENT[v] = p]] = v) + } + delete _tNEXT[v] + } else { + if (v in _tPREV) { + if (v in _tPARENT) { + delete _tNEXT[_tLCHLD[a = _tPARENT[v]] = _tPREV[v]] + if (p == a) { + delete _tPREV[v] + return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[p]] = v) } - delete _tNEXT[v] + --_tQCHLD[a] } else { - if (p == v) { + delete _tNEXT[_tPREV[v]] + } + delete _tPREV[v] + } else { + if (v in _tPARENT) { + if (p == (a = _tPARENT[v])) { return v } - if (v in _tPARENT) { - if (v in _tPREV) { - delete _tNEXT[_tLCHLD[a = _tPARENT[v]] = _tPREV[v]] - --_tQCHLD[a] - } else { - delete _tFCHLD[a = _tPARENT[v]] - delete _tLCHLD[a] - delete _tQCHLD[a] - } - delete _tPARENT[v] - } else { - if (v in _tPREV) { - delete _tNEXT[_tPREV[v]] - } - } + delete _tFCHLD[a] + delete _tLCHLD[a] + delete _tQCHLD[a] } - return (_tNEXT[_tPREV[v] = p] = v) } - } else { - if (v == 0) { - return v + if (p in _tFCHLD) { + ++_tQCHLD[p] + return (_tFCHLD[p] = _tPREV[_tNEXT[v] = _tFCHLD[_tPARENT[v] = p]] = v) } - return v } + _tQCHLD[p] = 1 + return (_tFCHLD[_tPARENT[v] = p] = _tLCHLD[p] = v) } else { - if (p == 0) { - return v - } - if (v) { - return _texclude(v) + if (v == 0) { + if (p in _tFCHLD) { + ######################## p=ptr, v=0 > delete all chld + v = _tFCHLD[p] + delete _tFCHLD[p] + delete _tLCHLD[p] + delete _tQCHLD[p] + do { + delete _tPARENT[v] + } while (v in _tNEXT && (v = _tNEXT[v])) + } } return v } + } else { + ######################## p=ptr, v="" > ignore action + if (p == 0) { + return v + } + ######################## p=0 + return v } +} - function _wLCHLD(p, v, a) - { - if (p) { - if (v) { - if (p == v) { +#_________________________________________________________________ +function _wLBRO(p, v, a) +{ + ########################################### + if (p) { + if (v) { + for (a = p; a in _tPARENT; ) { + if ((a = _tPARENT[a]) == v) { return v } - for (a = p; a in _tPARENT; ) { - if ((a = _tPARENT[a]) == v) { - return v - } - } + } + ######################## v is parentesis of p + if (p in _tPARENT) { + p = _tPARENT[p] if (v in _tPREV) { if (v in _tNEXT) { _tNEXT[_tPREV[a] = _tPREV[v]] = a = _tNEXT[v] @@ -6135,11 +7495,8 @@ delete _tNEXT[_tPREV[v]] } } - if (p in _tLCHLD) { - ++_tQCHLD[p] - return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[_tPARENT[v] = p]] = v) - } - delete _tPREV[v] + ++_tQCHLD[p] + return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[_tPARENT[v] = p]] = v) } else { if (v in _tNEXT) { if (v in _tPARENT) { @@ -6163,596 +7520,802 @@ delete _tQCHLD[a] } } - if (p in _tLCHLD) { - ++_tQCHLD[p] - return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[_tPARENT[v] = p]] = v) - } + ++_tQCHLD[p] + return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[_tPARENT[v] = p]] = v) } - _tQCHLD[p] = 1 - return (_tLCHLD[_tPARENT[v] = p] = _tFCHLD[p] = v) } else { - if (v == 0) { - if (p in _tFCHLD) { - v = _tFCHLD[p] - delete _tFCHLD[p] - delete _tLCHLD[p] - delete _tQCHLD[p] - do { - delete _tPARENT[v] - } while (v in _tNEXT && (v = _tNEXT[v])) + while (p in _tNEXT) { + p = _tNEXT[p] + } + if (v in _tNEXT) { + if (v in _tPARENT) { + --_tQCHLD[a = _tPARENT[v]] + delete _tPARENT[v] + if (v in _tPREV) { + _tPREV[_tNEXT[a] = _tNEXT[v]] = a = _tPREV[v] + } else { + delete _tPREV[_tFCHLD[a] = _tNEXT[v]] + } + } else { + if (v in _tPREV) { + _tPREV[_tNEXT[a] = _tNEXT[v]] = a = _tPREV[v] + } else { + delete _tPREV[_tNEXT[v]] + } + } + delete _tNEXT[v] + } else { + if (p == v) { + return v + } + if (v in _tPARENT) { + if (v in _tPREV) { + delete _tNEXT[_tLCHLD[a = _tPARENT[v]] = _tPREV[v]] + --_tQCHLD[a] + } else { + delete _tFCHLD[a = _tPARENT[v]] + delete _tLCHLD[a] + delete _tQCHLD[a] + } + delete _tPARENT[v] + } else { + if (v in _tPREV) { + delete _tNEXT[_tPREV[v]] + } } } - return v + return (_tNEXT[_tPREV[v] = p] = v) } } else { - if (p == 0) { + 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 } +} - function _wLINK(p, v) - { - return (_tLINK[p] = v) - } - - function _wNEXT(p, v, a, b) - { - if (p) { - if (v) { - if (p == v) { +#_________________________________________________________________ +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 } - for (a = p; a in _tPARENT; ) { - if ((a = _tPARENT[a]) == v) { - return v - } - } - if (v in _tPREV) { - if (p == (a = _tPREV[v])) { - return v - } - if (v in _tNEXT) { - _tPREV[_tNEXT[a] = _tNEXT[v]] = a - if (v in _tPARENT) { - --_tQCHLD[_tPARENT[v]] - } - } else { - delete _tNEXT[a] - if (v in _tPARENT) { - _tLCHLD[b = _tPARENT[v]] = a - --_tQCHLD[b] + } + ######################## v is parentesis of p + if (v in _tPREV) { + if (v in _tNEXT) { + _tNEXT[_tPREV[a] = _tPREV[v]] = a = _tNEXT[v] + delete _tNEXT[v] + if (v in _tPARENT) { + if (p == (a = _tPARENT[v])) { + return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[p]] = v) } + --_tQCHLD[a] } } else { - if (v in _tNEXT) { - if (v in _tPARENT) { - delete _tPREV[_tFCHLD[a = _tPARENT[v]] = _tNEXT[v]] - --_tQCHLD[a] - } else { - delete _tPREV[_tNEXT[v]] + if (v in _tPARENT) { + if (p == (a = _tPARENT[v])) { + return v } + delete _tNEXT[_tLCHLD[a] = _tPREV[v]] + --_tQCHLD[a] } else { - if (v in _tPARENT) { - delete _tFCHLD[a = _tPARENT[v]] - delete _tLCHLD[a] - delete _tQCHLD[a] - } + delete _tNEXT[_tPREV[v]] } } - if (p in _tNEXT) { - _tPREV[_tNEXT[v] = _tNEXT[p]] = v - if (p in _tPARENT) { - ++_tQCHLD[_tPARENT[v] = _tPARENT[p]] + if (p in _tLCHLD) { + ++_tQCHLD[p] + return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[_tPARENT[v] = p]] = v) + } + delete _tPREV[v] + } else { + if (v in _tNEXT) { + if (v in _tPARENT) { + delete _tPREV[_tFCHLD[a = _tPARENT[v]] = _tNEXT[v]] + if (p == a) { + delete _tNEXT[v] + return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[p]] = v) + } + --_tQCHLD[a] } else { - delete _tPARENT[v] + delete _tPREV[_tNEXT[v]] } - } else { delete _tNEXT[v] - if (p in _tPARENT) { - ++_tQCHLD[_tPARENT[_tLCHLD[a] = v] = a = _tPARENT[p]] - } else { - delete _tPARENT[v] + } else { + if (v in _tPARENT) { + if (p == (a = _tPARENT[v])) { + return v + } + delete _tLCHLD[a] + delete _tFCHLD[a] + delete _tQCHLD[a] } } - return (_tNEXT[_tPREV[v] = p] = v) - } else { - if (v == 0) { - return v + if (p in _tLCHLD) { + ++_tQCHLD[p] + return (_tLCHLD[p] = _tNEXT[_tPREV[v] = _tLCHLD[_tPARENT[v] = p]] = v) } - return v } + _tQCHLD[p] = 1 + return (_tLCHLD[_tPARENT[v] = p] = _tFCHLD[p] = v) } else { - if (p == 0) { - return v - } - if (v) { - return _texclude(v) + if (v == 0) { + if (p in _tFCHLD) { + ######################## p=ptr, v=0 > delete all chld + v = _tFCHLD[p] + delete _tFCHLD[p] + delete _tLCHLD[p] + delete _tQCHLD[p] + do { + delete _tPARENT[v] + } while (v in _tNEXT && (v = _tNEXT[v])) + } } return v } - } - - function _wPARENT(p, v) - { + } else { + ######################## p=ptr, v="" > ignore action + if (p == 0) { + return v + } + ######################## p=0 return v } - - function _wPREV(p, v, a, b) - { - if (p) { - if (v) { - if (p == v) { +} + +#_________________________________________________________________ +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 } - 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 } if (v in _tNEXT) { - if (p == (a = _tNEXT[v])) { - return v - } - if (v in _tPREV) { - _tNEXT[_tPREV[a] = _tPREV[v]] = a - if (v in _tPARENT) { - --_tQCHLD[_tPARENT[v]] - } - } else { - delete _tPREV[a] - if (v in _tPARENT) { - _tFCHLD[b = _tPARENT[v]] = a - --_tQCHLD[b] - } + _tPREV[_tNEXT[a] = _tNEXT[v]] = a + if (v in _tPARENT) { + --_tQCHLD[_tPARENT[v]] } } else { - if (v in _tPREV) { - if (v in _tPARENT) { - delete _tNEXT[_tLCHLD[a = _tPARENT[v]] = _tPREV[v]] - --_tQCHLD[a] - } else { - delete _tNEXT[_tPREV[v]] - } - } else { - if (v in _tPARENT) { - delete _tLCHLD[a = _tPARENT[v]] - delete _tFCHLD[a] - delete _tQCHLD[a] - } + delete _tNEXT[a] + if (v in _tPARENT) { + _tLCHLD[b = _tPARENT[v]] = a + --_tQCHLD[b] } } - if (p in _tPREV) { - _tNEXT[_tPREV[v] = _tPREV[p]] = v - if (p in _tPARENT) { - ++_tQCHLD[_tPARENT[v] = _tPARENT[p]] + } else { + if (v in _tNEXT) { + if (v in _tPARENT) { + delete _tPREV[_tFCHLD[a = _tPARENT[v]] = _tNEXT[v]] + --_tQCHLD[a] } else { - delete _tPARENT[v] + delete _tPREV[_tNEXT[v]] } } else { - delete _tPREV[v] - if (p in _tPARENT) { - ++_tQCHLD[_tPARENT[_tFCHLD[a] = v] = a = _tPARENT[p]] - } else { - delete _tPARENT[v] + if (v in _tPARENT) { + delete _tFCHLD[a = _tPARENT[v]] + delete _tLCHLD[a] + delete _tQCHLD[a] } } - return (_tPREV[_tNEXT[v] = p] = v) + } + if (p in _tNEXT) { + _tPREV[_tNEXT[v] = _tNEXT[p]] = v + if (p in _tPARENT) { + ++_tQCHLD[_tPARENT[v] = _tPARENT[p]] + } else { + delete _tPARENT[v] + } } else { - if (v == 0) { - return v + delete _tNEXT[v] + if (p in _tPARENT) { + ++_tQCHLD[_tPARENT[_tLCHLD[a] = v] = a = _tPARENT[p]] + } else { + delete _tPARENT[v] } - return v } + return (_tNEXT[_tPREV[v] = p] = v) } else { - if (p == 0) { + if (v == 0) { return v } - if (v) { - return _texclude(v) - } + ######################## p=ptr, v=0 return v } - } - - function _wQBRO(p, v) - { + } else { + ######################## p=ptr, v="" + if (p == 0) { + return v + } + ######################## p=0 + if (v) { + return _texclude(v) + } + ######################## p="", v=ptr - exclude v return v } - - function _wQCHLD(p, v) - { - if (p) { - if (v) { +} + +#_________________________________________________________________ +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 + } + if (v in _tPREV) { + _tNEXT[_tPREV[a] = _tPREV[v]] = a + if (v in _tPARENT) { + --_tQCHLD[_tPARENT[v]] + } + } else { + delete _tPREV[a] + if (v in _tPARENT) { + _tFCHLD[b = _tPARENT[v]] = a + --_tQCHLD[b] + } + } } else { - if (v == 0) { - if (p in _tFCHLD) { - v = _tFCHLD[p] - delete _tFCHLD[p] - delete _tLCHLD[p] - delete _tQCHLD[p] - do { - delete _tPARENT[v] - } while (v in _tNEXT && (v = _tNEXT[v])) + if (v in _tPREV) { + if (v in _tPARENT) { + delete _tNEXT[_tLCHLD[a = _tPARENT[v]] = _tPREV[v]] + --_tQCHLD[a] + } else { + delete _tNEXT[_tPREV[v]] + } + } else { + if (v in _tPARENT) { + delete _tLCHLD[a = _tPARENT[v]] + delete _tFCHLD[a] + delete _tQCHLD[a] } } - return v } + if (p in _tPREV) { + _tNEXT[_tPREV[v] = _tPREV[p]] = v + if (p in _tPARENT) { + ++_tQCHLD[_tPARENT[v] = _tPARENT[p]] + } else { + delete _tPARENT[v] + } + } else { + delete _tPREV[v] + if (p in _tPARENT) { + ++_tQCHLD[_tPARENT[_tFCHLD[a] = v] = a = _tPARENT[p]] + } else { + delete _tPARENT[v] + } + } + return (_tPREV[_tNEXT[v] = p] = v) } else { - if (p == 0) { + if (v == 0) { return v } + ######################## p=ptr, v=0 return v } - } - - function _warning(t, d, A) - { - if (_ERRLOG_WF) { - A["TYPE"] = "WARNING" - A["TEXT"] = t - _log(A, d) + } else { + ######################## p=ptr, v="" + if (p == 0) { + return v } + ######################## p=0 + if (v) { + return _texclude(v) + } + ######################## p="", v=ptr - exclude v + return v } - - function _wfilerdnehnd(f, t) - { - if ((f = _filerdne(f)) == "") { - return "" +} + +#_________________________________________________________________ +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] + delete _tQCHLD[p] + do { + delete _tPARENT[v] + } while (v in _tNEXT && (v = _tNEXT[v])) + } + } + return v } - if (! ((t = _filerd(f)) in _WFILEROOTDIR)) { - _cmd("md \"" t "\" 2>NUL") - _WFILEROOTDIR[t] + } else { + ######################## p=ptr, v="" > ignore action + if (p == 0) { + return v } - return f + ######################## p=0 + return v } +} - function _wonl(t) - { - wonl = wonl _ln(t) +#_______________________________________________________________________ +function _warning(t, d, A) +{ + ############################################### + if (_ERRLOG_WF) { + A["TYPE"] = "WARNING" + A["TEXT"] = t + _log(A, d) } +} - function _wonline(t) - { - wonl = wonl _ln(substr(" _ " t " _____________________________________________________________________________________________________________________________________", 1, 126)) +#___________________________________________________________ +function _wfilerdnehnd(f, t) +{ + if ((f = _filerdne(f)) == "") { + return "" } - - function _wr_shortcut(f, S) - { - if (_shrtcutf0 = _filepath(f)) { - ERRNO = "" - _shrtcuta0 = _shortcut_fpath " /A:C /F:\"" _shrtcutf0 "\" 2>&1" - for (f in _SHORTCUTWSTRUC) { - if (f in S) { - _shrtcuta0 = _shrtcuta0 " " _SHORTCUTWSTRUC[f] "\"" (gensub(/(\\?)$/, "\\1\\1", 1, S[f])) "\"" - } - } - if (_shortcut_nerr(_cmd(_shrtcuta0), _shrtcutf0)) { - return - } - } - return ((ERRNO ? ERRNO = "write shortcut: " ERRNO : _NOP)) + if (! ((t = _filerd(f)) in _WFILEROOTDIR)) { + _cmd("md \"" t "\" 2>NUL") + _WFILEROOTDIR[t] } + return f +} - function _wrfile(f, d, a, b) - { - if ((f = _wfilerdnehnd(f)) == "" || _filene(f) == "") { - ERRNO = "Filename error" - return - } - a = BINMODE - BINMODE = "rw" - b = ORS - ORS = "" - ERRNO = "" - print(d) > f - if (ERRNO) { - return "" - } - close(f) - BINMODE = a - ORS = b - if (ERRNO) { - return "" - } - return f - } +function _wonl(t) +{ + wonl = wonl _ln(t) +} - function _wrfile1(f, d, a, b) - { - if ((f = _wfilerdnehnd(f)) == "" || _filene(f) == "") { - ERRNO = "Filename error" - return - } - a = BINMODE - BINMODE = "rw" - b = ORS - ORS = "" +function _wonline(t) +{ + wonl = wonl _ln(substr(" _ " t " _____________________________________________________________________________________________________________________________________", 1, 126)) +} + +#___________________________________________________________ +function _wr_shortcut(f, S) +{ + if (_shrtcutf0 = _filepath(f)) { ERRNO = "" - print(d) > f - if (ERRNO) { - return "" + _shrtcuta0 = _shortcut_fpath " /A:C /F:\"" _shrtcutf0 "\" 2>&1" + for (f in _SHORTCUTWSTRUC) { + if (f in S) { + _shrtcuta0 = _shrtcuta0 " " _SHORTCUTWSTRUC[f] "\"" (gensub(/(\\?)$/, "\\1\\1", 1, S[f])) "\"" + } } - close(f) - BINMODE = a - ORS = b - if (ERRNO) { - return "" + if (_shortcut_nerr(_cmd(_shrtcuta0), _shrtcutf0)) { + return } - return d } + return ((ERRNO ? ERRNO = "write shortcut: " ERRNO : _NOP)) +} - function _yexport(p) - { - return _tframe("_yexport_i0", p) +#_________________________________________________________________ +function _wrfile(f, d, a, b) +{ + ######################################### + if ((f = _wfilerdnehnd(f)) == "" || _filene(f) == "") { + ERRNO = "Filename error" + return } - - function _yexport_i0(p, p0, p1, p2) - { - if (p in _tLOG) { - return ("_ERRLOG: " _Zexparr(_tLOG[p]) "\n") - } - if (p in _tSTR) { - p = _tSTR[p] - gsub(/\x1B/, "\033;", p) - gsub(/\x0A/, "\033:", p) - return (p "\n") - } + a = BINMODE + BINMODE = "rw" + b = ORS + ORS = "" + ERRNO = "" + print(d) > f + if (ERRNO) { + return "" } - - function cmp_str_idx(i1, v1, i2, v2) - { - return ((i1 < i2 ? -1 : 1)) + close(f) + BINMODE = a + ORS = b + if (ERRNO) { + return "" } + return f +} - function filedi(f, d) - { - if ((f = filerdnehndi(f)) == "") { - return _FILEIO_D - } - if (f in _FILEDIRFL) { - return _FILEDIR[f] - } - if (f in _FILEROOT) { - if (d = filegetdrvdir(_FILEROOT[f])) { - _FILEDIRFL[f] - } - return (_FILEDIR[f] = d _FILEDIR[f]) - } - if ((_FILEIO_RD, f) in _FILEDIR) { - return _FILEDIR[_FILEIO_RD, f] - } - return (_FILEDIR[_FILEIO_RD, f] = _FILEIO_D _FILEDIR[f]) +#___________________________________________________________ +function _wrfile1(f, d, a, b) +{ + ################################## + if ((f = _wfilerdnehnd(f)) == "" || _filene(f) == "") { + ERRNO = "Filename error" + return } - - function filegetdrvdir(t, r) - { - if (t in _FILEDRV) { - return _FILEDRV[t] - } - if (match(r = _cmd("cd " t " 2>NUL"), /[^\x00-\x1F]+/)) { - r = gensub(/[ \t]*([\\\$\:])[ \t]*/, "\\1", "G", substr(r, RSTART, RLENGTH)) - gsub(/(^[ \t]*)|([ \t]*$)/, "", r) - if (match(r, /\:(.*)/)) { - return (_FILEDRV[tolower(t)] = _FILEDRV[toupper(t)] = substr(r, RSTART + 1) ((r ~ /\\$/ ? "" : "\\"))) - } - } + a = BINMODE + BINMODE = "rw" + b = ORS + ORS = "" + ERRNO = "" + print(d) > f + if (ERRNO) { return "" } - - function filegetrootdir(f, dd, d) - { - if (f in _FILEDIRFL) { - if (f in _FILEROOT) { - return (_FILEROOT[f] _FILEDIR[f]) - } - if ((dd = (dd ? dd : _FILEIO_RD), f) in _FILEROOT) { - return (_FILEROOT[dd, f] _FILEDIR[f]) - } - return ((_FILEROOT[dd, f] = fileri(dd)) _FILEDIR[f]) - } + close(f) + BINMODE = a + ORS = b + if (ERRNO) { + return "" + } + return d +} + +#_______________________________________________________________________ +function _yexport(p) +{ + ##################################################### + return _tframe("_yexport_i0", p) +} + +#_______________________________________________________________________ +function _yexport_i0(p, p0, p1, p2) +{ + if (p in _tLOG) { + return ("_ERRLOG: " _Zexparr(_tLOG[p]) "\n") + } + if (p in _tSTR) { + p = _tSTR[p] + gsub(/\x1B/, "\033;", p) + gsub(/\x0A/, "\033:", p) + return (p "\n") + } +} + +#_________________________________________________________________ +function cmp_str_idx(i1, v1, i2, v2) +{ + ############################## + return ((i1 < i2 ? -1 : 1)) +} + +#___________________________________________________________ +function filedi(f, d) +{ + if ((f = filerdnehndi(f)) == "") { + return _FILEIO_D + } + if (f in _FILEDIRFL) { + return _FILEDIR[f] + } + if (f in _FILEROOT) { + if (d = filegetdrvdir(_FILEROOT[f])) { + _FILEDIRFL[f] + } + return (_FILEDIR[f] = d _FILEDIR[f]) + } + if ((_FILEIO_RD, f) in _FILEDIR) { + return _FILEDIR[_FILEIO_RD, f] + } + return (_FILEDIR[_FILEIO_RD, f] = _FILEIO_D _FILEDIR[f]) +} + +#___________________________________________________________ +function filegetdrvdir(t, r) +{ + if (t in _FILEDRV) { + return _FILEDRV[t] + } + if (match(r = _cmd("cd " t " 2>NUL"), /[^\x00-\x1F]+/)) { + r = gensub(/[ \t]*([\\\$\:])[ \t]*/, "\\1", "G", substr(r, RSTART, RLENGTH)) + gsub(/(^[ \t]*)|([ \t]*$)/, "", r) + if (match(r, /\:(.*)/)) { + return (_FILEDRV[tolower(t)] = _FILEDRV[toupper(t)] = substr(r, RSTART + 1) ((r ~ /\\$/ ? "" : "\\"))) + } + } + return "" +} + +#___________________________________________________________ +function filegetrootdir(f, dd, d) +{ + if (f in _FILEDIRFL) { if (f in _FILEROOT) { - if (d = filegetdrvdir(_FILEROOT[f])) { - _FILEDIRFL[f] - return (_FILEROOT[f] (_FILEDIR[f] = d _FILEDIR[f])) - } else { - return (_FILEROOT[f] _FILEDIR[f]) - } + return (_FILEROOT[f] _FILEDIR[f]) } if ((dd = (dd ? dd : _FILEIO_RD), f) in _FILEROOT) { - if ((dd, f) in _FILEDIR) { - return (_FILEROOT[dd, f] _FILEDIR[dd, f]) - } - if ((d = filedi(dd) _FILEDIR[f]) ~ /^\\/) { - return (_FILEROOT[dd, f] (_FILEDIR[dd, f] = d)) - } - return (_FILEROOT[dd, f] d) + return (_FILEROOT[dd, f] _FILEDIR[f]) } + return ((_FILEROOT[dd, f] = fileri(dd)) _FILEDIR[f]) + } + if (f in _FILEROOT) { + if (d = filegetdrvdir(_FILEROOT[f])) { + _FILEDIRFL[f] + return (_FILEROOT[f] (_FILEDIR[f] = d _FILEDIR[f])) + } else { + return (_FILEROOT[f] _FILEDIR[f]) + } + } + if ((dd = (dd ? dd : _FILEIO_RD), f) in _FILEROOT) { if ((dd, f) in _FILEDIR) { - return ((_FILEROOT[dd, f] = fileri(dd)) _FILEDIR[dd, f]) + return (_FILEROOT[dd, f] _FILEDIR[dd, f]) } if ((d = filedi(dd) _FILEDIR[f]) ~ /^\\/) { - return ((_FILEROOT[dd, f] = fileri(dd)) (_FILEDIR[dd, f] = d)) + return (_FILEROOT[dd, f] (_FILEDIR[dd, f] = d)) } - return ((_FILEROOT[dd, f] = fileri(dd)) d) + return (_FILEROOT[dd, f] d) + } + if ((dd, f) in _FILEDIR) { + return ((_FILEROOT[dd, f] = fileri(dd)) _FILEDIR[dd, f]) } + if ((d = filedi(dd) _FILEDIR[f]) ~ /^\\/) { + return ((_FILEROOT[dd, f] = fileri(dd)) (_FILEDIR[dd, f] = d)) + } + return ((_FILEROOT[dd, f] = fileri(dd)) d) +} - function filerdnehndi(st, a, c, r, d, n, A) - { - if (st) { - if ((c = toupper(st)) in _FILECACHE) { - return _FILECACHE[c] - } - if (match(st, /^[ \t]*\\[ \t]*\\/)) { - if (match(substr(st, a = RLENGTH + 1), /^[ \t]*([0-9A-Za-z\-]+)[ \t]*(\\[ \t]*([A-Za-z])[ \t]*\$[ \t]*)?(\\[ \t]*([0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+( +[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+)*[ \t]*\\)*[ \t]*)?(([0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+( +[0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+)*)[ \t]*)?/, A)) { - a = a + RLENGTH - d = ((A[3] ? "\\" A[3] "$" : "")) "\\" A[5] - gsub(/[ \t]*\\[ \t]*/, "\\", d) - if ((st = toupper((r = "\\\\" A[1]) d (n = A[8]))) in _FILECACHE) { - return (_FILECACHE[substr(c, 1, a)] = _FILECACHE[st]) - } - _FILEDIR[c = _FILECACHE[substr(c, 1, a)] = _FILECACHE[st] = ++_file_rootcntr] = d - _FILEDIRFL[c] - _FILEROOT[c] = r - } else { - _filepath_err = "UNC" - return "" - } - } else { - match(st, /^(([ \t]*\.[ \t]*\\[ \t]*)|(([ \t]*([A-Za-z])[ \t]*(\:)[ \t]*)?([ \t]*(\\)[ \t]*)?))([ \t]*(([ \t]*[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+( +[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+)*[ \t]*\\)+)[ \t]*)?([ \t]*([0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+( +[0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+)*)[ \t]*)?/, A) - if (! RLENGTH) { - return "" - } - d = A[8] A[10] +#___________________________________________________________ +function filerdnehndi(st, a, c, r, d, n, A) +{ + if (st) { + if ((c = toupper(st)) in _FILECACHE) { + return _FILECACHE[c] + } + if (match(st, /^[ \t]*\\[ \t]*\\/)) { + if (match(substr(st, a = RLENGTH + 1), /^[ \t]*([0-9A-Za-z\-]+)[ \t]*(\\[ \t]*([A-Za-z])[ \t]*\$[ \t]*)?(\\[ \t]*([0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+( +[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+)*[ \t]*\\)*[ \t]*)?(([0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+( +[0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+)*)[ \t]*)?/, A)) { + a = a + RLENGTH + d = ((A[3] ? "\\" A[3] "$" : "")) "\\" A[5] gsub(/[ \t]*\\[ \t]*/, "\\", d) - if ((st = toupper((r = A[5] A[6]) d (n = A[14]))) in _FILECACHE) { - return (_FILECACHE[substr(c, 1, RLENGTH)] = _FILECACHE[st]) - } - _FILEDIR[c = _FILECACHE[substr(c, 1, RLENGTH)] = _FILECACHE[st] = ++_file_rootcntr] = d - if (A[8]) { - _FILEDIRFL[c] - } - if (r) { - _FILEROOT[c] = r + if ((st = toupper((r = "\\\\" A[1]) d (n = A[8]))) in _FILECACHE) { + return (_FILECACHE[substr(c, 1, a)] = _FILECACHE[st]) } + _FILEDIR[c = _FILECACHE[substr(c, 1, a)] = _FILECACHE[st] = ++_file_rootcntr] = d + _FILEDIRFL[c] + _FILEROOT[c] = r + } else { + _filepath_err = "UNC" + return "" } - if (n) { - if (match(n, /\.[^\.]*$/)) { - _FILEXT[c] = substr(n, RSTART) - _FILENAM[c] = substr(n, 1, RSTART - 1) - } else { - _FILENAM[c] = n - } + } else { + match(st, /^(([ \t]*\.[ \t]*\\[ \t]*)|(([ \t]*([A-Za-z])[ \t]*(\:)[ \t]*)?([ \t]*(\\)[ \t]*)?))([ \t]*(([ \t]*[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+( +[0-9A-Za-z_\!\+\-\[\]\(\)\{\}\~\.]+)*[ \t]*\\)+)[ \t]*)?([ \t]*([0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+( +[0-9A-Za-z_\!\+\.\~\-\[\]\{\}\(\)]+)*)[ \t]*)?/, A) + if (! RLENGTH) { + return "" + } + d = A[8] A[10] + gsub(/[ \t]*\\[ \t]*/, "\\", d) + if ((st = toupper((r = A[5] A[6]) d (n = A[14]))) in _FILECACHE) { + return (_FILECACHE[substr(c, 1, RLENGTH)] = _FILECACHE[st]) + } + _FILEDIR[c = _FILECACHE[substr(c, 1, RLENGTH)] = _FILECACHE[st] = ++_file_rootcntr] = d + if (A[8]) { + _FILEDIRFL[c] + } + if (r) { + _FILEROOT[c] = r } - return c - } - return "" - } - - function fileri(f) - { - if ((f = filerdnehndi(f)) == "") { - return _FILEIO_R - } - if (f in _FILEROOT) { - return _FILEROOT[f] - } - if ((_FILEIO_RD, f) in _FILEROOT) { - return _FILEROOT[_FILEIO_RD, f] } - return (_FILEROOT[_FILEIO_RD, f] = _FILEIO_R) - } - - function hujf(a, b, c) - { - _conl("hujf(" a "," b "," c ")") - } - - function ncmp_str_idx(i1, v1, i2, v2) - { - return ((i1 < i2 ? 1 : -1)) - } - - function test_cfg(p, z, AA0, a) - { - AA0[1] - _fclass = _cfguid(p = _getuid(_classys), _NOP, _NOP, _NOP, _NOP, _classys) - _conl() - _conline() - _conl() - _drawuid(p) - _fclass = _cfguid(p = _getuid(_classys), AA0, AA0, AA0, AA0, _classys) - _conl() - _conline() - _conl() - _drawuid(p) - a = _getuid(z = _fclass = _cfguid(p = _getuid(_classys), p, "<", ">", "ab", "cd")) - _conl("### " a "########") - _conline() - _conl() - _drawuid(p) - a = _getuid(_fclass = _cfguid(p = _getuid(_classys), z, 0, 0, _NOP, z)) - _conl("### " a "########") - _conline() - _conl() - _drawuid(p) - a = _getuid(_fclass = _cfguid(p = _getuid(_classys), z, "^", "$", z, _classys)) - _conl("### " a "########") - _conline() - _conl() - _drawuid(p) - _fclass = _cfguid(p = _getuid(_classys), "oblptr", "pfx", "sfx", "abcd") - _conl() - _conline() - _conl() - _drawuid(p) - _conl("```````````````````" z "'''''''''" ((_isptr(z) ? " ptr" : " not ptr"))) - _drawuid(z) - } - - function test_splitstr(A) - { - AA0[-1] = "huj" - AA0["A"] = "pizda" - AA0[1] = "zhopa" - delete AB0[AB0[""] = ""] - AC0[-1] = "HUJ" - AC0["A"] = "PIZDA" - AC0[1] = "ZHOPA" - _SPLITSTRB0["1"] - wonl = "" - _tstv(0, A, 0, "_tstv") - _conl(wonl) - _wrfile("wonl.out", wonl) - } - - function test_uid(p, i) - { - _fclass = _cfguid(p = _getuid(_classys), p, "pfx", "sfx", "abc") - _conl("_fclass uid: " _getuid(_fclass)) - _drawuid(_fclass) - _conl("_classys uid: " _getuid(_classys)) _drawuid(_classys) - for (i = 1; i < 81; i++) { - _conl(i ": " _getuid(_fclass)) - } - _drawuid(_fclass) - } - - function tst_splitstr(t, A, R, r) - { - delete A - A["not cleared"] - _wonl() - _wonline("_splitstr(" ((isarray(t) ? "ARR" ((length(t) > 0 ? "#" ((t[1] != "zhopa" ? "U" : "l")) : "")) : _val0(t))) ",A" ((isarray(R) ? ", ARR" ((length(R) > 0 ? "#" ((R[1] != "zhopa" ? "U" : "l")) : "")) : ", " _val0(R))) "):") - _wonl(_val0(r = _splitstr(t, A, R))) - _wonl("arrary A:") - _wonl(_dumparr(A)) - return r - } - - function tts(p, uidel, psfx, cnt, chr, p5, p6, p7, im) - { - im = " " - im = ".. .." - _conl("ret: " _qparam(im, p, uidel, psfx, cnt, chr, p5, p6, p7) "'") - _conl("mask: `" _qparamask "'") - } - - function zorr(A, i, r) - { - if (i in A) { - _conl("`" i "' in A") - } else { - _conl("`" i "' not in A") + if (n) { + if (match(n, /\.[^\.]*$/)) { + _FILEXT[c] = substr(n, RSTART) + _FILENAM[c] = substr(n, 1, RSTART - 1) + } else { + _FILENAM[c] = n + } } - r = A[i] == "" && A[i] == 0 - _conl("A[" i "] status is " r) - return - a = a + -a - _conl("``````````````" a "''''''''''''''''") - } - - function zzer() - { + return c } + return "" +} + +#_____________________________________________________ +function fileri(f) +{ + if ((f = filerdnehndi(f)) == "") { + return _FILEIO_R + } + if (f in _FILEROOT) { + return _FILEROOT[f] + } + if ((_FILEIO_RD, f) in _FILEROOT) { + return _FILEROOT[_FILEIO_RD, f] + } + return (_FILEROOT[_FILEIO_RD, f] = _FILEIO_R) +} + +function hujf(a, b, c) +{ + _conl("hujf(" a "," b "," c ")") +} + +#___________________________________________________________ +function ncmp_str_idx(i1, v1, i2, v2) +{ + ####################### + return ((i1 < i2 ? 1 : -1)) +} + +function test_cfg(p, z, AA0, a) +{ + AA0[1] + _fclass = _cfguid(p = _getuid(_classys), _NOP, _NOP, _NOP, _NOP, _classys) + _conl() + _conline() + _conl() + _drawuid(p) + _fclass = _cfguid(p = _getuid(_classys), AA0, AA0, AA0, AA0, _classys) + _conl() + _conline() + _conl() + _drawuid(p) + a = _getuid(z = _fclass = _cfguid(p = _getuid(_classys), p, "<", ">", "ab", "cd")) + _conl("### " a "########") + _conline() + _conl() + _drawuid(p) + a = _getuid(_fclass = _cfguid(p = _getuid(_classys), z, 0, 0, _NOP, z)) + _conl("### " a "########") + _conline() + _conl() + _drawuid(p) + a = _getuid(_fclass = _cfguid(p = _getuid(_classys), z, "^", "$", z, _classys)) + _conl("### " a "########") + _conline() + _conl() + _drawuid(p) + _fclass = _cfguid(p = _getuid(_classys), "oblptr", "pfx", "sfx", "abcd") + _conl() + _conline() + _conl() + _drawuid(p) + _conl("```````````````````" z "'''''''''" ((_isptr(z) ? " ptr" : " not ptr"))) + _drawuid(z) +} + +function test_splitstr(A) +{ + AA0[-1] = "huj" + AA0["A"] = "pizda" + AA0[1] = "zhopa" + delete AB0[AB0[""] = ""] + AC0[-1] = "HUJ" + AC0["A"] = "PIZDA" + AC0[1] = "ZHOPA" + _SPLITSTRB0["1"] + wonl = "" + _tstv(0, A, 0, "_tstv") + _conl(wonl) + _wrfile("wonl.out", wonl) +} + +function test_uid(p, i) +{ + #test_cfg() + #return + + _fclass = _cfguid(p = _getuid(_classys), p, "pfx", "sfx", "abc") + #_fclass=_cfguid(p=_getuid(_classys),_NOP,_NOP,_NOP,"",_classys) + _conl("_fclass uid: " _getuid(_fclass)) + _drawuid(_fclass) + _conl("_classys uid: " _getuid(_classys)) _drawuid(_classys) + for (i = 1; i < 81; i++) { + _conl(i ": " _getuid(_fclass)) + } + _drawuid(_fclass) +} + +function tst_splitstr(t, A, R, r) +{ + delete A + A["not cleared"] + _wonl() + _wonline("_splitstr(" ((isarray(t) ? "ARR" ((length(t) > 0 ? "#" ((t[1] != "zhopa" ? "U" : "l")) : "")) : _val0(t))) ",A" ((isarray(R) ? ", ARR" ((length(R) > 0 ? "#" ((R[1] != "zhopa" ? "U" : "l")) : "")) : ", " _val0(R))) "):") + _wonl(_val0(r = _splitstr(t, A, R))) + _wonl("arrary A:") + _wonl(_dumparr(A)) + return r +} + +function tts(p, uidel, psfx, cnt, chr, p5, p6, p7, im) +{ + im = " " + im = ".. .." + _conl("ret: " _qparam(im, p, uidel, psfx, cnt, chr, p5, p6, p7) "'") + _conl("mask: `" _qparamask "'") +} + +# # - p is array +# ` - p is ptr detected in array _CLASSPTR(for _typ); or p is ptr detected in array A(for _typa) +# 0 - p is undefined + +# 2 - p is string=="" +# 3 - p is string!="" +# 4 - p is number 0 +# 5 - p is any number except 0(positive and negative) + +# str: _typ(p)+0 !_typ(p)+0 +# str/ptr _typ(p)>0 _typ(p)<1 +# str/arr "`">_typ(p0) && _t0 +# str/ptr/arr _typ(p) !_typ(p) +# ptr _typ(p)=="`" _typ(p)<"`" ? +# ptr/arr _typ(p)+0!=_t0 +# arr _typ(p)=="#" _typ(p)>"#" ? + +function zorr(A, i, r) +{ + if (i in A) { + _conl("`" i "' in A") + } else { + _conl("`" i "' not in A") + } + r = A[i] == "" && A[i] == 0 + _conl("A[" i "] status is " r) + return + a = a + -a + _conl("``````````````" a "''''''''''''''''") +} + +#_____________________________________________________________________________ +function zzer() +{ + ################################################################ +} diff --git a/test/testext.ok b/test/testext.ok index 5612e92c..9b36bf72 100644 --- a/test/testext.ok +++ b/test/testext.ok @@ -15,6 +15,7 @@ try_modify_environ: set_array_element of ENVIRON failed try_modify_environ: marking element "testext" for deletion try_del_environ() could not delete element - pass try_del_environ() could not add an element - pass +var_test: sym_lookup of PROCINFO passed - did not get a value var_test: sym_lookup of ARGC passed - got a value! var_test: sym_update of ARGC failed - correctly var_test: sym_update("testvar") succeeded |