diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 1437 | ||||
| -rw-r--r-- | doc/gawk.texi | 390 | ||||
| -rw-r--r-- | doc/gawktexi.in | 390 | ||||
| -rw-r--r-- | main.c | 2 | ||||
| -rw-r--r-- | test/ChangeLog | 4 | ||||
| -rw-r--r-- | test/badargs.ok | 2 |
8 files changed, 1086 insertions, 1149 deletions
@@ -1,3 +1,9 @@ +2014-08-15 Arnold D. Robbins <arnold@skeeve.com> + + * main.c (usage): Adjust whitespace for -L and add "invalid" + as a possible value for it. Report from Robert P. J. Day + <rpjday@crashcourse.ca>. + 2014-08-14 Arnold D. Robbins <arnold@skeeve.com> * Makefile.am (SUBDIRS): Put awklib after doc so that examples diff --git a/doc/ChangeLog b/doc/ChangeLog index 71ab5e56..e44e28b8 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2014-08-15 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Continuing on reviewer comments. + 2014-08-13 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Starting on reviewer comments. diff --git a/doc/gawk.info b/doc/gawk.info index 07c6abb9..878b1584 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -190,7 +190,7 @@ entitled "GNU Free Documentation License". * Single Character Fields:: Making each character a separate field. * Command Line Field Separator:: Setting `FS' from the - command-line. + command line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -216,7 +216,7 @@ entitled "GNU Free Documentation License". `getline'. * Getline Summary:: Summary of `getline' Variants. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -255,7 +255,7 @@ entitled "GNU Free Documentation License". * Variables:: Variables give names to values for later use. * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. * Conversion:: The conversion of strings to numbers @@ -884,7 +884,7 @@ 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. +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 @@ -1086,7 +1086,7 @@ formatting language. A single Texinfo source file is used to produce both the printed and online versions of the documentation. This minor node briefly documents the typographical conventions used in Texinfo. - Examples you would type at the command-line are preceded by the + Examples you would type at the command line are preceded by the common shell primary and secondary prompts, `$' and `>'. Input that you type is shown `like this'. Output from the command is preceded by the glyph "-|". This typically represents the command's standard @@ -1456,7 +1456,7 @@ 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(1) (`BEGIN' is a feature we haven't discussed yet): +programming (`BEGIN' is a feature we haven't discussed yet): $ awk "BEGIN { print \"Don't Panic!\" }" -| Don't Panic! @@ -1464,7 +1464,13 @@ programming(1) (`BEGIN' is a feature we haven't discussed yet): 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.(2) +quotes.(1) + + 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. This next simple `awk' program emulates the `cat' utility; it copies whatever you type on the keyboard to its standard output (why this @@ -1483,12 +1489,7 @@ works is explained shortly). ---------- Footnotes ---------- - (1) 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. - - (2) Although we generally recommend the use of single quotes around + (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. @@ -1719,9 +1720,9 @@ the quoting rules. Note that the single quote is not special within double quotes. * Null strings are removed when they occur as part of a non-null - command-line argument, while explicit non-null objects are kept. - For example, to specify that the field separator `FS' should be - set to the null string, use: + command-line argument, while explicit null objects are kept. For + example, to specify that the field separator `FS' should be set to + the null string, use: awk -F "" 'PROGRAM' FILES # correct @@ -1814,10 +1815,10 @@ 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. 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: +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 @@ -2505,8 +2506,8 @@ The following list describes options mandated by the POSIX standard: this option is intended to be used with code libraries, `gawk' does not recognize such files as constituting main program input. Thus, after processing an `-i' argument, `gawk' still expects to - find the main source code via the `-f' option or on the - command-line. + find the main source code via the `-f' option or on the command + line. `-l' EXT `--load' EXT @@ -2523,7 +2524,7 @@ The following list describes options mandated by the POSIX standard: `-L'[VALUE] `--lint'[`='VALUE] Warn about constructs that are dubious or nonportable to other - `awk' implementations. No space is allowed between the `-D' and + `awk' implementations. No space is allowed between the `-L' and VALUE, if VALUE is supplied. Some warnings are issued when `gawk' first reads your program. Others are issued at runtime, as your program executes. With an optional argument of `fatal', lint @@ -2601,7 +2602,7 @@ The following list describes options mandated by the POSIX standard: * Newlines are not allowed after `?' or `:' (*note Conditional Exp::). - * Specifying `-Ft' on the command-line does not set the value + * Specifying `-Ft' on the command line does not set the value of `FS' to be a single TAB character (*note Field Separators::). @@ -2783,7 +2784,7 @@ with `getline' (*note Getline/File::). In addition, `gawk' allows you to specify the special file name `/dev/stdin', both on the command line and with `getline'. Some other versions of `awk' also support this, but it is not standard. (Some -operating systems provide a `/dev/stdin' file in the file system; +operating systems provide a `/dev/stdin' file in the filesystem; however, `gawk' always processes this file name itself.) @@ -2809,7 +2810,7 @@ File: gawk.info, Node: AWKPATH Variable, Next: AWKLIBPATH Variable, Up: Envir ---------------------------------------- The previous minor node described how `awk' program files can be named -on the command-line with the `-f' option. In most `awk' +on the command line with the `-f' option. In most `awk' implementations, you must supply a precise path name for each program file, unless the file is in the current directory. But in `gawk', if the file name supplied to the `-f' or `-i' options does not contain a @@ -2896,7 +2897,7 @@ they are more specialized. Those in the following list are meant to be used by regular users. `POSIXLY_CORRECT' - Causes `gawk' to switch POSIX compatibility mode, disabling all + Causes `gawk' to switch to POSIX compatibility mode, disabling all traditional and GNU extensions. *Note Options::. `GAWK_SOCK_RETRIES' @@ -2924,7 +2925,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 file systems I/O blocksize.) + blocksize, which is usually the filesystems I/O blocksize.) `AWK_HASH' If this variable exists with a value of `gst', `gawk' switches to @@ -3153,9 +3154,9 @@ File: gawk.info, Node: Invoking Summary, Prev: Undocumented, Up: Invoking Gaw * Use either `awk 'PROGRAM' FILES' or `awk -f PROGRAM-FILE FILES' to run `awk'. - * The three standard `awk' options are `-f', `-F' and `-v'. `gawk' - supplies these and many others, as well as corresponding GNU-style - long options. + * The three standard options for all versions of `awk' are `-f', + `-F' and `-v'. `gawk' supplies these and many others, as well as + corresponding GNU-style long options. * Non-option command-line arguments are usually treated as file names, unless they have the form `VAR=VALUE', in which case they @@ -3991,7 +3992,7 @@ File: gawk.info, Node: Regexp Summary, Prev: Computed Regexps, Up: Regexp `awk', regular expression constants are written enclosed between slashes: `/'...`/'. - * Regexp constants may be used by standalone in patterns and in + * Regexp constants may be used standalone in patterns and in conditional expressions, or as part of matching expressions using the `~' and `!~' operators. @@ -4015,8 +4016,8 @@ File: gawk.info, Node: Regexp Summary, Prev: Computed Regexps, Up: Regexp extent of the match, such as for text substitution and when the record separator is a regexp. - * Matching expressions may use dynamic regexps; that is string values - treated as regular expressions. + * Matching expressions may use dynamic regexps; that is, string + values treated as regular expressions. @@ -4057,7 +4058,7 @@ have to be named on the `awk' command line (*note Getline::). * Getline:: Reading files under explicit program control using the `getline' function. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on the +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -4239,16 +4240,16 @@ trailing whitespace: $ echo record 1 AAAA record 2 BBBB record 3 | > gawk 'BEGIN { RS = "\n|( *[[:upper:]]+ *)" } - > { print "Record =", $0, "and RT =", RT }' - -| Record = record 1 and RT = AAAA - -| Record = record 2 and RT = BBBB - -| Record = record 3 and RT = - -| + > { print "Record =", $0,"and RT = [" RT "]" }' + -| Record = record 1 and RT = [ AAAA ] + -| Record = record 2 and RT = [ BBBB ] + -| Record = record 3 and RT = [ + -| ] -The final line of output has an extra blank line. This is because the -value of `RT' is a newline, and the `print' statement supplies its own -terminating newline. *Note Simple Sed::, for a more useful example of -`RS' as a regexp and `RT'. +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'. If you set `RS' to a regular expression that allows optional trailing text, such as `RS = "abc(XYZ)?"' it is possible, due to @@ -4590,7 +4591,7 @@ File: gawk.info, Node: Field Separators, Next: Constant Size, Prev: Changing * Default Field Splitting:: How fields are normally separated. * 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. @@ -5754,7 +5755,7 @@ VAR Table 4.1: `getline' Variants and What They Set -File: gawk.info, Node: Read Timeout, Next: Command line directories, Prev: Getline, Up: Reading Files +File: gawk.info, Node: Read Timeout, Next: Command-line directories, Prev: Getline, Up: Reading Files 4.10 Reading Input With A Timeout ================================= @@ -5848,7 +5849,7 @@ writing. (1) This assumes that standard input is the keyboard. -File: gawk.info, Node: Command line directories, Next: Input Summary, Prev: Read Timeout, Up: Reading Files +File: gawk.info, Node: Command-line directories, Next: Input Summary, Prev: Read Timeout, Up: Reading Files 4.11 Directories On The Command Line ==================================== @@ -5871,7 +5872,7 @@ error. usable data from an `awk' program. -File: gawk.info, Node: Input Summary, Next: Input Exercises, Prev: Command line directories, Up: Reading Files +File: gawk.info, Node: Input Summary, Next: Input Exercises, Prev: Command-line directories, Up: Reading Files 4.12 Summary ============ @@ -7355,12 +7356,12 @@ For example: } In this example, the programmer wants to pass a regexp constant to -the user-defined function `mysub', which in turn passes it on to either -`sub()' or `gsub()'. However, what really happens is that the `pat' -parameter is either one or zero, depending upon whether or not `$0' -matches `/hi/'. `gawk' issues a warning when it sees a regexp constant -used as a parameter to a user-defined function, since passing a truth -value in this way is probably not what was intended. +the user-defined function `mysub()', which in turn passes it on to +either `sub()' or `gsub()'. However, what really happens is that the +`pat' parameter is either one or zero, depending upon whether or not +`$0' matches `/hi/'. `gawk' issues a warning when it sees a regexp +constant used as a parameter to a user-defined function, since passing +a truth value in this way is probably not what was intended. File: gawk.info, Node: Variables, Next: Conversion, Prev: Using Constant Regexps, Up: Values @@ -7376,7 +7377,7 @@ on the `awk' command line. * Menu: * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line and a +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. @@ -12345,9 +12346,13 @@ File: gawk.info, Node: Gory Details, Up: String Functions 9.1.3.1 More About `\' and `&' with `sub()', `gsub()', and `gensub()' ..................................................................... -When using `sub()', `gsub()', or `gensub()', and trying to get literal -backslashes and ampersands into the replacement text, you need to -remember that there are several levels of "escape processing" going on. + CAUTION: This section has been known 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 +to remember that there are several levels of "escape processing" going +on. First, there is the "lexical" level, which is when `awk' reads your program and builds an internal copy of it to execute. Then there is @@ -12373,13 +12378,13 @@ is illustrated in *note table-sub-escapes::. You type `sub()' sees `sub()' generates ------- --------- -------------- - `\&' `&' the matched text - `\\&' `\&' a literal `&' - `\\\&' `\&' a literal `&' - `\\\\&' `\\&' a literal `\&' - `\\\\\&' `\\&' a literal `\&' - `\\\\\\&' `\\\&' a literal `\\&' - `\\q' `\q' a literal `\q' + `\&' `&' The matched text + `\\&' `\&' A literal `&' + `\\\&' `\&' A literal `&' + `\\\\&' `\\&' A literal `\&' + `\\\\\&' `\\&' A literal `\&' + `\\\\\\&' `\\\&' A literal `\\&' + `\\q' `\q' A literal `\q' Table 9.1: Historical Escape Sequence Processing for `sub()' and `gsub()' @@ -12393,50 +12398,25 @@ backslashes entered at the lexical level.) The problem with the historical approach is that there is no way to get a literal `\' followed by the matched text. - The 1992 POSIX standard attempted to fix this problem. That standard -says that `sub()' and `gsub()' look for either a `\' or an `&' after -the `\'. If either one follows a `\', that character is output -literally. The interpretation of `\' and `&' then becomes as shown in -*note table-sub-posix-92::. + Several editions of the POSIX standard attempted to fix this problem +but weren't successful. The details are irrelevant at this point in +time. - You type `sub()' sees `sub()' generates - ------- --------- -------------- - `&' `&' the matched text - `\\&' `\&' a literal `&' - `\\\\&' `\\&' a literal `\', then the matched text - `\\\\\\&' `\\\&' a literal `\&' - -Table 9.2: 1992 POSIX Rules for `sub()' and `gsub()' Escape Sequence -Processing - -This appears to solve the problem. Unfortunately, the phrasing of the -standard is unusual. It says, in effect, that `\' turns off the special -meaning of any following character, but for anything other than `\' and -`&', such special meaning is undefined. This wording leads to two -problems: - - * Backslashes must now be doubled in the REPLACEMENT string, breaking - historical `awk' programs. - - * To make sure that an `awk' program is portable, _every_ character - in the REPLACEMENT string must be preceded with a backslash.(1) - - Because of the problems just listed, in 1996, the `gawk' maintainer -submitted proposed text for a revised standard that reverts to rules -that correspond more closely to the original existing practice. The -proposed rules have special cases that make it possible to produce a -`\' preceding the matched text. This is shown in *note -table-sub-proposed::. + At one point, the `gawk' maintainer submitted proposed text for a +revised standard that reverts to rules that correspond more closely to +the original existing practice. The proposed rules have special cases +that make it possible to produce a `\' preceding the matched text. +This is shown in *note table-sub-proposed::. You type `sub()' sees `sub()' generates ------- --------- -------------- - `\\\\\\&' `\\\&' a literal `\&' - `\\\\&' `\\&' a literal `\', followed by the matched text - `\\&' `\&' a literal `&' - `\\q' `\q' a literal `\q' + `\\\\\\&' `\\\&' A literal `\&' + `\\\\&' `\\&' A literal `\', followed by the matched text + `\\&' `\&' A literal `&' + `\\q' `\q' A literal `\q' `\\\\' `\\' `\\' -Table 9.3: Proposed Rules For `sub()' And Backslash +Table 9.2: GNU `awk' Rules For `sub()' And Backslash In a nutshell, at the runtime level, there are now three special sequences of characters (`\\\&', `\\&' and `\&') whereas historically @@ -12444,11 +12424,11 @@ there was only one. However, as in the historical case, any `\' that is not part of one of these three sequences is not special and appears in the output literally. - `gawk' 3.0 and 3.1 follow these proposed POSIX rules for `sub()' and -`gsub()'. The POSIX standard took much longer to be revised than was -expected in 1996. The 2001 standard does not follow the above rules. -Instead, the rules there are somewhat simpler. The results are similar -except for one case. + `gawk' 3.0 and 3.1 follow these rules for `sub()' and `gsub()'. The +POSIX standard took much longer to be revised than was expected. In +addition, the `gawk' maintainer's proposal was lost during the +standardization process. The final rules are somewhat simpler. The +results are similar except for one case. The POSIX rules state that `\&' in the replacement string produces a literal `&', `\\' produces a literal `\', and `\' followed by anything @@ -12457,25 +12437,25 @@ rules are presented in *note table-posix-sub::. You type `sub()' sees `sub()' generates ------- --------- -------------- - `\\\\\\&' `\\\&' a literal `\&' - `\\\\&' `\\&' a literal `\', followed by the matched text - `\\&' `\&' a literal `&' - `\\q' `\q' a literal `\q' + `\\\\\\&' `\\\&' A literal `\&' + `\\\\&' `\\&' A literal `\', followed by the matched text + `\\&' `\&' A literal `&' + `\\q' `\q' A literal `\q' `\\\\' `\\' `\' -Table 9.4: POSIX Rules For `sub()' And `gsub()' +Table 9.3: POSIX Rules For `sub()' And `gsub()' The only case where the difference is noticeable is the last one: `\\\\' is seen as `\\' and produces `\' instead of `\\'. Starting with version 3.1.4, `gawk' followed the POSIX rules when `--posix' is specified (*note Options::). Otherwise, it continued to -follow the 1996 proposed rules, since that had been its behavior for -many years. +follow the proposed rules, since that had been its behavior for many +years. When version 4.0.0 was released, the `gawk' maintainer made the POSIX rules the default, breaking well over a decade's worth of -backwards compatibility.(2) Needless to say, this was a bad idea, and +backwards compatibility.(1) Needless to say, this was a bad idea, and as of version 4.0.1, `gawk' resumed its historical behavior, and only follows the POSIX rules when `--posix' is given. @@ -12488,14 +12468,14 @@ the `\' does not, as shown in *note table-gensub-escapes::. You type `gensub()' sees `gensub()' generates ------- ------------ ----------------- - `&' `&' the matched text - `\\&' `\&' a literal `&' - `\\\\' `\\' a literal `\' - `\\\\&' `\\&' a literal `\', then the matched text - `\\\\\\&' `\\\&' a literal `\&' - `\\q' `\q' a literal `q' + `&' `&' The matched text + `\\&' `\&' A literal `&' + `\\\\' `\\' A literal `\' + `\\\\&' `\\&' A literal `\', then the matched text + `\\\\\\&' `\\\&' A literal `\&' + `\\q' `\q' A literal `q' -Table 9.5: Escape Sequence Processing For `gensub()' +Table 9.4: Escape Sequence Processing For `gensub()' Because of the complexity of the lexical and runtime level processing and the special cases for `sub()' and `gsub()', we recommend the use of @@ -12514,9 +12494,7 @@ Although this makes a certain amount of sense, it can be surprising. ---------- Footnotes ---------- - (1) This consequence was certainly unintended. - - (2) This was rather naive of him, despite there being a note in this + (1) This was rather naive of him, despite there being a note in this section indicating that the next major version would move to the POSIX rules. @@ -13047,7 +13025,7 @@ table-bitwise-ops::. 0 | 0 0 | 0 1 | 0 1 1 | 0 1 | 1 1 | 1 0 -Table 9.6: Bitwise Operations +Table 9.5: Bitwise Operations As you can see, the result of an AND operation is 1 only when _both_ bits are 1. The result of an OR operation is 1 if _either_ bit is 1. @@ -13401,22 +13379,22 @@ 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. Recursive functions must always have a test that stops the recursion. -In this case, the recursion terminates when the starting position is -zero, i.e., when there are no more characters left in the string. +In this case, the recursion terminates when the input string is already +empty. - function rev(str, start) + function rev(str) { - if (start == 0) + if (str == "") return "" - return (substr(str, start, 1) rev(str, start - 1)) + return (rev(substr(str, 2)) substr(str, 1, 1)) } If this function is in a file named `rev.awk', it can be tested this way: $ echo "Don't Panic!" | - > gawk --source '{ print rev($0, length($0)) }' -f rev.awk + > gawk --source '{ print rev($0) }' -f rev.awk -| !cinaP t'noD The C `ctime()' function takes a timestamp and returns it in a @@ -13666,8 +13644,8 @@ function _are_ visible outside that function. a[1], a[2], a[3] } - prints `a[1] = 1, a[2] = two, a[3] = 3', because `changeit' stores - `"two"' in the second element of `a'. + prints `a[1] = 1, a[2] = two, a[3] = 3', because `changeit()' + stores `"two"' in the second element of `a'. Some `awk' implementations allow you to call a function that has not been defined. They only report a problem at runtime when the program @@ -19217,24 +19195,7 @@ File: gawk.info, Node: Two-way I/O, Next: TCP/IP Networking, Prev: Array Sort 12.3 Two-Way Communications with Another Process ================================================ - From: brennan@whidbey.com (Mike Brennan) - Newsgroups: comp.lang.awk - Subject: Re: Learn the SECRET to Attract Women Easily - Date: 4 Aug 1997 17:34:46 GMT - Message-ID: <5s53rm$eca@news.whidbey.com> - - On 3 Aug 1997 13:17:43 GMT, Want More Dates??? - <tracy78@kilgrona.com> wrote: - >Learn the SECRET to Attract Women Easily - > - >The SCENT(tm) Pheromone Sex Attractant For Men to Attract Women - - The scent of awk programmers is a lot more attractive to women than - the scent of perl programmers. - -- - Mike Brennan - - It is often useful to be able to send data to a separate program for +It is often useful to be able to send data to a separate program for processing and then read the result. This can always be done with temporary files: @@ -19253,12 +19214,11 @@ temporary files: This works, but not elegantly. Among other things, it requires that the program be run in a directory that cannot be shared among users; for example, `/tmp' will not do, as another user might happen to be -using a temporary file with the same name. - - However, with `gawk', it is possible to open a _two-way_ pipe to -another process. The second process is termed a "coprocess", since it -runs in parallel with `gawk'. The two-way connection is created using -the `|&' operator (borrowed from the Korn shell, `ksh'):(1) +using a temporary file with the same name.(1) However, with `gawk', it +is possible to open a _two-way_ pipe to another process. The second +process is termed a "coprocess", since it runs in parallel with `gawk'. +The two-way connection is created using the `|&' operator (borrowed +from the Korn shell, `ksh'):(2) do { print DATA |& "subprogram" @@ -19345,7 +19305,11 @@ using regular pipes. ---------- Footnotes ---------- - (1) This is very different from the same operator in the C shell and + (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. + + (2) This is very different from the same operator in the C shell and in Bash. @@ -19368,7 +19332,7 @@ 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 networking is by recognizing special file names that begin with one of -`/inet/', `/inet4/' or `/inet6'. +`/inet/', `/inet4/' or `/inet6/'. The full syntax of the special file name is `/NET-TYPE/PROTOCOL/LOCAL-PORT/REMOTE-HOST/REMOTE-PORT'. The @@ -21405,6 +21369,10 @@ in `gawk'. It continues on to present arbitrary precision integers, and concludes with a description of some points where `gawk' and the POSIX standard are not quite in agreement. + NOTE: Most users of `gawk' can safely skip this chapter. But if + you want to do scientific calculations with `gawk', this is the + place to be. + * Menu: * Computer Arithmetic:: A quick intro to computer math. @@ -21535,9 +21503,18 @@ material here. number and infinity produce infinity. "NaN" - "Not A Number." A special value indicating a result that can't - happen in real math, but that can happen in floating-point - computations. + "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 + systems return `NaN'. Some examples: + + `sqrt(-1)' + This makes sense in the range of complex numbers, but not in + the range of real numbers, so the result is `NaN'. + + `log(-8)' + -8 is out of the domain of `log()', so the result is `NaN'. "Normalized" How the significand (see later in this list) is usually stored. The @@ -21595,6 +21572,11 @@ Table 15.1: Basic IEEE Format Context 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 + File: gawk.info, Node: MPFR features, Next: FP Math Caution, Prev: Math Definitions, Up: Arbitrary Precision Arithmetic @@ -21922,7 +21904,7 @@ on arithmetic operations: of a constant. If you need to represent a floating-point constant at a higher - precision than the default and cannot use a command line + precision than the default and cannot use a command-line assignment to `PREC', you should either specify the constant as a string, or as a rational number, whenever possible. The following example illustrates the differences among various ways to print a @@ -22440,7 +22422,7 @@ Example::) and also the `testext.c' code for testing the APIs. Some other bits and pieces: * The API provides access to `gawk''s `do_XXX' values, reflecting - command line options, like `do_lint', `do_profiling' and so on + command-line options, like `do_lint', `do_profiling' and so on (*note Extension API Variables::). These are informational: an extension cannot affect their values inside `gawk'. In addition, attempting to assign to them produces a compile-time error. @@ -26034,7 +26016,7 @@ the current version of `gawk'. - Indirect function calls (*note Indirect Calls::). - Directories on the command line produce a warning and are - skipped (*note Command line directories::). + skipped (*note Command-line directories::). * New keywords: @@ -26204,7 +26186,7 @@ in POSIX `awk', in the order they were added to `gawk'. * The ability to delete all of an array at once with `delete ARRAY' (*note Delete::). - * Command line option changes (*note Options::): + * Command-line option changes (*note Options::): - The ability to use GNU-style long-named options that start with `--'. @@ -26241,7 +26223,7 @@ in POSIX `awk', in the order they were added to `gawk'. * The `fflush()' function from Brian Kernighan's `awk' (then at Bell Laboratories; *note I/O Functions::). - * New command line options: + * New command-line options: - The `--lint-old' option to warn about constructs that are not available in the original Version 7 Unix version of `awk' @@ -26434,7 +26416,7 @@ in POSIX `awk', in the order they were added to `gawk'. * `switch' / `case' are enabled by default (*note Switch Statement::). - * Command line option changes (*note Options::): + * Command-line option changes (*note Options::): - The `-b' and `--characters-as-bytes' options which prevent `gawk' from treating input as a multibyte string. @@ -26452,7 +26434,7 @@ in POSIX `awk', in the order they were added to `gawk'. * Directories named on the command line now produce a warning, not a fatal error, unless `--posix' or `--traditional' are used (*note - Command line directories::). + Command-line directories::). * The `gawk' internals were rewritten, bringing the `dgawk' debugger and possibly improved performance (*note Debugger::). @@ -26501,10 +26483,10 @@ in POSIX `awk', in the order they were added to `gawk'. `PROCINFO["identifiers"]' (*note Auto-set::). * The three executables `gawk', `pgawk', and `dgawk', were merged - into one, named just `gawk'. As a result the command line options + into one, named just `gawk'. As a result the command-line options changed. - * Command line option changes (*note Options::): + * Command-line option changes (*note Options::): - The `-D' option invokes the debugger. @@ -30985,7 +30967,7 @@ Index * * (asterisk), * operator, as regexp operator: Regexp Operators. (line 88) * * (asterisk), * operator, null strings, matching: Gory Details. - (line 164) + (line 143) * * (asterisk), ** operator <1>: Precedence. (line 49) * * (asterisk), ** operator: Arithmetic Ops. (line 81) * * (asterisk), **= operator <1>: Precedence. (line 95) @@ -31066,7 +31048,7 @@ Index * -F option: Options. (line 21) * -f option: Long. (line 12) * -F option, -Ft sets FS to TAB: Options. (line 306) -* -F option, command line: Command Line Field Separator. +* -F option, command-line: Command Line Field Separator. (line 6) * -f option, multiple uses: Options. (line 311) * -g option: Options. (line 147) @@ -31224,7 +31206,7 @@ Index * advanced features, network programming: TCP/IP Networking. (line 6) * advanced features, nondecimal input data: Nondecimal Data. (line 6) * advanced features, processes, communicating with: Two-way I/O. - (line 23) + (line 6) * advanced features, specifying field content: Splitting By Content. (line 10) * Aho, Alfred <1>: Contributors. (line 11) @@ -31344,7 +31326,7 @@ Index * asterisk (*), * operator, as regexp operator: Regexp Operators. (line 88) * asterisk (*), * operator, null strings, matching: Gory Details. - (line 164) + (line 143) * asterisk (*), ** operator <1>: Precedence. (line 49) * asterisk (*), ** operator: Arithmetic Ops. (line 81) * asterisk (*), **= operator <1>: Precedence. (line 95) @@ -31547,12 +31529,11 @@ Index * breakpoint, how to disable or enable: Breakpoint Control. (line 69) * breakpoint, setting: Breakpoint Control. (line 11) * Brennan, Michael <1>: Other Versions. (line 6) -* Brennan, Michael <2>: Two-way I/O. (line 6) -* Brennan, Michael <3>: Simple Sed. (line 25) -* Brennan, Michael <4>: Delete. (line 56) +* Brennan, Michael <2>: Simple Sed. (line 25) +* Brennan, Michael <3>: Delete. (line 56) * Brennan, Michael: Foreword. (line 83) * Brian Kernighan's awk <1>: I/O Functions. (line 43) -* Brian Kernighan's awk <2>: Gory Details. (line 15) +* 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 <5>: Nextfile Statement. (line 47) @@ -31579,7 +31560,7 @@ Index * Buening, Andreas <1>: Bugs. (line 71) * Buening, Andreas <2>: Contributors. (line 92) * Buening, Andreas: Acknowledgments. (line 60) -* buffering, input/output <1>: Two-way I/O. (line 70) +* 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) * buffers, flushing: I/O Functions. (line 32) @@ -31647,7 +31628,7 @@ Index (line 81) * close() function, return value: Close Files And Pipes. (line 131) -* close() function, two-way pipes and: Two-way I/O. (line 77) +* 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) @@ -31662,7 +31643,7 @@ Index * command line, arguments <1>: ARGC and ARGV. (line 6) * command line, arguments <2>: Auto-set. (line 15) * command line, arguments: Other Arguments. (line 6) -* command line, directories on: Command line directories. +* command line, directories on: Command-line directories. (line 6) * command line, formats: Running gawk. (line 12) * command line, FS on, setting: Command Line Field Separator. @@ -31754,7 +31735,7 @@ Index * CONVFMT variable, and array subscripts: Numeric Array Subscripts. (line 6) * cookie: Glossary. (line 149) -* coprocesses <1>: Two-way I/O. (line 44) +* coprocesses <1>: Two-way I/O. (line 25) * coprocesses: Redirection. (line 102) * coprocesses, closing: Close Files And Pipes. (line 6) @@ -31764,7 +31745,7 @@ Index * counting: Wc Program. (line 6) * csh utility: Statements/Lines. (line 44) * csh utility, POSIXLY_CORRECT environment variable: Options. (line 353) -* csh utility, |& operator, comparison with: Two-way I/O. (line 44) +* csh utility, |& operator, comparison with: Two-way I/O. (line 25) * ctime() user-defined function: Function Example. (line 73) * currency symbols, localization: Explaining gettext. (line 104) * current system time: Time Functions. (line 66) @@ -31840,7 +31821,7 @@ Index * dcngettext: I18N Functions. (line 28) * dcngettext() function (gawk), portability and: I18N Portability. (line 33) -* deadlocks: Two-way I/O. (line 70) +* deadlocks: Two-way I/O. (line 52) * debugger commands, b (break): Breakpoint Control. (line 11) * debugger commands, backtrace: Execution Stack. (line 13) * debugger commands, break: Breakpoint Control. (line 11) @@ -31983,7 +31964,7 @@ Index (line 15) * differences in awk and gawk, close() function: Close Files And Pipes. (line 81) -* differences in awk and gawk, command line directories: Command line directories. +* 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) @@ -32036,7 +32017,7 @@ Index (line 152) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. (line 66) -* directories, command line: Command line directories. +* directories, command-line: Command-line directories. (line 6) * directories, searching: Programs Exercises. (line 63) * directories, searching for loadable extensions: AWKLIBPATH Variable. @@ -32505,7 +32486,7 @@ 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, PROCINFO array in <1>: Two-way I/O. (line 117) +* 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, regexp constants and: Using Constant Regexps. @@ -32556,7 +32537,7 @@ Index (line 6) * getline command, coprocesses, using from: Getline/Coprocess. (line 6) -* getline command, deadlock and: Two-way I/O. (line 70) +* getline command, deadlock and: Two-way I/O. (line 52) * getline command, explicit input with: Getline. (line 6) * getline command, FILENAME variable and: Getline Notes. (line 19) * getline command, return values: Getline. (line 19) @@ -32702,7 +32683,7 @@ Index * input/output functions: I/O Functions. (line 6) * input/output, binary: User-modified. (line 15) * input/output, from BEGIN and END: I/O And BEGIN/END. (line 6) -* input/output, two-way: Two-way I/O. (line 44) +* input/output, two-way: Two-way I/O. (line 25) * insomnia, cure for: Alarm Program. (line 6) * installation, VMS: VMS Installation. (line 6) * installing gawk: Installation. (line 6) @@ -32893,7 +32874,7 @@ Index * matching, expressions, See comparison expressions: Typing and Comparison. (line 9) * matching, leftmost longest: Multiple Line. (line 26) -* matching, null strings: Gory Details. (line 164) +* matching, null strings: Gory Details. (line 143) * mawk utility <1>: Other Versions. (line 44) * mawk utility <2>: Nextfile Statement. (line 47) * mawk utility <3>: Concatenation. (line 36) @@ -32987,7 +32968,7 @@ Index (line 43) * null strings, converting numbers to strings: Strings And Numbers. (line 21) -* null strings, matching: Gory Details. (line 164) +* null strings, matching: Gory Details. (line 143) * number as string of bits: Bitwise Functions. (line 109) * number of array elements: String Functions. (line 197) * number sign (#), #! (executable scripts): Executable Scripts. @@ -33193,7 +33174,7 @@ Index * 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, functions and, gsub()/sub(): Gory Details. (line 54) +* POSIX awk, functions and, gsub()/sub(): Gory Details. (line 90) * POSIX awk, functions and, length(): String Functions. (line 176) * POSIX awk, GNU long options and: Options. (line 15) * POSIX awk, interval expressions in: Regexp Operators. (line 136) @@ -33255,12 +33236,12 @@ Index * private variables: Library Names. (line 11) * process group idIDof gawk process: Auto-set. (line 183) * process ID of gawk process: Auto-set. (line 186) -* processes, two-way communications with: Two-way I/O. (line 23) +* 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, and communications via ptys: Two-way I/O. (line 117) +* 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. @@ -33272,7 +33253,6 @@ Index * profiling awk programs, dynamically: Profiling. (line 179) * program identifiers: Auto-set. (line 154) * program, definition of: Getting Started. (line 21) -* programmers, attractiveness of: Two-way I/O. (line 6) * programming conventions, --non-decimal-data option: Nondecimal Data. (line 36) * programming conventions, ARGC/ARGV variables: Auto-set. (line 35) @@ -33572,7 +33552,7 @@ Index (line 64) * sidebar, Interactive Versus Noninteractive Buffering: I/O Functions. (line 107) -* sidebar, Matching the Null String: Gory Details. (line 162) +* sidebar, Matching the Null String: Gory Details. (line 141) * sidebar, Operator Evaluation Order: Increment Ops. (line 58) * sidebar, Piping into sh: Redirection. (line 140) * sidebar, Portability Issues with #!: Executable Scripts. (line 31) @@ -33621,7 +33601,7 @@ Index * sort function, arrays, sorting: Array Sorting Functions. (line 6) * sort utility: Word Sorting. (line 50) -* sort utility, coprocesses and: Two-way I/O. (line 83) +* sort utility, coprocesses and: Two-way I/O. (line 65) * sorting characters in different languages: Explaining gettext. (line 94) * source code, awka: Other Versions. (line 64) @@ -33913,7 +33893,7 @@ Index * vertical bar (|): Regexp Operators. (line 70) * vertical bar (|), | operator (I/O) <1>: Precedence. (line 65) * vertical bar (|), | operator (I/O): Getline/Pipe. (line 9) -* vertical bar (|), |& operator (I/O) <1>: Two-way I/O. (line 44) +* 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): Getline/Coprocess. (line 6) * vertical bar (|), || operator <1>: Precedence. (line 89) @@ -33975,7 +33955,7 @@ Index * | (vertical bar), | operator (I/O) <1>: Precedence. (line 65) * | (vertical bar), | operator (I/O) <2>: Redirection. (line 57) * | (vertical bar), | operator (I/O): Getline/Pipe. (line 9) -* | (vertical bar), |& operator (I/O) <1>: Two-way I/O. (line 44) +* | (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): Getline/Coprocess. (line 6) @@ -34015,532 +33995,531 @@ Node: Getting Started70816 Node: Running gawk73250 Node: One-shot74440 Node: Read Terminal75665 -Ref: Read Terminal-Footnote-177315 -Ref: Read Terminal-Footnote-277591 -Node: Long77762 -Node: Executable Scripts79138 -Ref: Executable Scripts-Footnote-180971 -Ref: Executable Scripts-Footnote-281073 -Node: Comments81620 -Node: Quoting84093 -Node: DOS Quoting89409 -Node: Sample Data Files90084 -Node: Very Simple92599 -Node: Two Rules97372 -Node: More Complex99266 -Ref: More Complex-Footnote-1102198 -Node: Statements/Lines102283 -Ref: Statements/Lines-Footnote-1106739 -Node: Other Features107004 -Node: When107932 -Node: Intro Summary110102 -Node: Invoking Gawk110868 -Node: Command Line112383 -Node: Options113174 -Ref: Options-Footnote-1128874 -Node: Other Arguments128899 -Node: Naming Standard Input131561 -Node: Environment Variables132655 -Node: AWKPATH Variable133213 -Ref: AWKPATH Variable-Footnote-1136085 -Ref: AWKPATH Variable-Footnote-2136130 -Node: AWKLIBPATH Variable136390 -Node: Other Environment Variables137149 -Node: Exit Status140599 -Node: Include Files141274 -Node: Loading Shared Libraries144852 -Node: Obsolete146236 -Node: Undocumented146933 -Node: Invoking Summary147200 -Node: Regexp148780 -Node: Regexp Usage150230 -Node: Escape Sequences152263 -Node: Regexp Operators157930 -Ref: Regexp Operators-Footnote-1165410 -Ref: Regexp Operators-Footnote-2165557 -Node: Bracket Expressions165655 -Ref: table-char-classes167545 -Node: GNU Regexp Operators170485 -Node: Case-sensitivity174208 -Ref: Case-sensitivity-Footnote-1177100 -Ref: Case-sensitivity-Footnote-2177335 -Node: Leftmost Longest177443 -Node: Computed Regexps178644 -Node: Regexp Summary182016 -Node: Reading Files183487 -Node: Records185579 -Node: awk split records186322 -Node: gawk split records191180 -Ref: gawk split records-Footnote-1195701 -Node: Fields195738 -Ref: Fields-Footnote-1198702 -Node: Nonconstant Fields198788 -Ref: Nonconstant Fields-Footnote-1201018 -Node: Changing Fields201220 -Node: Field Separators207174 -Node: Default Field Splitting209876 -Node: Regexp Field Splitting210993 -Node: Single Character Fields214334 -Node: Command Line Field Separator215393 -Node: Full Line Fields218735 -Ref: Full Line Fields-Footnote-1219243 -Node: Field Splitting Summary219289 -Ref: Field Splitting Summary-Footnote-1222388 -Node: Constant Size222489 -Node: Splitting By Content227096 -Ref: Splitting By Content-Footnote-1230846 -Node: Multiple Line230886 -Ref: Multiple Line-Footnote-1236742 -Node: Getline236921 -Node: Plain Getline239137 -Node: Getline/Variable241232 -Node: Getline/File242379 -Node: Getline/Variable/File243763 -Ref: Getline/Variable/File-Footnote-1245362 -Node: Getline/Pipe245449 -Node: Getline/Variable/Pipe248148 -Node: Getline/Coprocess249255 -Node: Getline/Variable/Coprocess250507 -Node: Getline Notes251244 -Node: Getline Summary254048 -Ref: table-getline-variants254456 -Node: Read Timeout255368 -Ref: Read Timeout-Footnote-1259195 -Node: Command line directories259253 -Node: Input Summary260157 -Node: Input Exercises263294 -Node: Printing264027 -Node: Print265749 -Node: Print Examples267090 -Node: Output Separators269869 -Node: OFMT271885 -Node: Printf273243 -Node: Basic Printf274149 -Node: Control Letters275688 -Node: Format Modifiers279679 -Node: Printf Examples285706 -Node: Redirection288170 -Node: Special Files295142 -Node: Special FD295673 -Ref: Special FD-Footnote-1299270 -Node: Special Network299344 -Node: Special Caveats300194 -Node: Close Files And Pipes300990 -Ref: Close Files And Pipes-Footnote-1308151 -Ref: Close Files And Pipes-Footnote-2308299 -Node: Output Summary308449 -Node: Output exercises309446 -Node: Expressions310126 -Node: Values311311 -Node: Constants311987 -Node: Scalar Constants312667 -Ref: Scalar Constants-Footnote-1313526 -Node: Nondecimal-numbers313776 -Node: Regexp Constants316776 -Node: Using Constant Regexps317251 -Node: Variables320321 -Node: Using Variables320976 -Node: Assignment Options322700 -Node: Conversion324575 -Node: Strings And Numbers325099 -Ref: Strings And Numbers-Footnote-1328161 -Node: Locale influences conversions328270 -Ref: table-locale-affects330987 -Node: All Operators331575 -Node: Arithmetic Ops332205 -Node: Concatenation334710 -Ref: Concatenation-Footnote-1337529 -Node: Assignment Ops337649 -Ref: table-assign-ops342632 -Node: Increment Ops343949 -Node: Truth Values and Conditions347387 -Node: Truth Values348470 -Node: Typing and Comparison349519 -Node: Variable Typing350312 -Node: Comparison Operators353962 -Ref: table-relational-ops354372 -Node: POSIX String Comparison357922 -Ref: POSIX String Comparison-Footnote-1359006 -Node: Boolean Ops359144 -Ref: Boolean Ops-Footnote-1363214 -Node: Conditional Exp363305 -Node: Function Calls365032 -Node: Precedence368912 -Node: Locales372581 -Node: Expressions Summary374212 -Node: Patterns and Actions376753 -Node: Pattern Overview377869 -Node: Regexp Patterns379546 -Node: Expression Patterns380089 -Node: Ranges383870 -Node: BEGIN/END386976 -Node: Using BEGIN/END387738 -Ref: Using BEGIN/END-Footnote-1390474 -Node: I/O And BEGIN/END390580 -Node: BEGINFILE/ENDFILE392865 -Node: Empty395796 -Node: Using Shell Variables396113 -Node: Action Overview398396 -Node: Statements400723 -Node: If Statement402571 -Node: While Statement404069 -Node: Do Statement406113 -Node: For Statement407269 -Node: Switch Statement410421 -Node: Break Statement412524 -Node: Continue Statement414579 -Node: Next Statement416372 -Node: Nextfile Statement418762 -Node: Exit Statement421417 -Node: Built-in Variables423821 -Node: User-modified424948 -Ref: User-modified-Footnote-1432637 -Node: Auto-set432699 -Ref: Auto-set-Footnote-1445618 -Ref: Auto-set-Footnote-2445823 -Node: ARGC and ARGV445879 -Node: Pattern Action Summary449733 -Node: Arrays451956 -Node: Array Basics453505 -Node: Array Intro454331 -Ref: figure-array-elements456304 -Node: Reference to Elements458711 -Node: Assigning Elements460984 -Node: Array Example461475 -Node: Scanning an Array463207 -Node: Controlling Scanning466222 -Ref: Controlling Scanning-Footnote-1471395 -Node: Delete471711 -Ref: Delete-Footnote-1474476 -Node: Numeric Array Subscripts474533 -Node: Uninitialized Subscripts476716 -Node: Multidimensional478341 -Node: Multiscanning481434 -Node: Arrays of Arrays483023 -Node: Arrays Summary487686 -Node: Functions489791 -Node: Built-in490664 -Node: Calling Built-in491742 -Node: Numeric Functions493730 -Ref: Numeric Functions-Footnote-1498474 -Ref: Numeric Functions-Footnote-2498831 -Ref: Numeric Functions-Footnote-3498879 -Node: String Functions499148 -Ref: String Functions-Footnote-1522159 -Ref: String Functions-Footnote-2522288 -Ref: String Functions-Footnote-3522536 -Node: Gory Details522623 -Ref: table-sub-escapes524292 -Ref: table-sub-posix-92525646 -Ref: table-sub-proposed526997 -Ref: table-posix-sub528351 -Ref: table-gensub-escapes529896 -Ref: Gory Details-Footnote-1531072 -Ref: Gory Details-Footnote-2531123 -Node: I/O Functions531274 -Ref: I/O Functions-Footnote-1538397 -Node: Time Functions538544 -Ref: Time Functions-Footnote-1549008 -Ref: Time Functions-Footnote-2549076 -Ref: Time Functions-Footnote-3549234 -Ref: Time Functions-Footnote-4549345 -Ref: Time Functions-Footnote-5549457 -Ref: Time Functions-Footnote-6549684 -Node: Bitwise Functions549950 -Ref: table-bitwise-ops550512 -Ref: Bitwise Functions-Footnote-1554757 -Node: Type Functions554941 -Node: I18N Functions556083 -Node: User-defined557728 -Node: Definition Syntax558532 -Ref: Definition Syntax-Footnote-1563711 -Node: Function Example563780 -Ref: Function Example-Footnote-1566424 -Node: Function Caveats566446 -Node: Calling A Function566964 -Node: Variable Scope567919 -Node: Pass By Value/Reference570907 -Node: Return Statement574415 -Node: Dynamic Typing577399 -Node: Indirect Calls578328 -Node: Functions Summary588041 -Node: Library Functions590580 -Ref: Library Functions-Footnote-1594198 -Ref: Library Functions-Footnote-2594341 -Node: Library Names594512 -Ref: Library Names-Footnote-1597985 -Ref: Library Names-Footnote-2598205 -Node: General Functions598291 -Node: Strtonum Function599319 -Node: Assert Function602099 -Node: Round Function605425 -Node: Cliff Random Function606966 -Node: Ordinal Functions607982 -Ref: Ordinal Functions-Footnote-1611059 -Ref: Ordinal Functions-Footnote-2611311 -Node: Join Function611522 -Ref: Join Function-Footnote-1613293 -Node: Getlocaltime Function613493 -Node: Readfile Function617229 -Node: Data File Management619068 -Node: Filetrans Function619700 -Node: Rewind Function623769 -Node: File Checking625327 -Ref: File Checking-Footnote-1626459 -Node: Empty Files626660 -Node: Ignoring Assigns628639 -Node: Getopt Function630193 -Ref: Getopt Function-Footnote-1641496 -Node: Passwd Functions641699 -Ref: Passwd Functions-Footnote-1650678 -Node: Group Functions650766 -Ref: Group Functions-Footnote-1658707 -Node: Walking Arrays658920 -Node: Library Functions Summary660523 -Node: Library exercises661911 -Node: Sample Programs663191 -Node: Running Examples663961 -Node: Clones664689 -Node: Cut Program665913 -Node: Egrep Program675781 -Ref: Egrep Program-Footnote-1683752 -Node: Id Program683862 -Node: Split Program687526 -Ref: Split Program-Footnote-1691064 -Node: Tee Program691192 -Node: Uniq Program693999 -Node: Wc Program701429 -Ref: Wc Program-Footnote-1705694 -Node: Miscellaneous Programs705786 -Node: Dupword Program706999 -Node: Alarm Program709030 -Node: Translate Program713844 -Ref: Translate Program-Footnote-1718235 -Ref: Translate Program-Footnote-2718505 -Node: Labels Program718639 -Ref: Labels Program-Footnote-1722010 -Node: Word Sorting722094 -Node: History Sorting726137 -Node: Extract Program727973 -Node: Simple Sed735509 -Node: Igawk Program738571 -Ref: Igawk Program-Footnote-1752882 -Ref: Igawk Program-Footnote-2753083 -Node: Anagram Program753221 -Node: Signature Program756289 -Node: Programs Summary757536 -Node: Programs Exercises758751 -Node: Advanced Features762402 -Node: Nondecimal Data764350 -Node: Array Sorting765927 -Node: Controlling Array Traversal766624 -Node: Array Sorting Functions774904 -Ref: Array Sorting Functions-Footnote-1778811 -Node: Two-way I/O779005 -Ref: Two-way I/O-Footnote-1784521 -Node: TCP/IP Networking784603 -Node: Profiling787447 -Node: Advanced Features Summary794998 -Node: Internationalization796862 -Node: I18N and L10N798342 -Node: Explaining gettext799028 -Ref: Explaining gettext-Footnote-1804168 -Ref: Explaining gettext-Footnote-2804352 -Node: Programmer i18n804517 -Node: Translator i18n808742 -Node: String Extraction809536 -Ref: String Extraction-Footnote-1810497 -Node: Printf Ordering810583 -Ref: Printf Ordering-Footnote-1813365 -Node: I18N Portability813429 -Ref: I18N Portability-Footnote-1815878 -Node: I18N Example815941 -Ref: I18N Example-Footnote-1818663 -Node: Gawk I18N818735 -Node: I18N Summary819373 -Node: Debugger820712 -Node: Debugging821734 -Node: Debugging Concepts822175 -Node: Debugging Terms824031 -Node: Awk Debugging826628 -Node: Sample Debugging Session827520 -Node: Debugger Invocation828040 -Node: Finding The Bug829373 -Node: List of Debugger Commands835855 -Node: Breakpoint Control837187 -Node: Debugger Execution Control840851 -Node: Viewing And Changing Data844211 -Node: Execution Stack847569 -Node: Debugger Info849082 -Node: Miscellaneous Debugger Commands853076 -Node: Readline Support858260 -Node: Limitations859152 -Node: Debugging Summary861426 -Node: Arbitrary Precision Arithmetic862590 -Node: Computer Arithmetic863919 -Ref: Computer Arithmetic-Footnote-1868306 -Node: Math Definitions868363 -Ref: table-ieee-formats871247 -Node: MPFR features871751 -Node: FP Math Caution873393 -Ref: FP Math Caution-Footnote-1874434 -Node: Inexactness of computations874803 -Node: Inexact representation875751 -Node: Comparing FP Values877106 -Node: Errors accumulate878070 -Node: Getting Accuracy879503 -Node: Try To Round882162 -Node: Setting precision883061 -Ref: table-predefined-precision-strings883743 -Node: Setting the rounding mode885536 -Ref: table-gawk-rounding-modes885900 -Ref: Setting the rounding mode-Footnote-1889354 -Node: Arbitrary Precision Integers889533 -Ref: Arbitrary Precision Integers-Footnote-1893328 -Node: POSIX Floating Point Problems893477 -Ref: POSIX Floating Point Problems-Footnote-1897353 -Node: Floating point summary897391 -Node: Dynamic Extensions899608 -Node: Extension Intro901160 -Node: Plugin License902425 -Node: Extension Mechanism Outline903110 -Ref: figure-load-extension903534 -Ref: figure-load-new-function905019 -Ref: figure-call-new-function906021 -Node: Extension API Description908005 -Node: Extension API Functions Introduction909455 -Node: General Data Types914320 -Ref: General Data Types-Footnote-1920013 -Node: Requesting Values920312 -Ref: table-value-types-returned921049 -Node: Memory Allocation Functions922007 -Ref: Memory Allocation Functions-Footnote-1924754 -Node: Constructor Functions924850 -Node: Registration Functions926608 -Node: Extension Functions927293 -Node: Exit Callback Functions929595 -Node: Extension Version String930844 -Node: Input Parsers931494 -Node: Output Wrappers941308 -Node: Two-way processors945824 -Node: Printing Messages948028 -Ref: Printing Messages-Footnote-1949105 -Node: Updating `ERRNO'949257 -Node: Accessing Parameters949996 -Node: Symbol Table Access951226 -Node: Symbol table by name951740 -Node: Symbol table by cookie953716 -Ref: Symbol table by cookie-Footnote-1957849 -Node: Cached values957912 -Ref: Cached values-Footnote-1961416 -Node: Array Manipulation961507 -Ref: Array Manipulation-Footnote-1962605 -Node: Array Data Types962644 -Ref: Array Data Types-Footnote-1965347 -Node: Array Functions965439 -Node: Flattening Arrays969313 -Node: Creating Arrays976165 -Node: Extension API Variables980896 -Node: Extension Versioning981532 -Node: Extension API Informational Variables983433 -Node: Extension API Boilerplate984519 -Node: Finding Extensions988323 -Node: Extension Example988883 -Node: Internal File Description989613 -Node: Internal File Ops993704 -Ref: Internal File Ops-Footnote-11005136 -Node: Using Internal File Ops1005276 -Ref: Using Internal File Ops-Footnote-11007623 -Node: Extension Samples1007891 -Node: Extension Sample File Functions1009415 -Node: Extension Sample Fnmatch1016983 -Node: Extension Sample Fork1018465 -Node: Extension Sample Inplace1019678 -Node: Extension Sample Ord1021353 -Node: Extension Sample Readdir1022189 -Ref: table-readdir-file-types1023045 -Node: Extension Sample Revout1023844 -Node: Extension Sample Rev2way1024435 -Node: Extension Sample Read write array1025176 -Node: Extension Sample Readfile1027055 -Node: Extension Sample API Tests1028155 -Node: Extension Sample Time1028680 -Node: gawkextlib1029995 -Node: Extension summary1032808 -Node: Extension Exercises1036501 -Node: Language History1037223 -Node: V7/SVR3.11038866 -Node: SVR41041186 -Node: POSIX1042628 -Node: BTL1044014 -Node: POSIX/GNU1044748 -Node: Feature History1050491 -Node: Common Extensions1063621 -Node: Ranges and Locales1064933 -Ref: Ranges and Locales-Footnote-11069550 -Ref: Ranges and Locales-Footnote-21069577 -Ref: Ranges and Locales-Footnote-31069811 -Node: Contributors1070032 -Node: History summary1075457 -Node: Installation1076826 -Node: Gawk Distribution1077777 -Node: Getting1078261 -Node: Extracting1079085 -Node: Distribution contents1080727 -Node: Unix Installation1086497 -Node: Quick Installation1087114 -Node: Additional Configuration Options1089556 -Node: Configuration Philosophy1091294 -Node: Non-Unix Installation1093645 -Node: PC Installation1094103 -Node: PC Binary Installation1095414 -Node: PC Compiling1097262 -Ref: PC Compiling-Footnote-11100261 -Node: PC Testing1100366 -Node: PC Using1101542 -Node: Cygwin1105700 -Node: MSYS1106509 -Node: VMS Installation1107023 -Node: VMS Compilation1107819 -Ref: VMS Compilation-Footnote-11109041 -Node: VMS Dynamic Extensions1109099 -Node: VMS Installation Details1110472 -Node: VMS Running1112724 -Node: VMS GNV1115558 -Node: VMS Old Gawk1116281 -Node: Bugs1116751 -Node: Other Versions1120755 -Node: Installation summary1127010 -Node: Notes1128066 -Node: Compatibility Mode1128931 -Node: Additions1129713 -Node: Accessing The Source1130638 -Node: Adding Code1132074 -Node: New Ports1138252 -Node: Derived Files1142733 -Ref: Derived Files-Footnote-11147814 -Ref: Derived Files-Footnote-21147848 -Ref: Derived Files-Footnote-31148444 -Node: Future Extensions1148558 -Node: Implementation Limitations1149164 -Node: Extension Design1150412 -Node: Old Extension Problems1151566 -Ref: Old Extension Problems-Footnote-11153083 -Node: Extension New Mechanism Goals1153140 -Ref: Extension New Mechanism Goals-Footnote-11156500 -Node: Extension Other Design Decisions1156689 -Node: Extension Future Growth1158795 -Node: Old Extension Mechanism1159631 -Node: Notes summary1161393 -Node: Basic Concepts1162579 -Node: Basic High Level1163260 -Ref: figure-general-flow1163532 -Ref: figure-process-flow1164131 -Ref: Basic High Level-Footnote-11167360 -Node: Basic Data Typing1167545 -Node: Glossary1170873 -Node: Copying1196025 -Node: GNU Free Documentation License1233581 -Node: Index1258717 +Ref: Read Terminal-Footnote-177628 +Node: Long77799 +Node: Executable Scripts79175 +Ref: Executable Scripts-Footnote-181008 +Ref: Executable Scripts-Footnote-281110 +Node: Comments81657 +Node: Quoting84130 +Node: DOS Quoting89443 +Node: Sample Data Files90118 +Node: Very Simple92672 +Node: Two Rules97445 +Node: More Complex99339 +Ref: More Complex-Footnote-1102271 +Node: Statements/Lines102356 +Ref: Statements/Lines-Footnote-1106812 +Node: Other Features107077 +Node: When108005 +Node: Intro Summary110175 +Node: Invoking Gawk110941 +Node: Command Line112456 +Node: Options113247 +Ref: Options-Footnote-1128947 +Node: Other Arguments128972 +Node: Naming Standard Input131634 +Node: Environment Variables132727 +Node: AWKPATH Variable133285 +Ref: AWKPATH Variable-Footnote-1136157 +Ref: AWKPATH Variable-Footnote-2136202 +Node: AWKLIBPATH Variable136462 +Node: Other Environment Variables137221 +Node: Exit Status140673 +Node: Include Files141348 +Node: Loading Shared Libraries144926 +Node: Obsolete146310 +Node: Undocumented147007 +Node: Invoking Summary147274 +Node: Regexp148874 +Node: Regexp Usage150324 +Node: Escape Sequences152357 +Node: Regexp Operators158024 +Ref: Regexp Operators-Footnote-1165504 +Ref: Regexp Operators-Footnote-2165651 +Node: Bracket Expressions165749 +Ref: table-char-classes167639 +Node: GNU Regexp Operators170579 +Node: Case-sensitivity174302 +Ref: Case-sensitivity-Footnote-1177194 +Ref: Case-sensitivity-Footnote-2177429 +Node: Leftmost Longest177537 +Node: Computed Regexps178738 +Node: Regexp Summary182110 +Node: Reading Files183579 +Node: Records185671 +Node: awk split records186414 +Node: gawk split records191272 +Ref: gawk split records-Footnote-1195793 +Node: Fields195830 +Ref: Fields-Footnote-1198794 +Node: Nonconstant Fields198880 +Ref: Nonconstant Fields-Footnote-1201110 +Node: Changing Fields201312 +Node: Field Separators207266 +Node: Default Field Splitting209968 +Node: Regexp Field Splitting211085 +Node: Single Character Fields214426 +Node: Command Line Field Separator215485 +Node: Full Line Fields218827 +Ref: Full Line Fields-Footnote-1219335 +Node: Field Splitting Summary219381 +Ref: Field Splitting Summary-Footnote-1222480 +Node: Constant Size222581 +Node: Splitting By Content227188 +Ref: Splitting By Content-Footnote-1230938 +Node: Multiple Line230978 +Ref: Multiple Line-Footnote-1236834 +Node: Getline237013 +Node: Plain Getline239229 +Node: Getline/Variable241324 +Node: Getline/File242471 +Node: Getline/Variable/File243855 +Ref: Getline/Variable/File-Footnote-1245454 +Node: Getline/Pipe245541 +Node: Getline/Variable/Pipe248240 +Node: Getline/Coprocess249347 +Node: Getline/Variable/Coprocess250599 +Node: Getline Notes251336 +Node: Getline Summary254140 +Ref: table-getline-variants254548 +Node: Read Timeout255460 +Ref: Read Timeout-Footnote-1259287 +Node: Command-line directories259345 +Node: Input Summary260249 +Node: Input Exercises263386 +Node: Printing264119 +Node: Print265841 +Node: Print Examples267182 +Node: Output Separators269961 +Node: OFMT271977 +Node: Printf273335 +Node: Basic Printf274241 +Node: Control Letters275780 +Node: Format Modifiers279771 +Node: Printf Examples285798 +Node: Redirection288262 +Node: Special Files295234 +Node: Special FD295765 +Ref: Special FD-Footnote-1299362 +Node: Special Network299436 +Node: Special Caveats300286 +Node: Close Files And Pipes301082 +Ref: Close Files And Pipes-Footnote-1308243 +Ref: Close Files And Pipes-Footnote-2308391 +Node: Output Summary308541 +Node: Output exercises309538 +Node: Expressions310218 +Node: Values311403 +Node: Constants312079 +Node: Scalar Constants312759 +Ref: Scalar Constants-Footnote-1313618 +Node: Nondecimal-numbers313868 +Node: Regexp Constants316868 +Node: Using Constant Regexps317343 +Node: Variables320415 +Node: Using Variables321070 +Node: Assignment Options322794 +Node: Conversion324669 +Node: Strings And Numbers325193 +Ref: Strings And Numbers-Footnote-1328255 +Node: Locale influences conversions328364 +Ref: table-locale-affects331081 +Node: All Operators331669 +Node: Arithmetic Ops332299 +Node: Concatenation334804 +Ref: Concatenation-Footnote-1337623 +Node: Assignment Ops337743 +Ref: table-assign-ops342726 +Node: Increment Ops344043 +Node: Truth Values and Conditions347481 +Node: Truth Values348564 +Node: Typing and Comparison349613 +Node: Variable Typing350406 +Node: Comparison Operators354056 +Ref: table-relational-ops354466 +Node: POSIX String Comparison358016 +Ref: POSIX String Comparison-Footnote-1359100 +Node: Boolean Ops359238 +Ref: Boolean Ops-Footnote-1363308 +Node: Conditional Exp363399 +Node: Function Calls365126 +Node: Precedence369006 +Node: Locales372675 +Node: Expressions Summary374306 +Node: Patterns and Actions376847 +Node: Pattern Overview377963 +Node: Regexp Patterns379640 +Node: Expression Patterns380183 +Node: Ranges383964 +Node: BEGIN/END387070 +Node: Using BEGIN/END387832 +Ref: Using BEGIN/END-Footnote-1390568 +Node: I/O And BEGIN/END390674 +Node: BEGINFILE/ENDFILE392959 +Node: Empty395890 +Node: Using Shell Variables396207 +Node: Action Overview398490 +Node: Statements400817 +Node: If Statement402665 +Node: While Statement404163 +Node: Do Statement406207 +Node: For Statement407363 +Node: Switch Statement410515 +Node: Break Statement412618 +Node: Continue Statement414673 +Node: Next Statement416466 +Node: Nextfile Statement418856 +Node: Exit Statement421511 +Node: Built-in Variables423915 +Node: User-modified425042 +Ref: User-modified-Footnote-1432731 +Node: Auto-set432793 +Ref: Auto-set-Footnote-1445712 +Ref: Auto-set-Footnote-2445917 +Node: ARGC and ARGV445973 +Node: Pattern Action Summary449827 +Node: Arrays452050 +Node: Array Basics453599 +Node: Array Intro454425 +Ref: figure-array-elements456398 +Node: Reference to Elements458805 +Node: Assigning Elements461078 +Node: Array Example461569 +Node: Scanning an Array463301 +Node: Controlling Scanning466316 +Ref: Controlling Scanning-Footnote-1471489 +Node: Delete471805 +Ref: Delete-Footnote-1474570 +Node: Numeric Array Subscripts474627 +Node: Uninitialized Subscripts476810 +Node: Multidimensional478435 +Node: Multiscanning481528 +Node: Arrays of Arrays483117 +Node: Arrays Summary487780 +Node: Functions489885 +Node: Built-in490758 +Node: Calling Built-in491836 +Node: Numeric Functions493824 +Ref: Numeric Functions-Footnote-1498568 +Ref: Numeric Functions-Footnote-2498925 +Ref: Numeric Functions-Footnote-3498973 +Node: String Functions499242 +Ref: String Functions-Footnote-1522253 +Ref: String Functions-Footnote-2522382 +Ref: String Functions-Footnote-3522630 +Node: Gory Details522717 +Ref: table-sub-escapes524504 +Ref: table-sub-proposed526024 +Ref: table-posix-sub527388 +Ref: table-gensub-escapes528928 +Ref: Gory Details-Footnote-1530104 +Node: I/O Functions530255 +Ref: I/O Functions-Footnote-1537378 +Node: Time Functions537525 +Ref: Time Functions-Footnote-1547989 +Ref: Time Functions-Footnote-2548057 +Ref: Time Functions-Footnote-3548215 +Ref: Time Functions-Footnote-4548326 +Ref: Time Functions-Footnote-5548438 +Ref: Time Functions-Footnote-6548665 +Node: Bitwise Functions548931 +Ref: table-bitwise-ops549493 +Ref: Bitwise Functions-Footnote-1553738 +Node: Type Functions553922 +Node: I18N Functions555064 +Node: User-defined556709 +Node: Definition Syntax557513 +Ref: Definition Syntax-Footnote-1562692 +Node: Function Example562761 +Ref: Function Example-Footnote-1565325 +Node: Function Caveats565347 +Node: Calling A Function565865 +Node: Variable Scope566820 +Node: Pass By Value/Reference569808 +Node: Return Statement573318 +Node: Dynamic Typing576302 +Node: Indirect Calls577231 +Node: Functions Summary586944 +Node: Library Functions589483 +Ref: Library Functions-Footnote-1593101 +Ref: Library Functions-Footnote-2593244 +Node: Library Names593415 +Ref: Library Names-Footnote-1596888 +Ref: Library Names-Footnote-2597108 +Node: General Functions597194 +Node: Strtonum Function598222 +Node: Assert Function601002 +Node: Round Function604328 +Node: Cliff Random Function605869 +Node: Ordinal Functions606885 +Ref: Ordinal Functions-Footnote-1609962 +Ref: Ordinal Functions-Footnote-2610214 +Node: Join Function610425 +Ref: Join Function-Footnote-1612196 +Node: Getlocaltime Function612396 +Node: Readfile Function616132 +Node: Data File Management617971 +Node: Filetrans Function618603 +Node: Rewind Function622672 +Node: File Checking624230 +Ref: File Checking-Footnote-1625362 +Node: Empty Files625563 +Node: Ignoring Assigns627542 +Node: Getopt Function629096 +Ref: Getopt Function-Footnote-1640399 +Node: Passwd Functions640602 +Ref: Passwd Functions-Footnote-1649581 +Node: Group Functions649669 +Ref: Group Functions-Footnote-1657610 +Node: Walking Arrays657823 +Node: Library Functions Summary659426 +Node: Library exercises660814 +Node: Sample Programs662094 +Node: Running Examples662864 +Node: Clones663592 +Node: Cut Program664816 +Node: Egrep Program674684 +Ref: Egrep Program-Footnote-1682655 +Node: Id Program682765 +Node: Split Program686429 +Ref: Split Program-Footnote-1689967 +Node: Tee Program690095 +Node: Uniq Program692902 +Node: Wc Program700332 +Ref: Wc Program-Footnote-1704597 +Node: Miscellaneous Programs704689 +Node: Dupword Program705902 +Node: Alarm Program707933 +Node: Translate Program712747 +Ref: Translate Program-Footnote-1717138 +Ref: Translate Program-Footnote-2717408 +Node: Labels Program717542 +Ref: Labels Program-Footnote-1720913 +Node: Word Sorting720997 +Node: History Sorting725040 +Node: Extract Program726876 +Node: Simple Sed734412 +Node: Igawk Program737474 +Ref: Igawk Program-Footnote-1751785 +Ref: Igawk Program-Footnote-2751986 +Node: Anagram Program752124 +Node: Signature Program755192 +Node: Programs Summary756439 +Node: Programs Exercises757654 +Node: Advanced Features761305 +Node: Nondecimal Data763253 +Node: Array Sorting764830 +Node: Controlling Array Traversal765527 +Node: Array Sorting Functions773807 +Ref: Array Sorting Functions-Footnote-1777714 +Node: Two-way I/O777908 +Ref: Two-way I/O-Footnote-1782852 +Ref: Two-way I/O-Footnote-2783031 +Node: TCP/IP Networking783113 +Node: Profiling785958 +Node: Advanced Features Summary793509 +Node: Internationalization795373 +Node: I18N and L10N796853 +Node: Explaining gettext797539 +Ref: Explaining gettext-Footnote-1802679 +Ref: Explaining gettext-Footnote-2802863 +Node: Programmer i18n803028 +Node: Translator i18n807253 +Node: String Extraction808047 +Ref: String Extraction-Footnote-1809008 +Node: Printf Ordering809094 +Ref: Printf Ordering-Footnote-1811876 +Node: I18N Portability811940 +Ref: I18N Portability-Footnote-1814389 +Node: I18N Example814452 +Ref: I18N Example-Footnote-1817174 +Node: Gawk I18N817246 +Node: I18N Summary817884 +Node: Debugger819223 +Node: Debugging820245 +Node: Debugging Concepts820686 +Node: Debugging Terms822542 +Node: Awk Debugging825139 +Node: Sample Debugging Session826031 +Node: Debugger Invocation826551 +Node: Finding The Bug827884 +Node: List of Debugger Commands834366 +Node: Breakpoint Control835698 +Node: Debugger Execution Control839362 +Node: Viewing And Changing Data842722 +Node: Execution Stack846080 +Node: Debugger Info847593 +Node: Miscellaneous Debugger Commands851587 +Node: Readline Support856771 +Node: Limitations857663 +Node: Debugging Summary859937 +Node: Arbitrary Precision Arithmetic861101 +Node: Computer Arithmetic862588 +Ref: Computer Arithmetic-Footnote-1866975 +Node: Math Definitions867032 +Ref: table-ieee-formats870321 +Ref: Math Definitions-Footnote-1870861 +Node: MPFR features870964 +Node: FP Math Caution872606 +Ref: FP Math Caution-Footnote-1873647 +Node: Inexactness of computations874016 +Node: Inexact representation874964 +Node: Comparing FP Values876319 +Node: Errors accumulate877283 +Node: Getting Accuracy878716 +Node: Try To Round881375 +Node: Setting precision882274 +Ref: table-predefined-precision-strings882956 +Node: Setting the rounding mode884749 +Ref: table-gawk-rounding-modes885113 +Ref: Setting the rounding mode-Footnote-1888567 +Node: Arbitrary Precision Integers888746 +Ref: Arbitrary Precision Integers-Footnote-1892541 +Node: POSIX Floating Point Problems892690 +Ref: POSIX Floating Point Problems-Footnote-1896566 +Node: Floating point summary896604 +Node: Dynamic Extensions898821 +Node: Extension Intro900373 +Node: Plugin License901638 +Node: Extension Mechanism Outline902323 +Ref: figure-load-extension902747 +Ref: figure-load-new-function904232 +Ref: figure-call-new-function905234 +Node: Extension API Description907218 +Node: Extension API Functions Introduction908668 +Node: General Data Types913533 +Ref: General Data Types-Footnote-1919226 +Node: Requesting Values919525 +Ref: table-value-types-returned920262 +Node: Memory Allocation Functions921220 +Ref: Memory Allocation Functions-Footnote-1923967 +Node: Constructor Functions924063 +Node: Registration Functions925821 +Node: Extension Functions926506 +Node: Exit Callback Functions928808 +Node: Extension Version String930057 +Node: Input Parsers930707 +Node: Output Wrappers940521 +Node: Two-way processors945037 +Node: Printing Messages947241 +Ref: Printing Messages-Footnote-1948318 +Node: Updating `ERRNO'948470 +Node: Accessing Parameters949209 +Node: Symbol Table Access950439 +Node: Symbol table by name950953 +Node: Symbol table by cookie952929 +Ref: Symbol table by cookie-Footnote-1957062 +Node: Cached values957125 +Ref: Cached values-Footnote-1960629 +Node: Array Manipulation960720 +Ref: Array Manipulation-Footnote-1961818 +Node: Array Data Types961857 +Ref: Array Data Types-Footnote-1964560 +Node: Array Functions964652 +Node: Flattening Arrays968526 +Node: Creating Arrays975378 +Node: Extension API Variables980109 +Node: Extension Versioning980745 +Node: Extension API Informational Variables982646 +Node: Extension API Boilerplate983732 +Node: Finding Extensions987536 +Node: Extension Example988096 +Node: Internal File Description988826 +Node: Internal File Ops992917 +Ref: Internal File Ops-Footnote-11004349 +Node: Using Internal File Ops1004489 +Ref: Using Internal File Ops-Footnote-11006836 +Node: Extension Samples1007104 +Node: Extension Sample File Functions1008628 +Node: Extension Sample Fnmatch1016196 +Node: Extension Sample Fork1017678 +Node: Extension Sample Inplace1018891 +Node: Extension Sample Ord1020566 +Node: Extension Sample Readdir1021402 +Ref: table-readdir-file-types1022258 +Node: Extension Sample Revout1023057 +Node: Extension Sample Rev2way1023648 +Node: Extension Sample Read write array1024389 +Node: Extension Sample Readfile1026268 +Node: Extension Sample API Tests1027368 +Node: Extension Sample Time1027893 +Node: gawkextlib1029208 +Node: Extension summary1032021 +Node: Extension Exercises1035714 +Node: Language History1036436 +Node: V7/SVR3.11038079 +Node: SVR41040399 +Node: POSIX1041841 +Node: BTL1043227 +Node: POSIX/GNU1043961 +Node: Feature History1049704 +Node: Common Extensions1062834 +Node: Ranges and Locales1064146 +Ref: Ranges and Locales-Footnote-11068763 +Ref: Ranges and Locales-Footnote-21068790 +Ref: Ranges and Locales-Footnote-31069024 +Node: Contributors1069245 +Node: History summary1074670 +Node: Installation1076039 +Node: Gawk Distribution1076990 +Node: Getting1077474 +Node: Extracting1078298 +Node: Distribution contents1079940 +Node: Unix Installation1085710 +Node: Quick Installation1086327 +Node: Additional Configuration Options1088769 +Node: Configuration Philosophy1090507 +Node: Non-Unix Installation1092858 +Node: PC Installation1093316 +Node: PC Binary Installation1094627 +Node: PC Compiling1096475 +Ref: PC Compiling-Footnote-11099474 +Node: PC Testing1099579 +Node: PC Using1100755 +Node: Cygwin1104913 +Node: MSYS1105722 +Node: VMS Installation1106236 +Node: VMS Compilation1107032 +Ref: VMS Compilation-Footnote-11108254 +Node: VMS Dynamic Extensions1108312 +Node: VMS Installation Details1109685 +Node: VMS Running1111937 +Node: VMS GNV1114771 +Node: VMS Old Gawk1115494 +Node: Bugs1115964 +Node: Other Versions1119968 +Node: Installation summary1126223 +Node: Notes1127279 +Node: Compatibility Mode1128144 +Node: Additions1128926 +Node: Accessing The Source1129851 +Node: Adding Code1131287 +Node: New Ports1137465 +Node: Derived Files1141946 +Ref: Derived Files-Footnote-11147027 +Ref: Derived Files-Footnote-21147061 +Ref: Derived Files-Footnote-31147657 +Node: Future Extensions1147771 +Node: Implementation Limitations1148377 +Node: Extension Design1149625 +Node: Old Extension Problems1150779 +Ref: Old Extension Problems-Footnote-11152296 +Node: Extension New Mechanism Goals1152353 +Ref: Extension New Mechanism Goals-Footnote-11155713 +Node: Extension Other Design Decisions1155902 +Node: Extension Future Growth1158008 +Node: Old Extension Mechanism1158844 +Node: Notes summary1160606 +Node: Basic Concepts1161792 +Node: Basic High Level1162473 +Ref: figure-general-flow1162745 +Ref: figure-process-flow1163344 +Ref: Basic High Level-Footnote-11166573 +Node: Basic Data Typing1166758 +Node: Glossary1170086 +Node: Copying1195238 +Node: GNU Free Documentation License1232794 +Node: Index1257930 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index d8d8132a..c0b979d1 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -51,7 +51,7 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH July, 2014 +@set UPDATE-MONTH August, 2014 @set VERSION 4.1 @set PATCHLEVEL 1 @@ -546,7 +546,7 @@ particular records in a file and perform operations upon them. * Single Character Fields:: Making each character a separate field. * Command Line Field Separator:: Setting @code{FS} from the - command-line. + command line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -572,7 +572,7 @@ particular records in a file and perform operations upon them. @code{getline}. * Getline Summary:: Summary of @code{getline} Variants. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -611,7 +611,7 @@ particular records in a file and perform operations upon them. * Variables:: Variables give names to values for later use. * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. * Conversion:: The conversion of strings to numbers @@ -1404,7 +1404,7 @@ help from me, thoroughly reworked @command{gawk} for compatibility with the newer @command{awk}. Circa 1994, I became the primary maintainer. Current development focuses on bug fixes, -performance improvements, standards compliance, and occasionally, new features. +performance improvements, standards compliance and, occasionally, new features. In May of 1997, J@"urgen Kahrs felt the need for network access from @command{awk}, and with a little help from me, set about adding @@ -1697,7 +1697,7 @@ are slightly different than in other books you may have read. This @value{SECTION} briefly documents the typographical conventions used in Texinfo. @end ifinfo -Examples you would type at the command-line are preceded by the common +Examples you would type at the command line are preceded by the common shell primary and secondary prompts, @samp{$} and @samp{>}. Input that you type is shown @kbd{like this}. Output from the command is preceded by the glyph ``@print{}''. @@ -2335,12 +2335,7 @@ 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@footnote{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 startup file.} -(@code{BEGIN} is a feature we haven't discussed yet): +programming (@code{BEGIN} is a feature we haven't discussed yet): @example $ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} @@ -2359,6 +2354,14 @@ 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.} +@quotation NOTE +As a side note, 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 +startup file. +@end quotation + This next simple @command{awk} program emulates the @command{cat} utility; it copies whatever you type on the keyboard to its standard output (why this works is explained shortly). @@ -2715,7 +2718,7 @@ Note that the single quote is not special within double quotes. @item Null strings are removed when they occur as part of a non-null -command-line argument, while explicit non-null objects are kept. +command-line argument, while explicit null objects are kept. For example, to specify that the field separator @code{FS} should be set to the null string, use: @@ -2862,7 +2865,9 @@ each line is considered to be one @dfn{record}. In the @value{DF} @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. An @samp{A} in the last column +with the author of the list. +The columns are aligned using spaces. +An @samp{A} in the last column means that the person is an acquaintance. An @samp{F} in the last column means that the person is a friend. An @samp{R} means that the person is a relative: @@ -3780,7 +3785,7 @@ Second, because this option is intended to be used with code libraries, @command{gawk} does not recognize such files as constituting main program input. Thus, after processing an @option{-i} argument, @command{gawk} still expects to find the main source code via the @option{-f} option -or on the command-line. +or on the command line. @item @option{-l} @var{ext} @itemx @option{--load} @var{ext} @@ -3804,7 +3809,7 @@ a shared library. This feature is described in detail in @ref{Dynamic Extension @cindex warnings, issuing Warn about constructs that are dubious or nonportable to other @command{awk} implementations. -No space is allowed between the @option{-D} and @var{value}, if +No space is allowed between the @option{-L} and @var{value}, if @var{value} is supplied. Some warnings are issued when @command{gawk} first reads your program. Others are issued at runtime, as your program executes. @@ -3923,7 +3928,7 @@ Newlines are not allowed after @samp{?} or @samp{:} @cindex @code{FS} variable, as TAB character @item -Specifying @samp{-Ft} on the command-line does not set the value +Specifying @samp{-Ft} on the command line does not set the value of @code{FS} to be a single TAB character (@pxref{Field Separators}). @@ -4169,7 +4174,7 @@ with @code{getline}. Some other versions of @command{awk} also support this, but it is not standard. (Some operating systems provide a @file{/dev/stdin} file -in the file system; however, @command{gawk} always processes +in the filesystem; however, @command{gawk} always processes this @value{FN} itself.) @node Environment Variables @@ -4195,7 +4200,7 @@ behaves. @cindex differences in @command{awk} and @command{gawk}, @code{AWKPATH} environment variable @ifinfo The previous @value{SECTION} described how @command{awk} program files can be named -on the command-line with the @option{-f} option. +on the command line with the @option{-f} option. @end ifinfo In most @command{awk} implementations, you must supply a precise path name for each program @@ -4290,7 +4295,7 @@ list are meant to be used by regular users. @table @env @item POSIXLY_CORRECT -Causes @command{gawk} to switch POSIX compatibility +Causes @command{gawk} to switch to POSIX compatibility mode, disabling all traditional and GNU extensions. @xref{Options}. @@ -4323,7 +4328,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 file systems I/O blocksize.) +blocksize, which is usually the filesystems I/O blocksize.) @item AWK_HASH If this variable exists with a value of @samp{gst}, @command{gawk} @@ -4656,9 +4661,9 @@ or to run @command{awk}. @item -The three standard @command{awk} options are @option{-f}, @option{-F} -and @option{-v}. @command{gawk} supplies these and many others, as well -as corresponding GNU-style long options. +The three standard options for all versions of @command{awk} are +@option{-f}, @option{-F} and @option{-v}. @command{gawk} supplies these +and many others, as well as corresponding GNU-style long options. @item Non-option command-line arguments are usually treated as @value{FN}s, @@ -5994,7 +5999,7 @@ In @command{awk}, regular expression constants are written enclosed between slashes: @code{/}@dots{}@code{/}. @item -Regexp constants may be used by standalone in patterns and +Regexp constants may be used standalone in patterns and in conditional expressions, or as part of matching expressions using the @samp{~} and @samp{!~} operators. @@ -6024,7 +6029,7 @@ 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. @end itemize @@ -6076,7 +6081,7 @@ used with it do not have to be named on the @command{awk} command line * Getline:: Reading files under explicit program control using the @code{getline} function. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on the +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -6307,17 +6312,17 @@ with optional leading and/or trailing whitespace: @example $ @kbd{echo record 1 AAAA record 2 BBBB record 3 |} > @kbd{gawk 'BEGIN @{ RS = "\n|( *[[:upper:]]+ *)" @}} -> @kbd{@{ print "Record =", $0, "and RT =", RT @}'} -@print{} Record = record 1 and RT = AAAA -@print{} Record = record 2 and RT = BBBB -@print{} Record = record 3 and RT = -@print{} +> @kbd{@{ print "Record =", $0,"and RT = [" RT "]" @}'} +@print{} Record = record 1 and RT = [ AAAA ] +@print{} Record = record 2 and RT = [ BBBB ] +@print{} Record = record 3 and RT = [ +@print{} ] @end example @noindent -The final line of output has an extra blank line. This is because the -value of @code{RT} is a newline, and the @code{print} statement -supplies its own terminating newline. +The square brackets delineate the contents of @code{RT}, letting you +see the leading and trailing whitespace. The final value of @code{RT} +@code{RT} is a newline. @xref{Simple Sed}, for a more useful example of @code{RS} as a regexp and @code{RT}. @@ -6831,7 +6836,7 @@ with a statement such as @samp{$1 = $1}, as described earlier. * Default Field Splitting:: How fields are normally separated. * 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. @end menu @@ -7087,7 +7092,7 @@ behaves this way. @node Command Line Field Separator @subsection Setting @code{FS} from the Command Line -@cindex @option{-F} option, command line +@cindex @option{-F} option, command-line @cindex field separator, on command line @cindex command line, @code{FS} on@comma{} setting @cindex @code{FS} variable, setting from command line @@ -8522,10 +8527,10 @@ a connection before it can start reading any data, or the attempt to open a FIFO special file for reading can block indefinitely until some other process opens it for writing. -@node Command line directories +@node Command-line directories @section Directories On The Command Line -@cindex differences in @command{awk} and @command{gawk}, command line directories -@cindex directories, command line +@cindex differences in @command{awk} and @command{gawk}, command-line directories +@cindex directories, command-line @cindex command line, directories on According to the POSIX standard, files named on the @command{awk} @@ -10563,7 +10568,7 @@ function mysub(pat, repl, str, global) @c @cindex automatic warnings @c @cindex warnings, automatic In this example, the programmer wants to pass a regexp constant to the -user-defined function @code{mysub}, which in turn passes it on to +user-defined function @code{mysub()}, which in turn passes it on to either @code{sub()} or @code{gsub()}. However, what really happens is that the @code{pat} parameter is either one or zero, depending upon whether or not @code{$0} matches @code{/hi/}. @@ -10584,7 +10589,7 @@ on the @command{awk} command line. @menu * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line and a +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. @end menu @@ -17501,6 +17506,12 @@ Nonalphabetic characters are left unchanged. For example, @cindex backslash (@code{\}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @cindex @code{&} (ampersand), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @cindex ampersand (@code{&}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and + +@quotation CAUTION +This section has been known to cause headaches. +You might want to skip it upon first reading. +@end quotation + When using @code{sub()}, @code{gsub()}, or @code{gensub()}, and trying to get literal backslashes and ampersands into the replacement text, you need to remember that there are several levels of @dfn{escape processing} going on. @@ -17543,26 +17554,26 @@ through unchanged. This is illustrated in @ref{table-sub-escapes}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr - @code{\&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\\&}! @code{\\&}!a literal @samp{\&}_cr - @code{\\\\\&}! @code{\\&}!a literal @samp{\&}_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\\&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr + @code{\&}! @code{&}!The matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\\&}! @code{\\&}!A literal @samp{\&}_cr + @code{\\\\\&}! @code{\\&}!A literal @samp{\&}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\\&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr } _bigskip} @end tex @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\&} -@item @code{\\\\\&} @tab @code{\\&} @tab a literal @samp{\&} -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\\&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\&} @tab @code{&} @tab The matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\&} +@item @code{\\\\\&} @tab @code{\\&} @tab A literal @samp{\&} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\\&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @end multitable @end ifdocbook @ifnottex @@ -17570,13 +17581,13 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- - @code{\&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\&} @code{\&} a literal @samp{&} - @code{\\\\&} @code{\\&} a literal @samp{\&} - @code{\\\\\&} @code{\\&} a literal @samp{\&} -@code{\\\\\\&} @code{\\\&} a literal @samp{\\&} - @code{\\q} @code{\q} a literal @samp{\q} + @code{\&} @code{&} The matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\\&} @code{\&} A literal @samp{&} + @code{\\\\&} @code{\\&} A literal @samp{\&} + @code{\\\\\&} @code{\\&} A literal @samp{\&} +@code{\\\\\\&} @code{\\\&} A literal @samp{\\&} + @code{\\q} @code{\q} A literal @samp{\q} @end display @end ifnotdocbook @end ifnottex @@ -17592,86 +17603,19 @@ case of even numbers of backslashes entered at the lexical level.) The problem with the historical approach is that there is no way to get a literal @samp{\} followed by the matched text. -@c @cindex @command{awk} language, POSIX version -@cindex POSIX @command{awk}, functions and, @code{gsub()}/@code{sub()} -The 1992 POSIX standard attempted to fix this problem. That standard -says that @code{sub()} and @code{gsub()} look for either a @samp{\} or an @samp{&} -after the @samp{\}. If either one follows a @samp{\}, that character is -output literally. The interpretation of @samp{\} and @samp{&} then becomes -as shown in @ref{table-sub-posix-92}. - -@float Table,table-sub-posix-92 -@caption{1992 POSIX Rules for @code{sub()} and @code{gsub()} Escape Sequence Processing} -@c thanks to Karl Berry for formatting this table -@tex -\vbox{\bigskip -% We need more characters for escape and tab ... -\catcode`_ = 0 -\catcode`! = 4 -% ... since this table has lots of &'s and \'s, so we unspecialize them. -\catcode`\& = \other \catcode`\\ = \other -_halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr - You type!@code{sub()} sees!@code{sub()} generates_cr -_hrulefill!_hrulefill!_hrulefill_cr - @code{&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, then the matched text_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -} -_bigskip} -@end tex -@ifdocbook -@multitable @columnfractions .20 .20 .60 -@headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, then the matched text -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@end multitable -@end ifdocbook -@ifnottex -@ifnotdocbook -@display - You type @code{sub()} sees @code{sub()} generates - -------- ---------- --------------- - @code{&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\\&} @code{\\&} a literal @samp{\}, then the matched text -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} -@end display -@end ifnotdocbook -@end ifnottex -@end float - -@noindent -This appears to solve the problem. -Unfortunately, the phrasing of the standard is unusual. It -says, in effect, that @samp{\} turns off the special meaning of any -following character, but for anything other than @samp{\} and @samp{&}, -such special meaning is undefined. This wording leads to two problems: - -@itemize @value{BULLET} -@item -Backslashes must now be doubled in the @var{replacement} string, breaking -historical @command{awk} programs. - -@item -To make sure that an @command{awk} program is portable, @emph{every} character -in the @var{replacement} string must be preceded with a -backslash.@footnote{This consequence was certainly unintended.} -@c I can say that, 'cause I was involved in making this change -@end itemize +Several editions of the POSIX standard attempted to fix this problem +but weren't successful. The details are irrelevant at this point in time. -Because of the problems just listed, -in 1996, the @command{gawk} maintainer submitted +At one point, the @command{gawk} maintainer submitted proposed text for a revised standard that reverts to rules that correspond more closely to the original existing practice. The proposed rules have special cases that make it possible -to produce a @samp{\} preceding the matched text. This is shown in +to produce a @samp{\} preceding the matched text. +This is shown in @ref{table-sub-proposed}. @float Table,table-sub-proposed -@caption{Proposed Rules For @code{sub()} And Backslash} +@caption{GNU @command{awk} Rules For @code{sub()} And Backslash} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -17682,10 +17626,10 @@ to produce a @samp{\} preceding the matched text. This is shown in _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, followed by the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr +@code{\\\\&}! @code{\\&}!A literal @samp{\}, followed by the matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr @code{\\\\}! @code{\\}!@code{\\}_cr } _bigskip} @@ -17693,10 +17637,10 @@ _bigskip} @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, followed by the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, followed by the matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @item @code{\\\\} @tab @code{\\} @tab @code{\\} @end multitable @end ifdocbook @@ -17705,10 +17649,10 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\\\&} @code{\\&} a literal @samp{\}, followed by the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\q} @code{\q} a literal @samp{\q} +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\\\&} @code{\\&} A literal @samp{\}, followed by the matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\q} @code{\q} A literal @samp{\q} @code{\\\\} @code{\\} @code{\\} @end display @end ifnotdocbook @@ -17721,13 +17665,13 @@ there was only one. However, as in the historical case, any @samp{\} that is not part of one of these three sequences is not special and appears in the output literally. -@command{gawk} 3.0 and 3.1 follow these proposed POSIX rules for @code{sub()} and -@code{gsub()}. -@c As much as we think it's a lousy idea. You win some, you lose some. Sigh. -The POSIX standard took much longer to be revised than was expected in 1996. -The 2001 standard does not follow the above rules. Instead, the rules -there are somewhat simpler. The results are similar except for one case. +@command{gawk} 3.0 and 3.1 follow these rules for @code{sub()} and +@code{gsub()}. The POSIX standard took much longer to be revised than +was expected. In addition, the @command{gawk} maintainer's proposal was +lost during the standardization process. The final rules are +somewhat simpler. The results are similar except for one case. +@cindex POSIX @command{awk}, functions and, @code{gsub()}/@code{sub()} The POSIX rules state that @samp{\&} in the replacement string produces a literal @samp{&}, @samp{\\} produces a literal @samp{\}, and @samp{\} followed by anything else is not special; the @samp{\} is placed straight into the output. @@ -17745,10 +17689,10 @@ These rules are presented in @ref{table-posix-sub}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, followed by the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr +@code{\\\\&}! @code{\\&}!A literal @samp{\}, followed by the matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr @code{\\\\}! @code{\\}!@code{\}_cr } _bigskip} @@ -17756,10 +17700,10 @@ _bigskip} @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, followed by the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, followed by the matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @item @code{\\\\} @tab @code{\\} @tab @code{\} @end multitable @end ifdocbook @@ -17768,10 +17712,10 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\\\&} @code{\\&} a literal @samp{\}, followed by the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\q} @code{\q} a literal @samp{\q} +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\\\&} @code{\\&} A literal @samp{\}, followed by the matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\q} @code{\q} A literal @samp{\q} @code{\\\\} @code{\\} @code{\} @end display @end ifnotdocbook @@ -17783,7 +17727,7 @@ is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, -it continued to follow the 1996 proposed rules, since +it continued to follow the proposed rules, since that had been its behavior for many years. When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer @@ -17814,24 +17758,24 @@ as shown in @ref{table-gensub-escapes}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{gensub()} sees!@code{gensub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr - @code{&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\\}! @code{\\}!a literal @samp{\}_cr - @code{\\\\&}! @code{\\&}!a literal @samp{\}, then the matched text_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr - @code{\\q}! @code{\q}!a literal @samp{q}_cr + @code{&}! @code{&}!The matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\\}! @code{\\}!A literal @samp{\}_cr + @code{\\\\&}! @code{\\&}!A literal @samp{\}, then the matched text_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr + @code{\\q}! @code{\q}!A literal @samp{q}_cr } _bigskip} @end tex @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{gensub()} sees @tab @code{gensub()} generates -@item @code{&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\} @tab @code{\\} @tab a literal @samp{\} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, then the matched text -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{q} +@item @code{&} @tab @code{&} @tab The matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\\} @tab @code{\\} @tab A literal @samp{\} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, then the matched text +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{q} @end multitable @end ifdocbook @ifnottex @@ -17839,12 +17783,12 @@ _bigskip} @display You type @code{gensub()} sees @code{gensub()} generates -------- ------------- ------------------ - @code{&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\\} @code{\\} a literal @samp{\} - @code{\\\\&} @code{\\&} a literal @samp{\}, then the matched text -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\q} @code{\q} a literal @samp{q} + @code{&} @code{&} The matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\\\} @code{\\} A literal @samp{\} + @code{\\\\&} @code{\\&} A literal @samp{\}, then the matched text +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\q} @code{\q} A literal @samp{q} @end display @end ifnotdocbook @end ifnottex @@ -19268,17 +19212,18 @@ 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. Recursive functions must always have a test that stops the recursion. -In this case, the recursion terminates when the starting position -is zero, i.e., when there are no more characters left in the string. +In this case, the recursion terminates when the input string is +already empty. +@c 8/2014: Thanks to Mike Brennan for the improved formulation @cindex @code{rev()} user-defined function @example -function rev(str, start) +function rev(str) @{ - if (start == 0) + if (str == "") return "" - return (substr(str, start, 1) rev(str, start - 1)) + return (rev(substr(str, 2)) substr(str, 1, 1)) @} @end example @@ -19287,7 +19232,7 @@ this way: @example $ @kbd{echo "Don't Panic!" |} -> @kbd{gawk --source '@{ print rev($0, length($0)) @}' -f rev.awk} +> @kbd{gawk --source '@{ print rev($0) @}' -f rev.awk} @print{} !cinaP t'noD @end example @@ -19572,7 +19517,7 @@ BEGIN @{ @noindent prints @samp{a[1] = 1, a[2] = two, a[3] = 3}, because -@code{changeit} stores @code{"two"} in the second element of @code{a}. +@code{changeit()} stores @code{"two"} in the second element of @code{a}. @end quotation @cindex undefined functions @@ -25927,7 +25872,7 @@ The program should exit without reading any @value{DF}s. However, suppose that an included library file defines an @code{END} rule of its own. In this case, @command{gawk} will hang, reading standard input. In order to avoid this, @file{/dev/null} is explicitly added to the -command-line. Reading from @file{/dev/null} always returns an immediate +command line. Reading from @file{/dev/null} always returns an immediate end of file indication. @c Hmm. Add /dev/null if $# is 0? Still messes up ARGV. Sigh. @@ -26949,6 +26894,9 @@ Caveat Emptor. @node Two-way I/O @section Two-Way Communications with Another Process + +@c 8/2014. Neither Mike nor BWK saw this as relevant. Commenting it out. +@ignore @cindex Brennan, Michael @cindex programmers, attractiveness of @smallexample @@ -26978,6 +26926,7 @@ the scent of perl programmers. Mike Brennan @c brennan@@whidbey.com @end smallexample +@end ignore @cindex advanced features, processes@comma{} communicating with @cindex processes, two-way communications with @@ -27004,7 +26953,10 @@ system("rm " tempfile) This works, but not elegantly. Among other things, it requires that the program be run in a directory that cannot be shared among users; for example, @file{/tmp} will not do, as another user might happen -to be using a temporary file with the same name. +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 @cindex coprocesses @cindex input/output, two-way @@ -27159,7 +27111,7 @@ You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is by recognizing special @value{FN}s that begin with one of @samp{/inet/}, -@samp{/inet4/} or @samp{/inet6}. +@samp{/inet4/} or @samp{/inet6/}. The full syntax of the special @value{FN} is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. @@ -29792,6 +29744,12 @@ arbitrary precision integers, and concludes with a description of some points where @command{gawk} and the POSIX standard are not quite in agreement. +@quotation NOTE +Most users of @command{gawk} can safely skip this chapter. +But if you want to do scientific calculations with @command{gawk}, +this is the place to be. +@end quotation + @menu * Computer Arithmetic:: A quick intro to computer math. * Math Definitions:: Defining terms used. @@ -29911,8 +29869,23 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.'' A special value indicating a result that can't -happen in real math, but that can happen in floating-point computations. +``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: + +@table @code +@item sqrt(-1) +This makes sense in the range of complex numbers, but not in the +range of real numbers, so the result is @code{NaN}. + +@item log(-8) +@minus{}8 is out of the domain of @code{log()}, so the result is @code{NaN}. +@end table @item Normalized How the significand (see later in this list) is usually stored. The @@ -30330,7 +30303,7 @@ internally as a 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 -than the default and cannot use a command line assignment to @code{PREC}, +than the default and cannot use a command-line assignment to @code{PREC}, you should either specify the constant as a string, or as a rational number, whenever possible. The following example illustrates the differences among various ways to print a floating-point constant: @@ -30964,7 +30937,7 @@ Some other bits and pieces: @itemize @value{BULLET} @item The API provides access to @command{gawk}'s @code{do_@var{xxx}} values, -reflecting command line options, like @code{do_lint}, @code{do_profiling} +reflecting command-line options, like @code{do_lint}, @code{do_profiling} and so on (@pxref{Extension API Variables}). These are informational: an extension cannot affect their values inside @command{gawk}. In addition, attempting to assign to them @@ -35180,7 +35153,7 @@ Indirect function calls @item Directories on the command line produce a warning and are skipped -(@pxref{Command line directories}). +(@pxref{Command-line directories}). @end itemize @item @@ -35527,7 +35500,7 @@ The ability to delete all of an array at once with @samp{delete @var{array}} (@pxref{Delete}). @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -35590,7 +35563,7 @@ Brian Kernighan's @command{awk} @pxref{I/O Functions}). @item -New command line options: +New command-line options: @itemize @value{MINUS} @item @@ -35880,7 +35853,7 @@ Indirect function calls (@pxref{Switch Statement}). @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -35905,7 +35878,7 @@ All long options acquired corresponding short options, for use in @samp{#!} scri @item Directories named on the command line now produce a warning, not a fatal error, unless @option{--posix} or @option{--traditional} are used -(@pxref{Command line directories}). +(@pxref{Command-line directories}). @item The @command{gawk} internals were rewritten, bringing the @command{dgawk} @@ -35981,10 +35954,10 @@ Three new arrays: @item The three executables @command{gawk}, @command{pgawk}, and @command{dgawk}, were merged into -one, named just @command{gawk}. As a result the command line options changed. +one, named just @command{gawk}. As a result the command-line options changed. @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -41362,13 +41335,14 @@ Consistency issues: Use "zeros" instead of "zeroes". Use "nonzero" not "non-zero". Use "runtime" not "run time" or "run-time". - Use "command-line" not "command line". + Use "command-line" as an adjective and "command line" as a noun. Use "online" not "on-line". Use "whitespace" not "white space". Use "Input/Output", not "input/output". Also "I/O", not "i/o". Use "lefthand"/"righthand", not "left-hand"/"right-hand". Use "workaround", not "work-around". Use "startup"/"cleanup", not "start-up"/"clean-up" + Use "filesystem", not "file system" Use @code{do}, and not @code{do}-@code{while}, except where actually discussing the do-while. Use "versus" in text and "vs." in index entries @@ -41383,8 +41357,6 @@ Consistency issues: The numbers zero through ten should be spelled out, except when talking about file descriptor numbers. > 10 and < 0, it's ok to use numbers. - In tables, put command-line options in @code, while in the text, - put them in @option. For most cases, do NOT put a comma before "and", "or" or "but". But exercise taste with this rule. Don't show the awk command with a program in quotes when it's diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 33269644..5460dec3 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -46,7 +46,7 @@ @c applies to and all the info about who's publishing this edition @c These apply across the board. -@set UPDATE-MONTH July, 2014 +@set UPDATE-MONTH August, 2014 @set VERSION 4.1 @set PATCHLEVEL 1 @@ -541,7 +541,7 @@ particular records in a file and perform operations upon them. * Single Character Fields:: Making each character a separate field. * Command Line Field Separator:: Setting @code{FS} from the - command-line. + command line. * Full Line Fields:: Making the full line be a single field. * Field Splitting Summary:: Some final points and a summary table. @@ -567,7 +567,7 @@ particular records in a file and perform operations upon them. @code{getline}. * Getline Summary:: Summary of @code{getline} Variants. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -606,7 +606,7 @@ particular records in a file and perform operations upon them. * Variables:: Variables give names to values for later use. * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. * Conversion:: The conversion of strings to numbers @@ -1371,7 +1371,7 @@ help from me, thoroughly reworked @command{gawk} for compatibility with the newer @command{awk}. Circa 1994, I became the primary maintainer. Current development focuses on bug fixes, -performance improvements, standards compliance, and occasionally, new features. +performance improvements, standards compliance and, occasionally, new features. In May of 1997, J@"urgen Kahrs felt the need for network access from @command{awk}, and with a little help from me, set about adding @@ -1664,7 +1664,7 @@ are slightly different than in other books you may have read. This @value{SECTION} briefly documents the typographical conventions used in Texinfo. @end ifinfo -Examples you would type at the command-line are preceded by the common +Examples you would type at the command line are preceded by the common shell primary and secondary prompts, @samp{$} and @samp{>}. Input that you type is shown @kbd{like this}. Output from the command is preceded by the glyph ``@print{}''. @@ -2302,12 +2302,7 @@ 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@footnote{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 startup file.} -(@code{BEGIN} is a feature we haven't discussed yet): +programming (@code{BEGIN} is a feature we haven't discussed yet): @example $ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"} @@ -2326,6 +2321,14 @@ 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.} +@quotation NOTE +As a side note, 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 +startup file. +@end quotation + This next simple @command{awk} program emulates the @command{cat} utility; it copies whatever you type on the keyboard to its standard output (why this works is explained shortly). @@ -2643,7 +2646,7 @@ Note that the single quote is not special within double quotes. @item Null strings are removed when they occur as part of a non-null -command-line argument, while explicit non-null objects are kept. +command-line argument, while explicit null objects are kept. For example, to specify that the field separator @code{FS} should be set to the null string, use: @@ -2790,7 +2793,9 @@ each line is considered to be one @dfn{record}. In the @value{DF} @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. An @samp{A} in the last column +with the author of the list. +The columns are aligned using spaces. +An @samp{A} in the last column means that the person is an acquaintance. An @samp{F} in the last column means that the person is a friend. An @samp{R} means that the person is a relative: @@ -3708,7 +3713,7 @@ Second, because this option is intended to be used with code libraries, @command{gawk} does not recognize such files as constituting main program input. Thus, after processing an @option{-i} argument, @command{gawk} still expects to find the main source code via the @option{-f} option -or on the command-line. +or on the command line. @item @option{-l} @var{ext} @itemx @option{--load} @var{ext} @@ -3732,7 +3737,7 @@ a shared library. This feature is described in detail in @ref{Dynamic Extension @cindex warnings, issuing Warn about constructs that are dubious or nonportable to other @command{awk} implementations. -No space is allowed between the @option{-D} and @var{value}, if +No space is allowed between the @option{-L} and @var{value}, if @var{value} is supplied. Some warnings are issued when @command{gawk} first reads your program. Others are issued at runtime, as your program executes. @@ -3851,7 +3856,7 @@ Newlines are not allowed after @samp{?} or @samp{:} @cindex @code{FS} variable, as TAB character @item -Specifying @samp{-Ft} on the command-line does not set the value +Specifying @samp{-Ft} on the command line does not set the value of @code{FS} to be a single TAB character (@pxref{Field Separators}). @@ -4097,7 +4102,7 @@ with @code{getline}. Some other versions of @command{awk} also support this, but it is not standard. (Some operating systems provide a @file{/dev/stdin} file -in the file system; however, @command{gawk} always processes +in the filesystem; however, @command{gawk} always processes this @value{FN} itself.) @node Environment Variables @@ -4123,7 +4128,7 @@ behaves. @cindex differences in @command{awk} and @command{gawk}, @code{AWKPATH} environment variable @ifinfo The previous @value{SECTION} described how @command{awk} program files can be named -on the command-line with the @option{-f} option. +on the command line with the @option{-f} option. @end ifinfo In most @command{awk} implementations, you must supply a precise path name for each program @@ -4218,7 +4223,7 @@ list are meant to be used by regular users. @table @env @item POSIXLY_CORRECT -Causes @command{gawk} to switch POSIX compatibility +Causes @command{gawk} to switch to POSIX compatibility mode, disabling all traditional and GNU extensions. @xref{Options}. @@ -4251,7 +4256,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 file systems I/O blocksize.) +blocksize, which is usually the filesystems I/O blocksize.) @item AWK_HASH If this variable exists with a value of @samp{gst}, @command{gawk} @@ -4584,9 +4589,9 @@ or to run @command{awk}. @item -The three standard @command{awk} options are @option{-f}, @option{-F} -and @option{-v}. @command{gawk} supplies these and many others, as well -as corresponding GNU-style long options. +The three standard options for all versions of @command{awk} are +@option{-f}, @option{-F} and @option{-v}. @command{gawk} supplies these +and many others, as well as corresponding GNU-style long options. @item Non-option command-line arguments are usually treated as @value{FN}s, @@ -5795,7 +5800,7 @@ In @command{awk}, regular expression constants are written enclosed between slashes: @code{/}@dots{}@code{/}. @item -Regexp constants may be used by standalone in patterns and +Regexp constants may be used standalone in patterns and in conditional expressions, or as part of matching expressions using the @samp{~} and @samp{!~} operators. @@ -5825,7 +5830,7 @@ 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. @end itemize @@ -5877,7 +5882,7 @@ used with it do not have to be named on the @command{awk} command line * Getline:: Reading files under explicit program control using the @code{getline} function. * Read Timeout:: Reading input with a timeout. -* Command line directories:: What happens if you put a directory on the +* Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. * Input Exercises:: Exercises. @@ -6108,17 +6113,17 @@ with optional leading and/or trailing whitespace: @example $ @kbd{echo record 1 AAAA record 2 BBBB record 3 |} > @kbd{gawk 'BEGIN @{ RS = "\n|( *[[:upper:]]+ *)" @}} -> @kbd{@{ print "Record =", $0, "and RT =", RT @}'} -@print{} Record = record 1 and RT = AAAA -@print{} Record = record 2 and RT = BBBB -@print{} Record = record 3 and RT = -@print{} +> @kbd{@{ print "Record =", $0,"and RT = [" RT "]" @}'} +@print{} Record = record 1 and RT = [ AAAA ] +@print{} Record = record 2 and RT = [ BBBB ] +@print{} Record = record 3 and RT = [ +@print{} ] @end example @noindent -The final line of output has an extra blank line. This is because the -value of @code{RT} is a newline, and the @code{print} statement -supplies its own terminating newline. +The square brackets delineate the contents of @code{RT}, letting you +see the leading and trailing whitespace. The final value of @code{RT} +@code{RT} is a newline. @xref{Simple Sed}, for a more useful example of @code{RS} as a regexp and @code{RT}. @@ -6545,7 +6550,7 @@ with a statement such as @samp{$1 = $1}, as described earlier. * Default Field Splitting:: How fields are normally separated. * 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. @end menu @@ -6801,7 +6806,7 @@ behaves this way. @node Command Line Field Separator @subsection Setting @code{FS} from the Command Line -@cindex @option{-F} option, command line +@cindex @option{-F} option, command-line @cindex field separator, on command line @cindex command line, @code{FS} on@comma{} setting @cindex @code{FS} variable, setting from command line @@ -8141,10 +8146,10 @@ a connection before it can start reading any data, or the attempt to open a FIFO special file for reading can block indefinitely until some other process opens it for writing. -@node Command line directories +@node Command-line directories @section Directories On The Command Line -@cindex differences in @command{awk} and @command{gawk}, command line directories -@cindex directories, command line +@cindex differences in @command{awk} and @command{gawk}, command-line directories +@cindex directories, command-line @cindex command line, directories on According to the POSIX standard, files named on the @command{awk} @@ -10053,7 +10058,7 @@ function mysub(pat, repl, str, global) @c @cindex automatic warnings @c @cindex warnings, automatic In this example, the programmer wants to pass a regexp constant to the -user-defined function @code{mysub}, which in turn passes it on to +user-defined function @code{mysub()}, which in turn passes it on to either @code{sub()} or @code{gsub()}. However, what really happens is that the @code{pat} parameter is either one or zero, depending upon whether or not @code{$0} matches @code{/hi/}. @@ -10074,7 +10079,7 @@ on the @command{awk} command line. @menu * Using Variables:: Using variables in your programs. -* Assignment Options:: Setting variables on the command-line and a +* Assignment Options:: Setting variables on the command line and a summary of command-line syntax. This is an advanced method of input. @end menu @@ -16806,6 +16811,12 @@ Nonalphabetic characters are left unchanged. For example, @cindex backslash (@code{\}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @cindex @code{&} (ampersand), @code{gsub()}/@code{gensub()}/@code{sub()} functions and @cindex ampersand (@code{&}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and + +@quotation CAUTION +This section has been known to cause headaches. +You might want to skip it upon first reading. +@end quotation + When using @code{sub()}, @code{gsub()}, or @code{gensub()}, and trying to get literal backslashes and ampersands into the replacement text, you need to remember that there are several levels of @dfn{escape processing} going on. @@ -16848,26 +16859,26 @@ through unchanged. This is illustrated in @ref{table-sub-escapes}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr - @code{\&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\\&}! @code{\\&}!a literal @samp{\&}_cr - @code{\\\\\&}! @code{\\&}!a literal @samp{\&}_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\\&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr + @code{\&}! @code{&}!The matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\\&}! @code{\\&}!A literal @samp{\&}_cr + @code{\\\\\&}! @code{\\&}!A literal @samp{\&}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\\&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr } _bigskip} @end tex @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\&} -@item @code{\\\\\&} @tab @code{\\&} @tab a literal @samp{\&} -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\\&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\&} @tab @code{&} @tab The matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\&} +@item @code{\\\\\&} @tab @code{\\&} @tab A literal @samp{\&} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\\&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @end multitable @end ifdocbook @ifnottex @@ -16875,13 +16886,13 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- - @code{\&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\&} @code{\&} a literal @samp{&} - @code{\\\\&} @code{\\&} a literal @samp{\&} - @code{\\\\\&} @code{\\&} a literal @samp{\&} -@code{\\\\\\&} @code{\\\&} a literal @samp{\\&} - @code{\\q} @code{\q} a literal @samp{\q} + @code{\&} @code{&} The matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\\&} @code{\&} A literal @samp{&} + @code{\\\\&} @code{\\&} A literal @samp{\&} + @code{\\\\\&} @code{\\&} A literal @samp{\&} +@code{\\\\\\&} @code{\\\&} A literal @samp{\\&} + @code{\\q} @code{\q} A literal @samp{\q} @end display @end ifnotdocbook @end ifnottex @@ -16897,86 +16908,19 @@ case of even numbers of backslashes entered at the lexical level.) The problem with the historical approach is that there is no way to get a literal @samp{\} followed by the matched text. -@c @cindex @command{awk} language, POSIX version -@cindex POSIX @command{awk}, functions and, @code{gsub()}/@code{sub()} -The 1992 POSIX standard attempted to fix this problem. That standard -says that @code{sub()} and @code{gsub()} look for either a @samp{\} or an @samp{&} -after the @samp{\}. If either one follows a @samp{\}, that character is -output literally. The interpretation of @samp{\} and @samp{&} then becomes -as shown in @ref{table-sub-posix-92}. - -@float Table,table-sub-posix-92 -@caption{1992 POSIX Rules for @code{sub()} and @code{gsub()} Escape Sequence Processing} -@c thanks to Karl Berry for formatting this table -@tex -\vbox{\bigskip -% We need more characters for escape and tab ... -\catcode`_ = 0 -\catcode`! = 4 -% ... since this table has lots of &'s and \'s, so we unspecialize them. -\catcode`\& = \other \catcode`\\ = \other -_halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr - You type!@code{sub()} sees!@code{sub()} generates_cr -_hrulefill!_hrulefill!_hrulefill_cr - @code{&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, then the matched text_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -} -_bigskip} -@end tex -@ifdocbook -@multitable @columnfractions .20 .20 .60 -@headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, then the matched text -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@end multitable -@end ifdocbook -@ifnottex -@ifnotdocbook -@display - You type @code{sub()} sees @code{sub()} generates - -------- ---------- --------------- - @code{&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\\&} @code{\\&} a literal @samp{\}, then the matched text -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} -@end display -@end ifnotdocbook -@end ifnottex -@end float - -@noindent -This appears to solve the problem. -Unfortunately, the phrasing of the standard is unusual. It -says, in effect, that @samp{\} turns off the special meaning of any -following character, but for anything other than @samp{\} and @samp{&}, -such special meaning is undefined. This wording leads to two problems: - -@itemize @value{BULLET} -@item -Backslashes must now be doubled in the @var{replacement} string, breaking -historical @command{awk} programs. - -@item -To make sure that an @command{awk} program is portable, @emph{every} character -in the @var{replacement} string must be preceded with a -backslash.@footnote{This consequence was certainly unintended.} -@c I can say that, 'cause I was involved in making this change -@end itemize +Several editions of the POSIX standard attempted to fix this problem +but weren't successful. The details are irrelevant at this point in time. -Because of the problems just listed, -in 1996, the @command{gawk} maintainer submitted +At one point, the @command{gawk} maintainer submitted proposed text for a revised standard that reverts to rules that correspond more closely to the original existing practice. The proposed rules have special cases that make it possible -to produce a @samp{\} preceding the matched text. This is shown in +to produce a @samp{\} preceding the matched text. +This is shown in @ref{table-sub-proposed}. @float Table,table-sub-proposed -@caption{Proposed Rules For @code{sub()} And Backslash} +@caption{GNU @command{awk} Rules For @code{sub()} And Backslash} @tex \vbox{\bigskip % We need more characters for escape and tab ... @@ -16987,10 +16931,10 @@ to produce a @samp{\} preceding the matched text. This is shown in _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, followed by the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr +@code{\\\\&}! @code{\\&}!A literal @samp{\}, followed by the matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr @code{\\\\}! @code{\\}!@code{\\}_cr } _bigskip} @@ -16998,10 +16942,10 @@ _bigskip} @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, followed by the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, followed by the matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @item @code{\\\\} @tab @code{\\} @tab @code{\\} @end multitable @end ifdocbook @@ -17010,10 +16954,10 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\\\&} @code{\\&} a literal @samp{\}, followed by the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\q} @code{\q} a literal @samp{\q} +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\\\&} @code{\\&} A literal @samp{\}, followed by the matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\q} @code{\q} A literal @samp{\q} @code{\\\\} @code{\\} @code{\\} @end display @end ifnotdocbook @@ -17026,13 +16970,13 @@ there was only one. However, as in the historical case, any @samp{\} that is not part of one of these three sequences is not special and appears in the output literally. -@command{gawk} 3.0 and 3.1 follow these proposed POSIX rules for @code{sub()} and -@code{gsub()}. -@c As much as we think it's a lousy idea. You win some, you lose some. Sigh. -The POSIX standard took much longer to be revised than was expected in 1996. -The 2001 standard does not follow the above rules. Instead, the rules -there are somewhat simpler. The results are similar except for one case. +@command{gawk} 3.0 and 3.1 follow these rules for @code{sub()} and +@code{gsub()}. The POSIX standard took much longer to be revised than +was expected. In addition, the @command{gawk} maintainer's proposal was +lost during the standardization process. The final rules are +somewhat simpler. The results are similar except for one case. +@cindex POSIX @command{awk}, functions and, @code{gsub()}/@code{sub()} The POSIX rules state that @samp{\&} in the replacement string produces a literal @samp{&}, @samp{\\} produces a literal @samp{\}, and @samp{\} followed by anything else is not special; the @samp{\} is placed straight into the output. @@ -17050,10 +16994,10 @@ These rules are presented in @ref{table-posix-sub}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{sub()} sees!@code{sub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr -@code{\\\\&}! @code{\\&}!a literal @samp{\}, followed by the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\q}! @code{\q}!a literal @samp{\q}_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr +@code{\\\\&}! @code{\\&}!A literal @samp{\}, followed by the matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\q}! @code{\q}!A literal @samp{\q}_cr @code{\\\\}! @code{\\}!@code{\}_cr } _bigskip} @@ -17061,10 +17005,10 @@ _bigskip} @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{sub()} sees @tab @code{sub()} generates -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, followed by the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{\q} +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, followed by the matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{\q} @item @code{\\\\} @tab @code{\\} @tab @code{\} @end multitable @end ifdocbook @@ -17073,10 +17017,10 @@ _bigskip} @display You type @code{sub()} sees @code{sub()} generates -------- ---------- --------------- -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\\\&} @code{\\&} a literal @samp{\}, followed by the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\q} @code{\q} a literal @samp{\q} +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\\\&} @code{\\&} A literal @samp{\}, followed by the matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\q} @code{\q} A literal @samp{\q} @code{\\\\} @code{\\} @code{\} @end display @end ifnotdocbook @@ -17088,7 +17032,7 @@ is seen as @samp{\\} and produces @samp{\} instead of @samp{\\}. Starting with @value{PVERSION} 3.1.4, @command{gawk} followed the POSIX rules when @option{--posix} is specified (@pxref{Options}). Otherwise, -it continued to follow the 1996 proposed rules, since +it continued to follow the proposed rules, since that had been its behavior for many years. When @value{PVERSION} 4.0.0 was released, the @command{gawk} maintainer @@ -17119,24 +17063,24 @@ as shown in @ref{table-gensub-escapes}. _halign{_hfil#!_qquad_hfil#!_qquad#_hfil_cr You type!@code{gensub()} sees!@code{gensub()} generates_cr _hrulefill!_hrulefill!_hrulefill_cr - @code{&}! @code{&}!the matched text_cr - @code{\\&}! @code{\&}!a literal @samp{&}_cr - @code{\\\\}! @code{\\}!a literal @samp{\}_cr - @code{\\\\&}! @code{\\&}!a literal @samp{\}, then the matched text_cr -@code{\\\\\\&}! @code{\\\&}!a literal @samp{\&}_cr - @code{\\q}! @code{\q}!a literal @samp{q}_cr + @code{&}! @code{&}!The matched text_cr + @code{\\&}! @code{\&}!A literal @samp{&}_cr + @code{\\\\}! @code{\\}!A literal @samp{\}_cr + @code{\\\\&}! @code{\\&}!A literal @samp{\}, then the matched text_cr +@code{\\\\\\&}! @code{\\\&}!A literal @samp{\&}_cr + @code{\\q}! @code{\q}!A literal @samp{q}_cr } _bigskip} @end tex @ifdocbook @multitable @columnfractions .20 .20 .60 @headitem You type @tab @code{gensub()} sees @tab @code{gensub()} generates -@item @code{&} @tab @code{&} @tab the matched text -@item @code{\\&} @tab @code{\&} @tab a literal @samp{&} -@item @code{\\\\} @tab @code{\\} @tab a literal @samp{\} -@item @code{\\\\&} @tab @code{\\&} @tab a literal @samp{\}, then the matched text -@item @code{\\\\\\&} @tab @code{\\\&} @tab a literal @samp{\&} -@item @code{\\q} @tab @code{\q} @tab a literal @samp{q} +@item @code{&} @tab @code{&} @tab The matched text +@item @code{\\&} @tab @code{\&} @tab A literal @samp{&} +@item @code{\\\\} @tab @code{\\} @tab A literal @samp{\} +@item @code{\\\\&} @tab @code{\\&} @tab A literal @samp{\}, then the matched text +@item @code{\\\\\\&} @tab @code{\\\&} @tab A literal @samp{\&} +@item @code{\\q} @tab @code{\q} @tab A literal @samp{q} @end multitable @end ifdocbook @ifnottex @@ -17144,12 +17088,12 @@ _bigskip} @display You type @code{gensub()} sees @code{gensub()} generates -------- ------------- ------------------ - @code{&} @code{&} the matched text - @code{\\&} @code{\&} a literal @samp{&} - @code{\\\\} @code{\\} a literal @samp{\} - @code{\\\\&} @code{\\&} a literal @samp{\}, then the matched text -@code{\\\\\\&} @code{\\\&} a literal @samp{\&} - @code{\\q} @code{\q} a literal @samp{q} + @code{&} @code{&} The matched text + @code{\\&} @code{\&} A literal @samp{&} + @code{\\\\} @code{\\} A literal @samp{\} + @code{\\\\&} @code{\\&} A literal @samp{\}, then the matched text +@code{\\\\\\&} @code{\\\&} A literal @samp{\&} + @code{\\q} @code{\q} A literal @samp{q} @end display @end ifnotdocbook @end ifnottex @@ -18412,17 +18356,18 @@ 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. Recursive functions must always have a test that stops the recursion. -In this case, the recursion terminates when the starting position -is zero, i.e., when there are no more characters left in the string. +In this case, the recursion terminates when the input string is +already empty. +@c 8/2014: Thanks to Mike Brennan for the improved formulation @cindex @code{rev()} user-defined function @example -function rev(str, start) +function rev(str) @{ - if (start == 0) + if (str == "") return "" - return (substr(str, start, 1) rev(str, start - 1)) + return (rev(substr(str, 2)) substr(str, 1, 1)) @} @end example @@ -18431,7 +18376,7 @@ this way: @example $ @kbd{echo "Don't Panic!" |} -> @kbd{gawk --source '@{ print rev($0, length($0)) @}' -f rev.awk} +> @kbd{gawk --source '@{ print rev($0) @}' -f rev.awk} @print{} !cinaP t'noD @end example @@ -18716,7 +18661,7 @@ BEGIN @{ @noindent prints @samp{a[1] = 1, a[2] = two, a[3] = 3}, because -@code{changeit} stores @code{"two"} in the second element of @code{a}. +@code{changeit()} stores @code{"two"} in the second element of @code{a}. @end quotation @cindex undefined functions @@ -25042,7 +24987,7 @@ The program should exit without reading any @value{DF}s. However, suppose that an included library file defines an @code{END} rule of its own. In this case, @command{gawk} will hang, reading standard input. In order to avoid this, @file{/dev/null} is explicitly added to the -command-line. Reading from @file{/dev/null} always returns an immediate +command line. Reading from @file{/dev/null} always returns an immediate end of file indication. @c Hmm. Add /dev/null if $# is 0? Still messes up ARGV. Sigh. @@ -26064,6 +26009,9 @@ Caveat Emptor. @node Two-way I/O @section Two-Way Communications with Another Process + +@c 8/2014. Neither Mike nor BWK saw this as relevant. Commenting it out. +@ignore @cindex Brennan, Michael @cindex programmers, attractiveness of @smallexample @@ -26093,6 +26041,7 @@ the scent of perl programmers. Mike Brennan @c brennan@@whidbey.com @end smallexample +@end ignore @cindex advanced features, processes@comma{} communicating with @cindex processes, two-way communications with @@ -26119,7 +26068,10 @@ system("rm " tempfile) This works, but not elegantly. Among other things, it requires that the program be run in a directory that cannot be shared among users; for example, @file{/tmp} will not do, as another user might happen -to be using a temporary file with the same name. +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 @cindex coprocesses @cindex input/output, two-way @@ -26274,7 +26226,7 @@ You can think of this as just a @emph{very long} two-way pipeline to a coprocess. The way @command{gawk} decides that you want to use TCP/IP networking is by recognizing special @value{FN}s that begin with one of @samp{/inet/}, -@samp{/inet4/} or @samp{/inet6}. +@samp{/inet4/} or @samp{/inet6/}. The full syntax of the special @value{FN} is @file{/@var{net-type}/@var{protocol}/@var{local-port}/@var{remote-host}/@var{remote-port}}. @@ -28907,6 +28859,12 @@ arbitrary precision integers, and concludes with a description of some points where @command{gawk} and the POSIX standard are not quite in agreement. +@quotation NOTE +Most users of @command{gawk} can safely skip this chapter. +But if you want to do scientific calculations with @command{gawk}, +this is the place to be. +@end quotation + @menu * Computer Arithmetic:: A quick intro to computer math. * Math Definitions:: Defining terms used. @@ -29026,8 +28984,23 @@ A special value representing infinity. Operations involving another number and infinity produce infinity. @item NaN -``Not A Number.'' A special value indicating a result that can't -happen in real math, but that can happen in floating-point computations. +``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: + +@table @code +@item sqrt(-1) +This makes sense in the range of complex numbers, but not in the +range of real numbers, so the result is @code{NaN}. + +@item log(-8) +@minus{}8 is out of the domain of @code{log()}, so the result is @code{NaN}. +@end table @item Normalized How the significand (see later in this list) is usually stored. The @@ -29445,7 +29418,7 @@ internally as a 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 -than the default and cannot use a command line assignment to @code{PREC}, +than the default and cannot use a command-line assignment to @code{PREC}, you should either specify the constant as a string, or as a rational number, whenever possible. The following example illustrates the differences among various ways to print a floating-point constant: @@ -30079,7 +30052,7 @@ Some other bits and pieces: @itemize @value{BULLET} @item The API provides access to @command{gawk}'s @code{do_@var{xxx}} values, -reflecting command line options, like @code{do_lint}, @code{do_profiling} +reflecting command-line options, like @code{do_lint}, @code{do_profiling} and so on (@pxref{Extension API Variables}). These are informational: an extension cannot affect their values inside @command{gawk}. In addition, attempting to assign to them @@ -34295,7 +34268,7 @@ Indirect function calls @item Directories on the command line produce a warning and are skipped -(@pxref{Command line directories}). +(@pxref{Command-line directories}). @end itemize @item @@ -34642,7 +34615,7 @@ The ability to delete all of an array at once with @samp{delete @var{array}} (@pxref{Delete}). @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -34705,7 +34678,7 @@ Brian Kernighan's @command{awk} @pxref{I/O Functions}). @item -New command line options: +New command-line options: @itemize @value{MINUS} @item @@ -34995,7 +34968,7 @@ Indirect function calls (@pxref{Switch Statement}). @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -35020,7 +34993,7 @@ All long options acquired corresponding short options, for use in @samp{#!} scri @item Directories named on the command line now produce a warning, not a fatal error, unless @option{--posix} or @option{--traditional} are used -(@pxref{Command line directories}). +(@pxref{Command-line directories}). @item The @command{gawk} internals were rewritten, bringing the @command{dgawk} @@ -35096,10 +35069,10 @@ Three new arrays: @item The three executables @command{gawk}, @command{pgawk}, and @command{dgawk}, were merged into -one, named just @command{gawk}. As a result the command line options changed. +one, named just @command{gawk}. As a result the command-line options changed. @item -Command line option changes +Command-line option changes (@pxref{Options}): @itemize @value{MINUS} @@ -40477,13 +40450,14 @@ Consistency issues: Use "zeros" instead of "zeroes". Use "nonzero" not "non-zero". Use "runtime" not "run time" or "run-time". - Use "command-line" not "command line". + Use "command-line" as an adjective and "command line" as a noun. Use "online" not "on-line". Use "whitespace" not "white space". Use "Input/Output", not "input/output". Also "I/O", not "i/o". Use "lefthand"/"righthand", not "left-hand"/"right-hand". Use "workaround", not "work-around". Use "startup"/"cleanup", not "start-up"/"clean-up" + Use "filesystem", not "file system" Use @code{do}, and not @code{do}-@code{while}, except where actually discussing the do-while. Use "versus" in text and "vs." in index entries @@ -40498,8 +40472,6 @@ Consistency issues: The numbers zero through ten should be spelled out, except when talking about file descriptor numbers. > 10 and < 0, it's ok to use numbers. - In tables, put command-line options in @code, while in the text, - put them in @option. For most cases, do NOT put a comma before "and", "or" or "but". But exercise taste with this rule. Don't show the awk command with a program in quotes when it's @@ -825,7 +825,7 @@ usage(int exitval, FILE *fp) fputs(_("\t-h\t\t\t--help\n"), fp); fputs(_("\t-i includefile\t\t--include=includefile\n"), fp); fputs(_("\t-l library\t\t--load=library\n"), fp); - fputs(_("\t-L [fatal]\t\t--lint[=fatal]\n"), fp); + fputs(_("\t-L[fatal|invalid]\t--lint[=fatal|invalid]\n"), fp); fputs(_("\t-M\t\t\t--bignum\n"), fp); fputs(_("\t-N\t\t\t--use-lc-numeric\n"), fp); fputs(_("\t-n\t\t\t--non-decimal-data\n"), fp); diff --git a/test/ChangeLog b/test/ChangeLog index 61b8cd3b..8f8c9c31 100644 --- a/test/ChangeLog +++ b/test/ChangeLog @@ -1,3 +1,7 @@ +2014-08-15 Arnold D. Robbins <arnold@skeeve.com> + + * badargs.ok: Adjust after revising text for -L option. + 2014-08-12 Arnold D. Robbins <arnold@skeeve.com> * ofs1.ok: Updated to match corrected behavior in gawk. diff --git a/test/badargs.ok b/test/badargs.ok index 8d34be1f..1664ec1c 100644 --- a/test/badargs.ok +++ b/test/badargs.ok @@ -17,7 +17,7 @@ Short options: GNU long options: (extensions) -h --help -i includefile --include=includefile -l library --load=library - -L [fatal] --lint[=fatal] + -L[fatal|invalid] --lint[=fatal|invalid] -M --bignum -N --use-lc-numeric -n --non-decimal-data |