diff options
| -rw-r--r-- | awklib/eg/lib/assert.awk | 2 | ||||
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 720 | ||||
| -rw-r--r-- | doc/gawk.texi | 94 | ||||
| -rw-r--r-- | doc/gawktexi.in | 91 |
5 files changed, 460 insertions, 451 deletions
diff --git a/awklib/eg/lib/assert.awk b/awklib/eg/lib/assert.awk index 75fd8853..c8e13490 100644 --- a/awklib/eg/lib/assert.awk +++ b/awklib/eg/lib/assert.awk @@ -1,4 +1,4 @@ -# assert --- assert that a condition is true. Otherwise exit. +# assert --- assert that a condition is true. Otherwise, exit. # # Arnold Robbins, arnold@skeeve.com, Public Domain diff --git a/doc/ChangeLog b/doc/ChangeLog index 75a5e6a3..827d9aa1 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2015-02-02 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: O'Reilly fixes. + 2015-02-01 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: POSIX requirement that function parameters cannot diff --git a/doc/gawk.info b/doc/gawk.info index 4176eb81..3abb4f41 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -14457,7 +14457,7 @@ File: gawk.info, Node: Library Functions, Next: Sample Programs, Prev: Functi *note User-defined::, describes how to write your own `awk' functions. Writing functions is important, because it allows you to encapsulate algorithms and program tasks in a single place. It simplifies -programming, making program development more manageable, and making +programming, making program development more manageable and making programs more readable. In their seminal 1976 book, `Software Tools',(1) Brian Kernighan and @@ -14562,7 +14562,7 @@ often use variable names like these for their own purposes. The example programs shown in this major node all start the names of their private variables with an underscore (`_'). Users generally don't use leading underscores in their variable names, so this -convention immediately decreases the chances that the variable name +convention immediately decreases the chances that the variable names will be accidentally shared with the user's program. In addition, several of the library functions use a prefix that helps @@ -14575,7 +14575,7 @@ for private function names.(1) As a final note on variable naming, if a function makes global variables available for use by a main program, it is a good convention -to start that variable's name with a capital letter--for example, +to start those variables' names with a capital letter--for example, `getopt()''s `Opterr' and `Optind' variables (*note Getopt Function::). The leading capital letter indicates that it is global, while the fact that the variable name is not all capital letters indicates that the @@ -14583,7 +14583,7 @@ variable is not one of `awk''s predefined variables, such as `FS'. It is also important that _all_ variables in library functions that do not need to save state are, in fact, declared local.(2) If this is -not done, the variable could accidentally be used in the user's +not done, the variables could accidentally be used in the user's program, leading to bugs that are very difficult to track down: function lib_func(x, y, l1, l2) @@ -14761,7 +14761,7 @@ for use in printing the diagnostic message. This is not possible in `awk', so this `assert()' function also requires a string version of the condition that is being tested. Following is the function: - # assert --- assert that a condition is true. Otherwise exit. + # assert --- assert that a condition is true. Otherwise, exit. function assert(condition, string) { @@ -14782,7 +14782,7 @@ the condition that is being tested. Following is the function: false, it prints a message to standard error, using the `string' parameter to describe the failed condition. It then sets the variable `_assert_exit' to one and executes the `exit' statement. The `exit' -statement jumps to the `END' rule. If the `END' rules finds +statement jumps to the `END' rule. If the `END' rule finds `_assert_exit' to be true, it exits immediately. The purpose of the test in the `END' rule is to keep any other `END' @@ -14997,9 +14997,9 @@ the strings in an array into one long string. The following function, `join()', accomplishes this task. It is used later in several of the application programs (*note Sample Programs::). - Good function design is important; this function needs to be general -but it should also have a reasonable default behavior. It is called -with an array as well as the beginning and ending indices of the + Good function design is important; this function needs to be +general, but it should also have a reasonable default behavior. It is +called with an array as well as the beginning and ending indices of the elements in the array to be merged. This assumes that the array indices are numeric--a reasonable assumption, as the array was likely created with `split()' (*note String Functions::): @@ -15118,7 +15118,7 @@ optional timestamp value to use instead of the current time. File: gawk.info, Node: Readfile Function, Next: Shell Quoting, Prev: Getlocaltime Function, Up: General Functions -10.2.8 Reading a Whole File At Once +10.2.8 Reading a Whole File at Once ----------------------------------- Often, it is convenient to have the entire contents of a file available @@ -15160,13 +15160,13 @@ reads the entire contents of the named file in one shot: It works by setting `RS' to `^$', a regular expression that will never match if the file has contents. `gawk' reads data from the file -into `tmp' attempting to match `RS'. The match fails after each read, +into `tmp', attempting to match `RS'. The match fails after each read, but fails quickly, such that `gawk' fills `tmp' with the entire contents of the file. (*Note Records::, for information on `RT' and `RS'.) In the case that `file' is empty, the return value is the null -string. Thus calling code may use something like: +string. Thus, calling code may use something like: contents = readfile("/some/path") if (length(contents) == 0) @@ -15256,8 +15256,9 @@ File: gawk.info, Node: Filetrans Function, Next: Rewind Function, Up: Data Fi The `BEGIN' and `END' rules are each executed exactly once, at the beginning and end of your `awk' program, respectively (*note BEGIN/END::). We (the `gawk' authors) once had a user who mistakenly -thought that the `BEGIN' rule is executed at the beginning of each data -file and the `END' rule is executed at the end of each data file. +thought that the `BEGIN' rules were executed at the beginning of each +data file and the `END' rules were executed at the end of each data +file. When informed that this was not the case, the user requested that we add new special patterns to `gawk', named `BEGIN_FILE' and `END_FILE', @@ -15291,7 +15292,7 @@ does so _portably_; this works with any implementation of `awk': This file must be loaded before the user's "main" program, so that the rule it supplies is executed first. - This rule relies on `awk''s `FILENAME' variable that automatically + This rule relies on `awk''s `FILENAME' variable, which automatically changes for each new data file. The current file name is saved in a private variable, `_oldfilename'. If `FILENAME' does not equal `_oldfilename', then a new data file is being processed and it is @@ -15306,7 +15307,7 @@ correctly even for the first data file. The program also supplies an `END' rule to do the final processing for the last file. Because this `END' rule comes before any `END' rules supplied in the "main" program, `endfile()' is called first. Once -again the value of multiple `BEGIN' and `END' rules should be clear. +again, the value of multiple `BEGIN' and `END' rules should be clear. If the same data file occurs twice in a row on the command line, then `endfile()' and `beginfile()' are not executed at the end of the first @@ -15333,7 +15334,7 @@ how it simplifies writing the main program. You are probably wondering, if `beginfile()' and `endfile()' functions can do the job, why does `gawk' have `BEGINFILE' and -`ENDFILE' patterns (*note BEGINFILE/ENDFILE::)? +`ENDFILE' patterns? Good question. Normally, if `awk' cannot open a file, this causes an immediate fatal error. In this case, there is no way for a @@ -15341,7 +15342,8 @@ user-defined function to deal with the problem, as the mechanism for calling it relies on the file being open and at the first record. Thus, the main reason for `BEGINFILE' is to give you a "hook" to catch files that cannot be processed. `ENDFILE' exists for symmetry, and because -it provides an easy way to do per-file cleanup processing. +it provides an easy way to do per-file cleanup processing. For more +information, refer to *note BEGINFILE/ENDFILE::. File: gawk.info, Node: Rewind Function, Next: File Checking, Prev: Filetrans Function, Up: Data File Management @@ -15349,15 +15351,14 @@ File: gawk.info, Node: Rewind Function, Next: File Checking, Prev: Filetrans 10.3.2 Rereading the Current File --------------------------------- -Another request for a new built-in function was for a `rewind()' -function that would make it possible to reread the current file. The -requesting user didn't want to have to use `getline' (*note Getline::) -inside a loop. +Another request for a new built-in function was for a function that +would make it possible to reread the current file. The requesting user +didn't want to have to use `getline' (*note Getline::) inside a loop. However, as long as you are not in the `END' rule, it is quite easy to arrange to immediately close the current input file and then start -over with it from the top. For lack of a better name, we'll call it -`rewind()': +over with it from the top. For lack of a better name, we'll call the +function `rewind()': # rewind.awk --- rewind the current file and start over @@ -15415,7 +15416,7 @@ longer in the list). See also *note ARGC and ARGV::. Because `awk' variable names only allow the English letters, the regular expression check purposely does not use character classes such -as `[:alpha:]' and `[:alnum:]' (*note Bracket Expressions::) +as `[:alpha:]' and `[:alnum:]' (*note Bracket Expressions::). ---------- Footnotes ---------- @@ -15426,14 +15427,14 @@ opened. However, the code here provides a portable solution. File: gawk.info, Node: Empty Files, Next: Ignoring Assigns, Prev: File Checking, Up: Data File Management -10.3.4 Checking for Zero-length Files +10.3.4 Checking for Zero-Length Files ------------------------------------- All known `awk' implementations silently skip over zero-length files. This is a by-product of `awk''s implicit read-a-record-and-match-against-the-rules loop: when `awk' tries to -read a record from an empty file, it immediately receives an end of -file indication, closes the file, and proceeds on to the next +read a record from an empty file, it immediately receives an +end-of-file indication, closes the file, and proceeds on to the next command-line data file, _without_ executing any user-level `awk' program code. @@ -15483,7 +15484,7 @@ File: gawk.info, Node: Ignoring Assigns, Prev: Empty Files, Up: Data File Man Occasionally, you might not want `awk' to process command-line variable assignments (*note Assignment Options::). In particular, if you have a file name that contains an `=' character, `awk' treats the file name as -an assignment, and does not process it. +an assignment and does not process it. Some users have suggested an additional command-line option for `gawk' to disable command-line assignments. However, some simple @@ -15773,8 +15774,8 @@ which is in `ARGV[0]': } } - The rest of the `BEGIN' rule is a simple test program. Here is the -result of two sample runs of the test program: + The rest of the `BEGIN' rule is a simple test program. Here are the +results of two sample runs of the test program: $ awk -f getopt.awk -v _getopt_test=1 -- -a -cbARG bax -x -| c = <a>, Optarg = <> @@ -15820,10 +15821,10 @@ File: gawk.info, Node: Passwd Functions, Next: Group Functions, Prev: Getopt ============================== The `PROCINFO' array (*note Built-in Variables::) provides access to -the current user's real and effective user and group ID numbers, and if -available, the user's supplementary group set. However, because these -are numbers, they do not provide very useful information to the average -user. There needs to be some way to find the user information +the current user's real and effective user and group ID numbers, and, +if available, the user's supplementary group set. However, because +these are numbers, they do not provide very useful information to the +average user. There needs to be some way to find the user information associated with the user and group ID numbers. This minor node presents a suite of functions for retrieving information from the user database. *Note Group Functions::, for a similar suite that retrieves @@ -15834,7 +15835,7 @@ kept. Instead, it provides the `<pwd.h>' header file and several C language subroutines for obtaining user information. The primary function is `getpwent()', for "get password entry." The "password" comes from the original user database file, `/etc/passwd', which stores -user information, along with the encrypted passwords (hence the name). +user information along with the encrypted passwords (hence the name). Although an `awk' program could simply read `/etc/passwd' directly, this file may not contain complete information about the system's set @@ -15882,7 +15883,7 @@ Encrypted password User-ID The user's numeric user ID number. (On some systems, it's a C - `long', and not an `int'. Thus we cast it to `long' for all + `long', and not an `int'. Thus, we cast it to `long' for all cases.) Group-ID @@ -15981,8 +15982,8 @@ or on some other `awk' implementation. `PROCINFO["FS"]', is similar. The main part of the function uses a loop to read database lines, -split the line into fields, and then store the line into each array as -necessary. When the loop is done, `_pw_init()' cleans up by closing +split the lines into fields, and then store the lines into each array +as necessary. When the loop is done, `_pw_init()' cleans up by closing the pipeline, setting `_pw_inited' to one, and restoring `FS' (and `FIELDWIDTHS' or `FPAT' if necessary), `RS', and `$0'. The use of `_pw_count' is explained shortly. @@ -16110,7 +16111,7 @@ Group Password Group ID Number The group's numeric group ID number; the association of name to number must be unique within the file. (On some systems it's a C - `long', and not an `int'. Thus we cast it to `long' for all + `long', and not an `int'. Thus, we cast it to `long' for all cases.) Group Member List @@ -16200,29 +16201,30 @@ to ensure that the database is scanned no more than once. The `_gr_init()' function first saves `FS', `RS', and `$0', and then sets `FS' and `RS' to the correct values for scanning the group information. It also takes care to note whether `FIELDWIDTHS' or `FPAT' is being -used, and to restore the appropriate field splitting mechanism. +used, and to restore the appropriate field-splitting mechanism. - The group information is stored is several associative arrays. The + The group information is stored in several associative arrays. The arrays are indexed by group name (`_gr_byname'), by group ID number (`_gr_bygid'), and by position in the database (`_gr_bycount'). There is an additional array indexed by username (`_gr_groupsbyuser'), which is a space-separated list of groups to which each user belongs. - Unlike the user database, it is possible to have multiple records in -the database for the same group. This is common when a group has a + Unlike in the user database, it is possible to have multiple records +in the database for the same group. This is common when a group has a large number of members. A pair of such entries might look like the following: - tvpeople:*:101:johny,jay,arsenio + tvpeople:*:101:johnny,jay,arsenio tvpeople:*:101:david,conan,tom,joan For this reason, `_gr_init()' looks to see if a group name or group -ID number is already seen. If it is, the usernames are simply +ID number is already seen. If so, the usernames are simply concatenated onto the previous list of users.(1) Finally, `_gr_init()' closes the pipeline to `grcat', restores `FS' -(and `FIELDWIDTHS' or `FPAT' if necessary), `RS', and `$0', initializes -`_gr_count' to zero (it is used later), and makes `_gr_inited' nonzero. +(and `FIELDWIDTHS' or `FPAT', if necessary), `RS', and `$0', +initializes `_gr_count' to zero (it is used later), and makes +`_gr_inited' nonzero. The `getgrnam()' function takes a group name as its argument, and if that group exists, it is returned. Otherwise, it relies on the array @@ -16285,9 +16287,9 @@ very simple, relying on `awk''s associative arrays to do work. ---------- Footnotes ---------- - (1) There is actually a subtle problem with the code just presented. -Suppose that the first time there were no names. This code adds the -names with a leading comma. It also doesn't check that there is a `$4'. + (1) There is a subtle problem with the code just presented. Suppose +that the first time there were no names. This code adds the names with +a leading comma. It also doesn't check that there is a `$4'. File: gawk.info, Node: Walking Arrays, Next: Library Functions Summary, Prev: Group Functions, Up: Library Functions @@ -16296,11 +16298,11 @@ File: gawk.info, Node: Walking Arrays, Next: Library Functions Summary, Prev: ================================ *note Arrays of Arrays::, described how `gawk' provides arrays of -arrays. In particular, any element of an array may be either a scalar, +arrays. In particular, any element of an array may be either a scalar or another array. The `isarray()' function (*note Type Functions::) lets you distinguish an array from a scalar. The following function, -`walk_array()', recursively traverses an array, printing each element's -indices and value. You call it with the array and a string +`walk_array()', recursively traverses an array, printing the element +indices and values. You call it with the array and a string representing the name of the array: function walk_array(arr, name, i) @@ -16357,24 +16359,24 @@ File: gawk.info, Node: Library Functions Summary, Next: Library Exercises, Pr * The functions presented here fit into the following categories: General problems - Number-to-string conversion, assertions, rounding, random - number generation, converting characters to numbers, joining - strings, getting easily usable time-of-day information, and - reading a whole file in one shot. + Number-to-string conversion, testing assertions, rounding, + random number generation, converting characters to numbers, + joining strings, getting easily usable time-of-day + information, and reading a whole file in one shot Managing data files Noting data file boundaries, rereading the current file, checking for readable files, checking for zero-length files, - and treating assignments as file names. + and treating assignments as file names Processing command-line options - An `awk' version of the standard C `getopt()' function. + An `awk' version of the standard C `getopt()' function Reading the user and group databases - Two sets of routines that parallel the C library versions. + Two sets of routines that parallel the C library versions Traversing arrays of arrays - A simple function to traverse an array of arrays to any depth. + A simple function to traverse an array of arrays to any depth @@ -32116,7 +32118,7 @@ Index * BEGINFILE pattern: BEGINFILE/ENDFILE. (line 6) * BEGINFILE pattern, Boolean patterns and: Expression Patterns. (line 69) -* beginfile() user-defined function: Filetrans Function. (line 61) +* beginfile() user-defined function: Filetrans Function. (line 62) * Bentley, Jon: Glossary. (line 207) * Benzinger, Michael: Contributors. (line 97) * Berry, Karl <1>: Ranges and Locales. (line 74) @@ -32736,9 +32738,9 @@ Index * END pattern, print statement and: I/O And BEGIN/END. (line 16) * ENDFILE pattern: BEGINFILE/ENDFILE. (line 6) * ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 69) -* endfile() user-defined function: Filetrans Function. (line 61) -* endgrent() function (C library): Group Functions. (line 211) -* endgrent() user-defined function: Group Functions. (line 214) +* endfile() user-defined function: Filetrans Function. (line 62) +* endgrent() function (C library): Group Functions. (line 212) +* endgrent() user-defined function: Group Functions. (line 215) * endpwent() function (C library): Passwd Functions. (line 207) * endpwent() user-defined function: Passwd Functions. (line 210) * English, Steve: Advanced Features. (line 6) @@ -33172,12 +33174,12 @@ Index * getaddrinfo() function (C library): TCP/IP Networking. (line 38) * getgrent() function (C library): Group Functions. (line 6) * getgrent() user-defined function: Group Functions. (line 6) -* getgrgid() function (C library): Group Functions. (line 182) -* getgrgid() user-defined function: Group Functions. (line 185) -* getgrnam() function (C library): Group Functions. (line 171) -* getgrnam() user-defined function: Group Functions. (line 176) -* getgruser() function (C library): Group Functions. (line 191) -* getgruser() function, user-defined: Group Functions. (line 194) +* getgrgid() function (C library): Group Functions. (line 183) +* getgrgid() user-defined function: Group Functions. (line 186) +* getgrnam() function (C library): Group Functions. (line 172) +* getgrnam() user-defined function: Group Functions. (line 177) +* getgruser() function (C library): Group Functions. (line 192) +* getgruser() function, user-defined: Group Functions. (line 195) * getline command: Reading Files. (line 20) * getline command, _gr_init() user-defined function: Group Functions. (line 83) @@ -34048,7 +34050,7 @@ Index (line 11) * revtwoway extension: Extension Sample Rev2way. (line 12) -* rewind() user-defined function: Rewind Function. (line 16) +* rewind() user-defined function: Rewind Function. (line 15) * right angle bracket (>), > operator <1>: Precedence. (line 65) * right angle bracket (>), > operator: Comparison Operators. (line 11) @@ -34209,7 +34211,7 @@ Index * sidebar, Recipe for a Programming Language: History. (line 6) * sidebar, RS = "\0" Is Not Portable: gawk split records. (line 63) * sidebar, So Why Does gawk Have BEGINFILE and ENDFILE?: Filetrans Function. - (line 82) + (line 83) * sidebar, Syntactic Ambiguities Between /= and Regular Expressions: Assignment Ops. (line 146) * sidebar, Understanding #!: Executable Scripts. (line 31) @@ -34896,290 +34898,290 @@ Node: Indirect Calls588592 Ref: Indirect Calls-Footnote-1599898 Node: Functions Summary600026 Node: Library Functions602728 -Ref: Library Functions-Footnote-1606337 -Ref: Library Functions-Footnote-2606480 -Node: Library Names606651 -Ref: Library Names-Footnote-1610105 -Ref: Library Names-Footnote-2610328 -Node: General Functions610414 -Node: Strtonum Function611517 -Node: Assert Function614539 -Node: Round Function617863 -Node: Cliff Random Function619404 -Node: Ordinal Functions620420 -Ref: Ordinal Functions-Footnote-1623483 -Ref: Ordinal Functions-Footnote-2623735 -Node: Join Function623946 -Ref: Join Function-Footnote-1625715 -Node: Getlocaltime Function625915 -Node: Readfile Function629659 -Node: Shell Quoting631629 -Node: Data File Management633030 -Node: Filetrans Function633662 -Node: Rewind Function637718 -Node: File Checking639105 -Ref: File Checking-Footnote-1640437 -Node: Empty Files640638 -Node: Ignoring Assigns642617 -Node: Getopt Function644168 -Ref: Getopt Function-Footnote-1655630 -Node: Passwd Functions655830 -Ref: Passwd Functions-Footnote-1664667 -Node: Group Functions664755 -Ref: Group Functions-Footnote-1672649 -Node: Walking Arrays672862 -Node: Library Functions Summary674465 -Node: Library Exercises675866 -Node: Sample Programs677146 -Node: Running Examples677916 -Node: Clones678644 -Node: Cut Program679868 -Node: Egrep Program689587 -Ref: Egrep Program-Footnote-1697085 -Node: Id Program697195 -Node: Split Program700840 -Ref: Split Program-Footnote-1704288 -Node: Tee Program704416 -Node: Uniq Program707205 -Node: Wc Program714624 -Ref: Wc Program-Footnote-1718874 -Node: Miscellaneous Programs718968 -Node: Dupword Program720181 -Node: Alarm Program722212 -Node: Translate Program727016 -Ref: Translate Program-Footnote-1731581 -Node: Labels Program731851 -Ref: Labels Program-Footnote-1735202 -Node: Word Sorting735286 -Node: History Sorting739357 -Node: Extract Program741193 -Node: Simple Sed748718 -Node: Igawk Program751786 -Ref: Igawk Program-Footnote-1766110 -Ref: Igawk Program-Footnote-2766311 -Ref: Igawk Program-Footnote-3766433 -Node: Anagram Program766548 -Node: Signature Program769605 -Node: Programs Summary770852 -Node: Programs Exercises772045 -Ref: Programs Exercises-Footnote-1776176 -Node: Advanced Features776267 -Node: Nondecimal Data778215 -Node: Array Sorting779805 -Node: Controlling Array Traversal780502 -Ref: Controlling Array Traversal-Footnote-1788835 -Node: Array Sorting Functions788953 -Ref: Array Sorting Functions-Footnote-1792842 -Node: Two-way I/O793038 -Ref: Two-way I/O-Footnote-1797983 -Ref: Two-way I/O-Footnote-2798169 -Node: TCP/IP Networking798251 -Node: Profiling801124 -Node: Advanced Features Summary809401 -Node: Internationalization811334 -Node: I18N and L10N812814 -Node: Explaining gettext813500 -Ref: Explaining gettext-Footnote-1818525 -Ref: Explaining gettext-Footnote-2818709 -Node: Programmer i18n818874 -Ref: Programmer i18n-Footnote-1823740 -Node: Translator i18n823789 -Node: String Extraction824583 -Ref: String Extraction-Footnote-1825714 -Node: Printf Ordering825800 -Ref: Printf Ordering-Footnote-1828586 -Node: I18N Portability828650 -Ref: I18N Portability-Footnote-1831105 -Node: I18N Example831168 -Ref: I18N Example-Footnote-1833971 -Node: Gawk I18N834043 -Node: I18N Summary834681 -Node: Debugger836020 -Node: Debugging837042 -Node: Debugging Concepts837483 -Node: Debugging Terms839336 -Node: Awk Debugging841908 -Node: Sample Debugging Session842802 -Node: Debugger Invocation843322 -Node: Finding The Bug844706 -Node: List of Debugger Commands851181 -Node: Breakpoint Control852514 -Node: Debugger Execution Control856210 -Node: Viewing And Changing Data859574 -Node: Execution Stack862952 -Node: Debugger Info864589 -Node: Miscellaneous Debugger Commands868606 -Node: Readline Support873635 -Node: Limitations874527 -Node: Debugging Summary876641 -Node: Arbitrary Precision Arithmetic877809 -Node: Computer Arithmetic879225 -Ref: table-numeric-ranges882823 -Ref: Computer Arithmetic-Footnote-1883682 -Node: Math Definitions883739 -Ref: table-ieee-formats887027 -Ref: Math Definitions-Footnote-1887631 -Node: MPFR features887736 -Node: FP Math Caution889407 -Ref: FP Math Caution-Footnote-1890457 -Node: Inexactness of computations890826 -Node: Inexact representation891785 -Node: Comparing FP Values893142 -Node: Errors accumulate894224 -Node: Getting Accuracy895657 -Node: Try To Round898319 -Node: Setting precision899218 -Ref: table-predefined-precision-strings899902 -Node: Setting the rounding mode901691 -Ref: table-gawk-rounding-modes902055 -Ref: Setting the rounding mode-Footnote-1905510 -Node: Arbitrary Precision Integers905689 -Ref: Arbitrary Precision Integers-Footnote-1910589 -Node: POSIX Floating Point Problems910738 -Ref: POSIX Floating Point Problems-Footnote-1914611 -Node: Floating point summary914649 -Node: Dynamic Extensions916843 -Node: Extension Intro918395 -Node: Plugin License919661 -Node: Extension Mechanism Outline920458 -Ref: figure-load-extension920886 -Ref: figure-register-new-function922366 -Ref: figure-call-new-function923370 -Node: Extension API Description925356 -Node: Extension API Functions Introduction926806 -Node: General Data Types931630 -Ref: General Data Types-Footnote-1937369 -Node: Memory Allocation Functions937668 -Ref: Memory Allocation Functions-Footnote-1940507 -Node: Constructor Functions940603 -Node: Registration Functions942337 -Node: Extension Functions943022 -Node: Exit Callback Functions945319 -Node: Extension Version String946567 -Node: Input Parsers947232 -Node: Output Wrappers957111 -Node: Two-way processors961626 -Node: Printing Messages963830 -Ref: Printing Messages-Footnote-1964906 -Node: Updating `ERRNO'965058 -Node: Requesting Values965798 -Ref: table-value-types-returned966526 -Node: Accessing Parameters967483 -Node: Symbol Table Access968714 -Node: Symbol table by name969228 -Node: Symbol table by cookie971209 -Ref: Symbol table by cookie-Footnote-1975353 -Node: Cached values975416 -Ref: Cached values-Footnote-1978915 -Node: Array Manipulation979006 -Ref: Array Manipulation-Footnote-1980104 -Node: Array Data Types980141 -Ref: Array Data Types-Footnote-1982796 -Node: Array Functions982888 -Node: Flattening Arrays986742 -Node: Creating Arrays993634 -Node: Extension API Variables998405 -Node: Extension Versioning999041 -Node: Extension API Informational Variables1000942 -Node: Extension API Boilerplate1002007 -Node: Finding Extensions1005816 -Node: Extension Example1006376 -Node: Internal File Description1007148 -Node: Internal File Ops1011215 -Ref: Internal File Ops-Footnote-11022885 -Node: Using Internal File Ops1023025 -Ref: Using Internal File Ops-Footnote-11025408 -Node: Extension Samples1025681 -Node: Extension Sample File Functions1027207 -Node: Extension Sample Fnmatch1034845 -Node: Extension Sample Fork1036336 -Node: Extension Sample Inplace1037551 -Node: Extension Sample Ord1039226 -Node: Extension Sample Readdir1040062 -Ref: table-readdir-file-types1040938 -Node: Extension Sample Revout1041749 -Node: Extension Sample Rev2way1042339 -Node: Extension Sample Read write array1043079 -Node: Extension Sample Readfile1045019 -Node: Extension Sample Time1046114 -Node: Extension Sample API Tests1047463 -Node: gawkextlib1047954 -Node: Extension summary1050612 -Node: Extension Exercises1054301 -Node: Language History1055023 -Node: V7/SVR3.11056679 -Node: SVR41058860 -Node: POSIX1060305 -Node: BTL1061694 -Node: POSIX/GNU1062428 -Node: Feature History1068052 -Node: Common Extensions1081150 -Node: Ranges and Locales1082474 -Ref: Ranges and Locales-Footnote-11087092 -Ref: Ranges and Locales-Footnote-21087119 -Ref: Ranges and Locales-Footnote-31087353 -Node: Contributors1087574 -Node: History summary1093115 -Node: Installation1094485 -Node: Gawk Distribution1095431 -Node: Getting1095915 -Node: Extracting1096738 -Node: Distribution contents1098373 -Node: Unix Installation1104438 -Node: Quick Installation1105121 -Node: Shell Startup Files1107532 -Node: Additional Configuration Options1108611 -Node: Configuration Philosophy1110350 -Node: Non-Unix Installation1112719 -Node: PC Installation1113177 -Node: PC Binary Installation1114496 -Node: PC Compiling1116344 -Ref: PC Compiling-Footnote-11119365 -Node: PC Testing1119474 -Node: PC Using1120650 -Node: Cygwin1124765 -Node: MSYS1125588 -Node: VMS Installation1126088 -Node: VMS Compilation1126880 -Ref: VMS Compilation-Footnote-11128102 -Node: VMS Dynamic Extensions1128160 -Node: VMS Installation Details1129844 -Node: VMS Running1132096 -Node: VMS GNV1134932 -Node: VMS Old Gawk1135666 -Node: Bugs1136136 -Node: Other Versions1140019 -Node: Installation summary1146443 -Node: Notes1147499 -Node: Compatibility Mode1148364 -Node: Additions1149146 -Node: Accessing The Source1150071 -Node: Adding Code1151506 -Node: New Ports1157663 -Node: Derived Files1162145 -Ref: Derived Files-Footnote-11167620 -Ref: Derived Files-Footnote-21167654 -Ref: Derived Files-Footnote-31168250 -Node: Future Extensions1168364 -Node: Implementation Limitations1168970 -Node: Extension Design1170218 -Node: Old Extension Problems1171372 -Ref: Old Extension Problems-Footnote-11172889 -Node: Extension New Mechanism Goals1172946 -Ref: Extension New Mechanism Goals-Footnote-11176306 -Node: Extension Other Design Decisions1176495 -Node: Extension Future Growth1178603 -Node: Old Extension Mechanism1179439 -Node: Notes summary1181201 -Node: Basic Concepts1182387 -Node: Basic High Level1183068 -Ref: figure-general-flow1183340 -Ref: figure-process-flow1183939 -Ref: Basic High Level-Footnote-11187168 -Node: Basic Data Typing1187353 -Node: Glossary1190681 -Node: Copying1222610 -Node: GNU Free Documentation License1260166 -Node: Index1285302 +Ref: Library Functions-Footnote-1606336 +Ref: Library Functions-Footnote-2606479 +Node: Library Names606650 +Ref: Library Names-Footnote-1610108 +Ref: Library Names-Footnote-2610331 +Node: General Functions610417 +Node: Strtonum Function611520 +Node: Assert Function614542 +Node: Round Function617866 +Node: Cliff Random Function619407 +Node: Ordinal Functions620423 +Ref: Ordinal Functions-Footnote-1623486 +Ref: Ordinal Functions-Footnote-2623738 +Node: Join Function623949 +Ref: Join Function-Footnote-1625719 +Node: Getlocaltime Function625919 +Node: Readfile Function629663 +Node: Shell Quoting631635 +Node: Data File Management633036 +Node: Filetrans Function633668 +Node: Rewind Function637764 +Node: File Checking639150 +Ref: File Checking-Footnote-1640483 +Node: Empty Files640684 +Node: Ignoring Assigns642663 +Node: Getopt Function644213 +Ref: Getopt Function-Footnote-1655677 +Node: Passwd Functions655877 +Ref: Passwd Functions-Footnote-1664717 +Node: Group Functions664805 +Ref: Group Functions-Footnote-1672702 +Node: Walking Arrays672907 +Node: Library Functions Summary674507 +Node: Library Exercises675911 +Node: Sample Programs677191 +Node: Running Examples677961 +Node: Clones678689 +Node: Cut Program679913 +Node: Egrep Program689632 +Ref: Egrep Program-Footnote-1697130 +Node: Id Program697240 +Node: Split Program700885 +Ref: Split Program-Footnote-1704333 +Node: Tee Program704461 +Node: Uniq Program707250 +Node: Wc Program714669 +Ref: Wc Program-Footnote-1718919 +Node: Miscellaneous Programs719013 +Node: Dupword Program720226 +Node: Alarm Program722257 +Node: Translate Program727061 +Ref: Translate Program-Footnote-1731626 +Node: Labels Program731896 +Ref: Labels Program-Footnote-1735247 +Node: Word Sorting735331 +Node: History Sorting739402 +Node: Extract Program741238 +Node: Simple Sed748763 +Node: Igawk Program751831 +Ref: Igawk Program-Footnote-1766155 +Ref: Igawk Program-Footnote-2766356 +Ref: Igawk Program-Footnote-3766478 +Node: Anagram Program766593 +Node: Signature Program769650 +Node: Programs Summary770897 +Node: Programs Exercises772090 +Ref: Programs Exercises-Footnote-1776221 +Node: Advanced Features776312 +Node: Nondecimal Data778260 +Node: Array Sorting779850 +Node: Controlling Array Traversal780547 +Ref: Controlling Array Traversal-Footnote-1788880 +Node: Array Sorting Functions788998 +Ref: Array Sorting Functions-Footnote-1792887 +Node: Two-way I/O793083 +Ref: Two-way I/O-Footnote-1798028 +Ref: Two-way I/O-Footnote-2798214 +Node: TCP/IP Networking798296 +Node: Profiling801169 +Node: Advanced Features Summary809446 +Node: Internationalization811379 +Node: I18N and L10N812859 +Node: Explaining gettext813545 +Ref: Explaining gettext-Footnote-1818570 +Ref: Explaining gettext-Footnote-2818754 +Node: Programmer i18n818919 +Ref: Programmer i18n-Footnote-1823785 +Node: Translator i18n823834 +Node: String Extraction824628 +Ref: String Extraction-Footnote-1825759 +Node: Printf Ordering825845 +Ref: Printf Ordering-Footnote-1828631 +Node: I18N Portability828695 +Ref: I18N Portability-Footnote-1831150 +Node: I18N Example831213 +Ref: I18N Example-Footnote-1834016 +Node: Gawk I18N834088 +Node: I18N Summary834726 +Node: Debugger836065 +Node: Debugging837087 +Node: Debugging Concepts837528 +Node: Debugging Terms839381 +Node: Awk Debugging841953 +Node: Sample Debugging Session842847 +Node: Debugger Invocation843367 +Node: Finding The Bug844751 +Node: List of Debugger Commands851226 +Node: Breakpoint Control852559 +Node: Debugger Execution Control856255 +Node: Viewing And Changing Data859619 +Node: Execution Stack862997 +Node: Debugger Info864634 +Node: Miscellaneous Debugger Commands868651 +Node: Readline Support873680 +Node: Limitations874572 +Node: Debugging Summary876686 +Node: Arbitrary Precision Arithmetic877854 +Node: Computer Arithmetic879270 +Ref: table-numeric-ranges882868 +Ref: Computer Arithmetic-Footnote-1883727 +Node: Math Definitions883784 +Ref: table-ieee-formats887072 +Ref: Math Definitions-Footnote-1887676 +Node: MPFR features887781 +Node: FP Math Caution889452 +Ref: FP Math Caution-Footnote-1890502 +Node: Inexactness of computations890871 +Node: Inexact representation891830 +Node: Comparing FP Values893187 +Node: Errors accumulate894269 +Node: Getting Accuracy895702 +Node: Try To Round898364 +Node: Setting precision899263 +Ref: table-predefined-precision-strings899947 +Node: Setting the rounding mode901736 +Ref: table-gawk-rounding-modes902100 +Ref: Setting the rounding mode-Footnote-1905555 +Node: Arbitrary Precision Integers905734 +Ref: Arbitrary Precision Integers-Footnote-1910634 +Node: POSIX Floating Point Problems910783 +Ref: POSIX Floating Point Problems-Footnote-1914656 +Node: Floating point summary914694 +Node: Dynamic Extensions916888 +Node: Extension Intro918440 +Node: Plugin License919706 +Node: Extension Mechanism Outline920503 +Ref: figure-load-extension920931 +Ref: figure-register-new-function922411 +Ref: figure-call-new-function923415 +Node: Extension API Description925401 +Node: Extension API Functions Introduction926851 +Node: General Data Types931675 +Ref: General Data Types-Footnote-1937414 +Node: Memory Allocation Functions937713 +Ref: Memory Allocation Functions-Footnote-1940552 +Node: Constructor Functions940648 +Node: Registration Functions942382 +Node: Extension Functions943067 +Node: Exit Callback Functions945364 +Node: Extension Version String946612 +Node: Input Parsers947277 +Node: Output Wrappers957156 +Node: Two-way processors961671 +Node: Printing Messages963875 +Ref: Printing Messages-Footnote-1964951 +Node: Updating `ERRNO'965103 +Node: Requesting Values965843 +Ref: table-value-types-returned966571 +Node: Accessing Parameters967528 +Node: Symbol Table Access968759 +Node: Symbol table by name969273 +Node: Symbol table by cookie971254 +Ref: Symbol table by cookie-Footnote-1975398 +Node: Cached values975461 +Ref: Cached values-Footnote-1978960 +Node: Array Manipulation979051 +Ref: Array Manipulation-Footnote-1980149 +Node: Array Data Types980186 +Ref: Array Data Types-Footnote-1982841 +Node: Array Functions982933 +Node: Flattening Arrays986787 +Node: Creating Arrays993679 +Node: Extension API Variables998450 +Node: Extension Versioning999086 +Node: Extension API Informational Variables1000987 +Node: Extension API Boilerplate1002052 +Node: Finding Extensions1005861 +Node: Extension Example1006421 +Node: Internal File Description1007193 +Node: Internal File Ops1011260 +Ref: Internal File Ops-Footnote-11022930 +Node: Using Internal File Ops1023070 +Ref: Using Internal File Ops-Footnote-11025453 +Node: Extension Samples1025726 +Node: Extension Sample File Functions1027252 +Node: Extension Sample Fnmatch1034890 +Node: Extension Sample Fork1036381 +Node: Extension Sample Inplace1037596 +Node: Extension Sample Ord1039271 +Node: Extension Sample Readdir1040107 +Ref: table-readdir-file-types1040983 +Node: Extension Sample Revout1041794 +Node: Extension Sample Rev2way1042384 +Node: Extension Sample Read write array1043124 +Node: Extension Sample Readfile1045064 +Node: Extension Sample Time1046159 +Node: Extension Sample API Tests1047508 +Node: gawkextlib1047999 +Node: Extension summary1050657 +Node: Extension Exercises1054346 +Node: Language History1055068 +Node: V7/SVR3.11056724 +Node: SVR41058905 +Node: POSIX1060350 +Node: BTL1061739 +Node: POSIX/GNU1062473 +Node: Feature History1068097 +Node: Common Extensions1081195 +Node: Ranges and Locales1082519 +Ref: Ranges and Locales-Footnote-11087137 +Ref: Ranges and Locales-Footnote-21087164 +Ref: Ranges and Locales-Footnote-31087398 +Node: Contributors1087619 +Node: History summary1093160 +Node: Installation1094530 +Node: Gawk Distribution1095476 +Node: Getting1095960 +Node: Extracting1096783 +Node: Distribution contents1098418 +Node: Unix Installation1104483 +Node: Quick Installation1105166 +Node: Shell Startup Files1107577 +Node: Additional Configuration Options1108656 +Node: Configuration Philosophy1110395 +Node: Non-Unix Installation1112764 +Node: PC Installation1113222 +Node: PC Binary Installation1114541 +Node: PC Compiling1116389 +Ref: PC Compiling-Footnote-11119410 +Node: PC Testing1119519 +Node: PC Using1120695 +Node: Cygwin1124810 +Node: MSYS1125633 +Node: VMS Installation1126133 +Node: VMS Compilation1126925 +Ref: VMS Compilation-Footnote-11128147 +Node: VMS Dynamic Extensions1128205 +Node: VMS Installation Details1129889 +Node: VMS Running1132141 +Node: VMS GNV1134977 +Node: VMS Old Gawk1135711 +Node: Bugs1136181 +Node: Other Versions1140064 +Node: Installation summary1146488 +Node: Notes1147544 +Node: Compatibility Mode1148409 +Node: Additions1149191 +Node: Accessing The Source1150116 +Node: Adding Code1151551 +Node: New Ports1157708 +Node: Derived Files1162190 +Ref: Derived Files-Footnote-11167665 +Ref: Derived Files-Footnote-21167699 +Ref: Derived Files-Footnote-31168295 +Node: Future Extensions1168409 +Node: Implementation Limitations1169015 +Node: Extension Design1170263 +Node: Old Extension Problems1171417 +Ref: Old Extension Problems-Footnote-11172934 +Node: Extension New Mechanism Goals1172991 +Ref: Extension New Mechanism Goals-Footnote-11176351 +Node: Extension Other Design Decisions1176540 +Node: Extension Future Growth1178648 +Node: Old Extension Mechanism1179484 +Node: Notes summary1181246 +Node: Basic Concepts1182432 +Node: Basic High Level1183113 +Ref: figure-general-flow1183385 +Ref: figure-process-flow1183984 +Ref: Basic High Level-Footnote-11187213 +Node: Basic Data Typing1187398 +Node: Glossary1190726 +Node: Copying1222655 +Node: GNU Free Documentation License1260211 +Node: Index1285347 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index e56c8a89..33c65758 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -20533,7 +20533,7 @@ It contains the following chapters: your own @command{awk} functions. Writing functions is important, because it allows you to encapsulate algorithms and program tasks in a single place. It simplifies programming, making program development more -manageable, and making programs more readable. +manageable and making programs more readable. @cindex Kernighan, Brian @cindex Plauger, P.J.@: @@ -20662,7 +20662,7 @@ often use variable names like these for their own purposes. The example programs shown in this @value{CHAPTER} all start the names of their private variables with an underscore (@samp{_}). Users generally don't use leading underscores in their variable names, so this convention immediately -decreases the chances that the variable name will be accidentally shared +decreases the chances that the variable names will be accidentally shared with the user's program. @cindex @code{_} (underscore), in names of private variables @@ -20680,8 +20680,8 @@ show how our own @command{awk} programming style has evolved and to provide some basis for this discussion.} As a final note on variable naming, if a function makes global variables -available for use by a main program, it is a good convention to start that -variable's name with a capital letter---for +available for use by a main program, it is a good convention to start those +variables' names with a capital letter---for example, @code{getopt()}'s @code{Opterr} and @code{Optind} variables (@pxref{Getopt Function}). The leading capital letter indicates that it is global, while the fact that @@ -20692,7 +20692,7 @@ not one of @command{awk}'s predefined variables, such as @code{FS}. It is also important that @emph{all} variables in library functions that do not need to save state are, in fact, declared local.@footnote{@command{gawk}'s @option{--dump-variables} command-line -option is useful for verifying this.} If this is not done, the variable +option is useful for verifying this.} If this is not done, the variables could accidentally be used in the user's program, leading to bugs that are very difficult to track down: @@ -20890,7 +20890,7 @@ Following is the function: @example @c file eg/lib/assert.awk -# assert --- assert that a condition is true. Otherwise exit. +# assert --- assert that a condition is true. Otherwise, exit. @c endfile @ignore @@ -20926,7 +20926,7 @@ is false, it prints a message to standard error, using the @code{string} parameter to describe the failed condition. It then sets the variable @code{_assert_exit} to one and executes the @code{exit} statement. The @code{exit} statement jumps to the @code{END} rule. If the @code{END} -rules finds @code{_assert_exit} to be true, it exits immediately. +rule finds @code{_assert_exit} to be true, it exits immediately. The purpose of the test in the @code{END} rule is to keep any other @code{END} rules from running. When an assertion fails, the @@ -21218,7 +21218,7 @@ all the strings in an array into one long string. The following function, the application programs (@pxref{Sample Programs}). -Good function design is important; this function needs to be general but it +Good function design is important; this function needs to be general, but it should also have a reasonable default behavior. It is called with an array as well as the beginning and ending indices of the elements in the array to be merged. This assumes that the array indices are numeric---a reasonable @@ -21366,7 +21366,7 @@ allowed the user to supply an optional timestamp value to use instead of the current time. @node Readfile Function -@subsection Reading a Whole File At Once +@subsection Reading a Whole File at Once Often, it is convenient to have the entire contents of a file available in memory as a single string. A straightforward but naive way to @@ -21423,13 +21423,13 @@ function readfile(file, tmp, save_rs) It works by setting @code{RS} to @samp{^$}, a regular expression that will never match if the file has contents. @command{gawk} reads data from -the file into @code{tmp} attempting to match @code{RS}. The match fails +the file into @code{tmp}, attempting to match @code{RS}. The match fails after each read, but fails quickly, such that @command{gawk} fills @code{tmp} with the entire contents of the file. (@DBXREF{Records} for information on @code{RT} and @code{RS}.) In the case that @code{file} is empty, the return value is the null -string. Thus calling code may use something like: +string. Thus, calling code may use something like: @example contents = readfile("/some/path") @@ -21440,7 +21440,7 @@ if (length(contents) == 0) This tests the result to see if it is empty or not. An equivalent test would be @samp{contents == ""}. -@xref{Extension Sample Readfile}, for an extension function that +@DBXREF{Extension Sample Readfile} for an extension function that also reads an entire file into memory. @node Shell Quoting @@ -21547,8 +21547,8 @@ The @code{BEGIN} and @code{END} rules are each executed exactly once, at the beginning and end of your @command{awk} program, respectively (@pxref{BEGIN/END}). We (the @command{gawk} authors) once had a user who mistakenly thought that the -@code{BEGIN} rule is executed at the beginning of each @value{DF} and the -@code{END} rule is executed at the end of each @value{DF}. +@code{BEGIN} rules were executed at the beginning of each @value{DF} and the +@code{END} rules were executed at the end of each @value{DF}. When informed that this was not the case, the user requested that we add new special @@ -21588,7 +21588,7 @@ END @{ endfile(FILENAME) @} This file must be loaded before the user's ``main'' program, so that the rule it supplies is executed first. -This rule relies on @command{awk}'s @code{FILENAME} variable that +This rule relies on @command{awk}'s @code{FILENAME} variable, which automatically changes for each new @value{DF}. The current @value{FN} is saved in a private variable, @code{_oldfilename}. If @code{FILENAME} does not equal @code{_oldfilename}, then a new @value{DF} is being processed and @@ -21604,7 +21604,7 @@ first @value{DF}. The program also supplies an @code{END} rule to do the final processing for the last file. Because this @code{END} rule comes before any @code{END} rules supplied in the ``main'' program, @code{endfile()} is called first. Once -again the value of multiple @code{BEGIN} and @code{END} rules should be clear. +again, the value of multiple @code{BEGIN} and @code{END} rules should be clear. @cindex @code{beginfile()} user-defined function @cindex @code{endfile()} user-defined function @@ -21652,7 +21652,7 @@ how it simplifies writing the main program. You are probably wondering, if @code{beginfile()} and @code{endfile()} functions can do the job, why does @command{gawk} have -@code{BEGINFILE} and @code{ENDFILE} patterns (@pxref{BEGINFILE/ENDFILE})? +@code{BEGINFILE} and @code{ENDFILE} patterns? Good question. Normally, if @command{awk} cannot open a file, this causes an immediate fatal error. In this case, there is no way for a @@ -21661,6 +21661,7 @@ calling it relies on the file being open and at the first record. Thus, the main reason for @code{BEGINFILE} is to give you a ``hook'' to catch files that cannot be processed. @code{ENDFILE} exists for symmetry, and because it provides an easy way to do per-file cleanup processing. +For more information, refer to @ref{BEGINFILE/ENDFILE}. @docbook </sidebar> @@ -21675,7 +21676,7 @@ and because it provides an easy way to do per-file cleanup processing. You are probably wondering, if @code{beginfile()} and @code{endfile()} functions can do the job, why does @command{gawk} have -@code{BEGINFILE} and @code{ENDFILE} patterns (@pxref{BEGINFILE/ENDFILE})? +@code{BEGINFILE} and @code{ENDFILE} patterns? Good question. Normally, if @command{awk} cannot open a file, this causes an immediate fatal error. In this case, there is no way for a @@ -21684,6 +21685,7 @@ calling it relies on the file being open and at the first record. Thus, the main reason for @code{BEGINFILE} is to give you a ``hook'' to catch files that cannot be processed. @code{ENDFILE} exists for symmetry, and because it provides an easy way to do per-file cleanup processing. +For more information, refer to @ref{BEGINFILE/ENDFILE}. @end cartouche @end ifnotdocbook @@ -21691,7 +21693,7 @@ and because it provides an easy way to do per-file cleanup processing. @subsection Rereading the Current File @cindex files, reading -Another request for a new built-in function was for a @code{rewind()} +Another request for a new built-in function was for a function that would make it possible to reread the current file. The requesting user didn't want to have to use @code{getline} (@pxref{Getline}) @@ -21700,7 +21702,7 @@ inside a loop. However, as long as you are not in the @code{END} rule, it is quite easy to arrange to immediately close the current input file and then start over with it from the top. -For lack of a better name, we'll call it @code{rewind()}: +For lack of a better name, we'll call the function @code{rewind()}: @cindex @code{rewind()} user-defined function @example @@ -21793,16 +21795,16 @@ See also @ref{ARGC and ARGV}. Because @command{awk} variable names only allow the English letters, the regular expression check purposely does not use character classes such as @samp{[:alpha:]} and @samp{[:alnum:]} -(@pxref{Bracket Expressions}) +(@pxref{Bracket Expressions}). @node Empty Files -@subsection Checking for Zero-length Files +@subsection Checking for Zero-Length Files All known @command{awk} implementations silently skip over zero-length files. This is a by-product of @command{awk}'s implicit read-a-record-and-match-against-the-rules loop: when @command{awk} tries to read a record from an empty file, it immediately receives an -end of file indication, closes the file, and proceeds on to the next +end-of-file indication, closes the file, and proceeds on to the next command-line @value{DF}, @emph{without} executing any user-level @command{awk} program code. @@ -21867,7 +21869,7 @@ Occasionally, you might not want @command{awk} to process command-line variable assignments (@pxref{Assignment Options}). In particular, if you have a @value{FN} that contains an @samp{=} character, -@command{awk} treats the @value{FN} as an assignment, and does not process it. +@command{awk} treats the @value{FN} as an assignment and does not process it. Some users have suggested an additional command-line option for @command{gawk} to disable command-line assignments. However, some simple programming with @@ -22229,8 +22231,8 @@ BEGIN @{ @c endfile @end example -The rest of the @code{BEGIN} rule is a simple test program. Here is the -result of two sample runs of the test program: +The rest of the @code{BEGIN} rule is a simple test program. Here are the +results of two sample runs of the test program: @example $ @kbd{awk -f getopt.awk -v _getopt_test=1 -- -a -cbARG bax -x} @@ -22288,7 +22290,7 @@ use @code{getopt()} to process their arguments. The @code{PROCINFO} array (@pxref{Built-in Variables}) provides access to the current user's real and effective user and group ID -numbers, and if available, the user's supplementary group set. +numbers, and, if available, the user's supplementary group set. However, because these are numbers, they do not provide very useful information to the average user. There needs to be some way to find the user information associated with the user and group ID numbers. This @@ -22308,7 +22310,7 @@ kept. Instead, it provides the @code{<pwd.h>} header file and several C language subroutines for obtaining user information. The primary function is @code{getpwent()}, for ``get password entry.'' The ``password'' comes from the original user database file, -@file{/etc/passwd}, which stores user information, along with the +@file{/etc/passwd}, which stores user information along with the encrypted passwords (hence the name). @cindex @command{pwcat} program @@ -22407,7 +22409,7 @@ The user's encrypted password. This may not be available on some systems. @item User-ID The user's numeric user ID number. -(On some systems, it's a C @code{long}, and not an @code{int}. Thus +(On some systems, it's a C @code{long}, and not an @code{int}. Thus, we cast it to @code{long} for all cases.) @item Group-ID @@ -22534,7 +22536,7 @@ The code that checks for using @code{FPAT}, using @code{using_fpat} and @code{PROCINFO["FS"]}, is similar. The main part of the function uses a loop to read database lines, split -the line into fields, and then store the line into each array as necessary. +the lines into fields, and then store the lines into each array as necessary. When the loop is done, @code{@w{_pw_init()}} cleans up by closing the pipeline, setting @code{@w{_pw_inited}} to one, and restoring @code{FS} (and @code{FIELDWIDTHS} or @code{FPAT} @@ -22751,7 +22753,7 @@ it is usually empty or set to @samp{*}. @item Group ID Number The group's numeric group ID number; the association of name to number must be unique within the file. -(On some systems it's a C @code{long}, and not an @code{int}. Thus +(On some systems it's a C @code{long}, and not an @code{int}. Thus, we cast it to @code{long} for all cases.) @item Group Member List @@ -22865,32 +22867,32 @@ The @code{@w{_gr_init()}} function first saves @code{FS}, @code{$0}, and then sets @code{FS} and @code{RS} to the correct values for scanning the group information. It also takes care to note whether @code{FIELDWIDTHS} or @code{FPAT} -is being used, and to restore the appropriate field splitting mechanism. +is being used, and to restore the appropriate field-splitting mechanism. -The group information is stored is several associative arrays. +The group information is stored in several associative arrays. The arrays are indexed by group name (@code{@w{_gr_byname}}), by group ID number (@code{@w{_gr_bygid}}), and by position in the database (@code{@w{_gr_bycount}}). There is an additional array indexed by username (@code{@w{_gr_groupsbyuser}}), which is a space-separated list of groups to which each user belongs. -Unlike the user database, it is possible to have multiple records in the +Unlike in the user database, it is possible to have multiple records in the database for the same group. This is common when a group has a large number of members. A pair of such entries might look like the following: @example -tvpeople:*:101:johny,jay,arsenio +tvpeople:*:101:johnny,jay,arsenio tvpeople:*:101:david,conan,tom,joan @end example For this reason, @code{_gr_init()} looks to see if a group name or -group ID number is already seen. If it is, the usernames are -simply concatenated onto the previous list of users.@footnote{There is actually a +group ID number is already seen. If so, the usernames are +simply concatenated onto the previous list of users.@footnote{There is a subtle problem with the code just presented. Suppose that the first time there were no names. This code adds the names with a leading comma. It also doesn't check that there is a @code{$4}.} Finally, @code{_gr_init()} closes the pipeline to @command{grcat}, restores -@code{FS} (and @code{FIELDWIDTHS} or @code{FPAT} if necessary), @code{RS}, and @code{$0}, +@code{FS} (and @code{FIELDWIDTHS} or @code{FPAT}, if necessary), @code{RS}, and @code{$0}, initializes @code{_gr_count} to zero (it is used later), and makes @code{_gr_inited} nonzero. @@ -22990,12 +22992,12 @@ uses these functions. @DBREF{Arrays of Arrays} described how @command{gawk} provides arrays of arrays. In particular, any element of -an array may be either a scalar, or another array. The +an array may be either a scalar or another array. The @code{isarray()} function (@pxref{Type Functions}) lets you distinguish an array from a scalar. The following function, @code{walk_array()}, recursively traverses -an array, printing each element's indices and value. +an array, printing the element indices and values. You call it with the array and a string representing the name of the array: @@ -23067,24 +23069,24 @@ The functions presented here fit into the following categories: @c nested list @table @asis @item General problems -Number-to-string conversion, assertions, rounding, random number +Number-to-string conversion, testing assertions, rounding, random number generation, converting characters to numbers, joining strings, getting easily usable time-of-day information, and reading a whole file in -one shot. +one shot @item Managing @value{DF}s Noting @value{DF} boundaries, rereading the current file, checking for readable files, checking for zero-length files, and treating assignments -as @value{FN}s. +as @value{FN}s @item Processing command-line options -An @command{awk} version of the standard C @code{getopt()} function. +An @command{awk} version of the standard C @code{getopt()} function @item Reading the user and group databases -Two sets of routines that parallel the C library versions. +Two sets of routines that parallel the C library versions @item Traversing arrays of arrays -A simple function to traverse an array of arrays to any depth. +A simple function to traverse an array of arrays to any depth @end table @c end nested list diff --git a/doc/gawktexi.in b/doc/gawktexi.in index e38feeab..6a890105 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -19654,7 +19654,7 @@ It contains the following chapters: your own @command{awk} functions. Writing functions is important, because it allows you to encapsulate algorithms and program tasks in a single place. It simplifies programming, making program development more -manageable, and making programs more readable. +manageable and making programs more readable. @cindex Kernighan, Brian @cindex Plauger, P.J.@: @@ -19783,7 +19783,7 @@ often use variable names like these for their own purposes. The example programs shown in this @value{CHAPTER} all start the names of their private variables with an underscore (@samp{_}). Users generally don't use leading underscores in their variable names, so this convention immediately -decreases the chances that the variable name will be accidentally shared +decreases the chances that the variable names will be accidentally shared with the user's program. @cindex @code{_} (underscore), in names of private variables @@ -19801,8 +19801,8 @@ show how our own @command{awk} programming style has evolved and to provide some basis for this discussion.} As a final note on variable naming, if a function makes global variables -available for use by a main program, it is a good convention to start that -variable's name with a capital letter---for +available for use by a main program, it is a good convention to start those +variables' names with a capital letter---for example, @code{getopt()}'s @code{Opterr} and @code{Optind} variables (@pxref{Getopt Function}). The leading capital letter indicates that it is global, while the fact that @@ -19813,7 +19813,7 @@ not one of @command{awk}'s predefined variables, such as @code{FS}. It is also important that @emph{all} variables in library functions that do not need to save state are, in fact, declared local.@footnote{@command{gawk}'s @option{--dump-variables} command-line -option is useful for verifying this.} If this is not done, the variable +option is useful for verifying this.} If this is not done, the variables could accidentally be used in the user's program, leading to bugs that are very difficult to track down: @@ -20011,7 +20011,7 @@ Following is the function: @example @c file eg/lib/assert.awk -# assert --- assert that a condition is true. Otherwise exit. +# assert --- assert that a condition is true. Otherwise, exit. @c endfile @ignore @@ -20047,7 +20047,7 @@ is false, it prints a message to standard error, using the @code{string} parameter to describe the failed condition. It then sets the variable @code{_assert_exit} to one and executes the @code{exit} statement. The @code{exit} statement jumps to the @code{END} rule. If the @code{END} -rules finds @code{_assert_exit} to be true, it exits immediately. +rule finds @code{_assert_exit} to be true, it exits immediately. The purpose of the test in the @code{END} rule is to keep any other @code{END} rules from running. When an assertion fails, the @@ -20339,7 +20339,7 @@ all the strings in an array into one long string. The following function, the application programs (@pxref{Sample Programs}). -Good function design is important; this function needs to be general but it +Good function design is important; this function needs to be general, but it should also have a reasonable default behavior. It is called with an array as well as the beginning and ending indices of the elements in the array to be merged. This assumes that the array indices are numeric---a reasonable @@ -20487,7 +20487,7 @@ allowed the user to supply an optional timestamp value to use instead of the current time. @node Readfile Function -@subsection Reading a Whole File At Once +@subsection Reading a Whole File at Once Often, it is convenient to have the entire contents of a file available in memory as a single string. A straightforward but naive way to @@ -20544,13 +20544,13 @@ function readfile(file, tmp, save_rs) It works by setting @code{RS} to @samp{^$}, a regular expression that will never match if the file has contents. @command{gawk} reads data from -the file into @code{tmp} attempting to match @code{RS}. The match fails +the file into @code{tmp}, attempting to match @code{RS}. The match fails after each read, but fails quickly, such that @command{gawk} fills @code{tmp} with the entire contents of the file. (@DBXREF{Records} for information on @code{RT} and @code{RS}.) In the case that @code{file} is empty, the return value is the null -string. Thus calling code may use something like: +string. Thus, calling code may use something like: @example contents = readfile("/some/path") @@ -20561,7 +20561,7 @@ if (length(contents) == 0) This tests the result to see if it is empty or not. An equivalent test would be @samp{contents == ""}. -@xref{Extension Sample Readfile}, for an extension function that +@DBXREF{Extension Sample Readfile} for an extension function that also reads an entire file into memory. @node Shell Quoting @@ -20668,8 +20668,8 @@ The @code{BEGIN} and @code{END} rules are each executed exactly once, at the beginning and end of your @command{awk} program, respectively (@pxref{BEGIN/END}). We (the @command{gawk} authors) once had a user who mistakenly thought that the -@code{BEGIN} rule is executed at the beginning of each @value{DF} and the -@code{END} rule is executed at the end of each @value{DF}. +@code{BEGIN} rules were executed at the beginning of each @value{DF} and the +@code{END} rules were executed at the end of each @value{DF}. When informed that this was not the case, the user requested that we add new special @@ -20709,7 +20709,7 @@ END @{ endfile(FILENAME) @} This file must be loaded before the user's ``main'' program, so that the rule it supplies is executed first. -This rule relies on @command{awk}'s @code{FILENAME} variable that +This rule relies on @command{awk}'s @code{FILENAME} variable, which automatically changes for each new @value{DF}. The current @value{FN} is saved in a private variable, @code{_oldfilename}. If @code{FILENAME} does not equal @code{_oldfilename}, then a new @value{DF} is being processed and @@ -20725,7 +20725,7 @@ first @value{DF}. The program also supplies an @code{END} rule to do the final processing for the last file. Because this @code{END} rule comes before any @code{END} rules supplied in the ``main'' program, @code{endfile()} is called first. Once -again the value of multiple @code{BEGIN} and @code{END} rules should be clear. +again, the value of multiple @code{BEGIN} and @code{END} rules should be clear. @cindex @code{beginfile()} user-defined function @cindex @code{endfile()} user-defined function @@ -20768,7 +20768,7 @@ how it simplifies writing the main program. You are probably wondering, if @code{beginfile()} and @code{endfile()} functions can do the job, why does @command{gawk} have -@code{BEGINFILE} and @code{ENDFILE} patterns (@pxref{BEGINFILE/ENDFILE})? +@code{BEGINFILE} and @code{ENDFILE} patterns? Good question. Normally, if @command{awk} cannot open a file, this causes an immediate fatal error. In this case, there is no way for a @@ -20777,13 +20777,14 @@ calling it relies on the file being open and at the first record. Thus, the main reason for @code{BEGINFILE} is to give you a ``hook'' to catch files that cannot be processed. @code{ENDFILE} exists for symmetry, and because it provides an easy way to do per-file cleanup processing. +For more information, refer to @ref{BEGINFILE/ENDFILE}. @end sidebar @node Rewind Function @subsection Rereading the Current File @cindex files, reading -Another request for a new built-in function was for a @code{rewind()} +Another request for a new built-in function was for a function that would make it possible to reread the current file. The requesting user didn't want to have to use @code{getline} (@pxref{Getline}) @@ -20792,7 +20793,7 @@ inside a loop. However, as long as you are not in the @code{END} rule, it is quite easy to arrange to immediately close the current input file and then start over with it from the top. -For lack of a better name, we'll call it @code{rewind()}: +For lack of a better name, we'll call the function @code{rewind()}: @cindex @code{rewind()} user-defined function @example @@ -20885,16 +20886,16 @@ See also @ref{ARGC and ARGV}. Because @command{awk} variable names only allow the English letters, the regular expression check purposely does not use character classes such as @samp{[:alpha:]} and @samp{[:alnum:]} -(@pxref{Bracket Expressions}) +(@pxref{Bracket Expressions}). @node Empty Files -@subsection Checking for Zero-length Files +@subsection Checking for Zero-Length Files All known @command{awk} implementations silently skip over zero-length files. This is a by-product of @command{awk}'s implicit read-a-record-and-match-against-the-rules loop: when @command{awk} tries to read a record from an empty file, it immediately receives an -end of file indication, closes the file, and proceeds on to the next +end-of-file indication, closes the file, and proceeds on to the next command-line @value{DF}, @emph{without} executing any user-level @command{awk} program code. @@ -20959,7 +20960,7 @@ Occasionally, you might not want @command{awk} to process command-line variable assignments (@pxref{Assignment Options}). In particular, if you have a @value{FN} that contains an @samp{=} character, -@command{awk} treats the @value{FN} as an assignment, and does not process it. +@command{awk} treats the @value{FN} as an assignment and does not process it. Some users have suggested an additional command-line option for @command{gawk} to disable command-line assignments. However, some simple programming with @@ -21321,8 +21322,8 @@ BEGIN @{ @c endfile @end example -The rest of the @code{BEGIN} rule is a simple test program. Here is the -result of two sample runs of the test program: +The rest of the @code{BEGIN} rule is a simple test program. Here are the +results of two sample runs of the test program: @example $ @kbd{awk -f getopt.awk -v _getopt_test=1 -- -a -cbARG bax -x} @@ -21380,7 +21381,7 @@ use @code{getopt()} to process their arguments. The @code{PROCINFO} array (@pxref{Built-in Variables}) provides access to the current user's real and effective user and group ID -numbers, and if available, the user's supplementary group set. +numbers, and, if available, the user's supplementary group set. However, because these are numbers, they do not provide very useful information to the average user. There needs to be some way to find the user information associated with the user and group ID numbers. This @@ -21400,7 +21401,7 @@ kept. Instead, it provides the @code{<pwd.h>} header file and several C language subroutines for obtaining user information. The primary function is @code{getpwent()}, for ``get password entry.'' The ``password'' comes from the original user database file, -@file{/etc/passwd}, which stores user information, along with the +@file{/etc/passwd}, which stores user information along with the encrypted passwords (hence the name). @cindex @command{pwcat} program @@ -21499,7 +21500,7 @@ The user's encrypted password. This may not be available on some systems. @item User-ID The user's numeric user ID number. -(On some systems, it's a C @code{long}, and not an @code{int}. Thus +(On some systems, it's a C @code{long}, and not an @code{int}. Thus, we cast it to @code{long} for all cases.) @item Group-ID @@ -21626,7 +21627,7 @@ The code that checks for using @code{FPAT}, using @code{using_fpat} and @code{PROCINFO["FS"]}, is similar. The main part of the function uses a loop to read database lines, split -the line into fields, and then store the line into each array as necessary. +the lines into fields, and then store the lines into each array as necessary. When the loop is done, @code{@w{_pw_init()}} cleans up by closing the pipeline, setting @code{@w{_pw_inited}} to one, and restoring @code{FS} (and @code{FIELDWIDTHS} or @code{FPAT} @@ -21843,7 +21844,7 @@ it is usually empty or set to @samp{*}. @item Group ID Number The group's numeric group ID number; the association of name to number must be unique within the file. -(On some systems it's a C @code{long}, and not an @code{int}. Thus +(On some systems it's a C @code{long}, and not an @code{int}. Thus, we cast it to @code{long} for all cases.) @item Group Member List @@ -21957,32 +21958,32 @@ The @code{@w{_gr_init()}} function first saves @code{FS}, @code{$0}, and then sets @code{FS} and @code{RS} to the correct values for scanning the group information. It also takes care to note whether @code{FIELDWIDTHS} or @code{FPAT} -is being used, and to restore the appropriate field splitting mechanism. +is being used, and to restore the appropriate field-splitting mechanism. -The group information is stored is several associative arrays. +The group information is stored in several associative arrays. The arrays are indexed by group name (@code{@w{_gr_byname}}), by group ID number (@code{@w{_gr_bygid}}), and by position in the database (@code{@w{_gr_bycount}}). There is an additional array indexed by username (@code{@w{_gr_groupsbyuser}}), which is a space-separated list of groups to which each user belongs. -Unlike the user database, it is possible to have multiple records in the +Unlike in the user database, it is possible to have multiple records in the database for the same group. This is common when a group has a large number of members. A pair of such entries might look like the following: @example -tvpeople:*:101:johny,jay,arsenio +tvpeople:*:101:johnny,jay,arsenio tvpeople:*:101:david,conan,tom,joan @end example For this reason, @code{_gr_init()} looks to see if a group name or -group ID number is already seen. If it is, the usernames are -simply concatenated onto the previous list of users.@footnote{There is actually a +group ID number is already seen. If so, the usernames are +simply concatenated onto the previous list of users.@footnote{There is a subtle problem with the code just presented. Suppose that the first time there were no names. This code adds the names with a leading comma. It also doesn't check that there is a @code{$4}.} Finally, @code{_gr_init()} closes the pipeline to @command{grcat}, restores -@code{FS} (and @code{FIELDWIDTHS} or @code{FPAT} if necessary), @code{RS}, and @code{$0}, +@code{FS} (and @code{FIELDWIDTHS} or @code{FPAT}, if necessary), @code{RS}, and @code{$0}, initializes @code{_gr_count} to zero (it is used later), and makes @code{_gr_inited} nonzero. @@ -22082,12 +22083,12 @@ uses these functions. @DBREF{Arrays of Arrays} described how @command{gawk} provides arrays of arrays. In particular, any element of -an array may be either a scalar, or another array. The +an array may be either a scalar or another array. The @code{isarray()} function (@pxref{Type Functions}) lets you distinguish an array from a scalar. The following function, @code{walk_array()}, recursively traverses -an array, printing each element's indices and value. +an array, printing the element indices and values. You call it with the array and a string representing the name of the array: @@ -22159,24 +22160,24 @@ The functions presented here fit into the following categories: @c nested list @table @asis @item General problems -Number-to-string conversion, assertions, rounding, random number +Number-to-string conversion, testing assertions, rounding, random number generation, converting characters to numbers, joining strings, getting easily usable time-of-day information, and reading a whole file in -one shot. +one shot @item Managing @value{DF}s Noting @value{DF} boundaries, rereading the current file, checking for readable files, checking for zero-length files, and treating assignments -as @value{FN}s. +as @value{FN}s @item Processing command-line options -An @command{awk} version of the standard C @code{getopt()} function. +An @command{awk} version of the standard C @code{getopt()} function @item Reading the user and group databases -Two sets of routines that parallel the C library versions. +Two sets of routines that parallel the C library versions @item Traversing arrays of arrays -A simple function to traverse an array of arrays to any depth. +A simple function to traverse an array of arrays to any depth @end table @c end nested list |