diff options
| -rw-r--r-- | awklib/eg/lib/processarray.awk | 12 | ||||
| -rw-r--r-- | awklib/eg/lib/shellquote.awk | 22 | ||||
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 1293 | ||||
| -rw-r--r-- | doc/gawk.texi | 188 | ||||
| -rw-r--r-- | doc/gawktexi.in | 185 |
6 files changed, 1081 insertions, 623 deletions
diff --git a/awklib/eg/lib/processarray.awk b/awklib/eg/lib/processarray.awk new file mode 100644 index 00000000..79a86d1f --- /dev/null +++ b/awklib/eg/lib/processarray.awk @@ -0,0 +1,12 @@ +function process_array(arr, name, process, do_arrays, i, new_name) +{ + for (i in arr) { + new_name = (name "[" i "]") + if (isarray(arr[i])) { + if (do_arrays) + @process(new_name, arr[i]) + process_array(arr[i], new_name, process, do_arrays) + } else + @process(new_name, arr[i]) + } +} diff --git a/awklib/eg/lib/shellquote.awk b/awklib/eg/lib/shellquote.awk new file mode 100644 index 00000000..cd943dc7 --- /dev/null +++ b/awklib/eg/lib/shellquote.awk @@ -0,0 +1,22 @@ +# shell_quote --- quote an argument for passing to the shell +# +# Michael Brennan +# brennan@madronabluff.com +# September 2014 + +function shell_quote(s, # parameter + SINGLE, QSINGLE, i, X, n, ret) # locals +{ + if (s == "") + return "\"\"" + + SINGLE = "\x27" # single quote + QSINGLE = "\"\x27\"" + n = split(s, X, SINGLE) + + ret = SINGLE X[1] SINGLE + for (i = 2; i <= n; i++) + ret = ret QSINGLE SINGLE X[i] SINGLE + + return ret +} diff --git a/doc/ChangeLog b/doc/ChangeLog index 3444a542..56e54b17 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2014-10-01 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More fixes after reading through the MS. + 2014-09-30 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: More fixes after reading through the MS. diff --git a/doc/gawk.info b/doc/gawk.info index 398fbb61..6c46bb79 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -416,6 +416,8 @@ entitled "GNU Free Documentation License". * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the + shell. * Data File Management:: Functions for managing command-line data files. * Filetrans Function:: A function for handling data file @@ -6799,6 +6801,9 @@ uppercase characters converted to lowercase (*note String Functions::). The program builds up a list of command lines, using the `mv' utility to rename the files. It then sends the list to the shell for execution. + *Note Shell Quoting::, for a function that can help in generating +command lines to be fed to the shell. + File: gawk.info, Node: Special FD, Next: Special Files, Prev: Redirection, Up: Printing @@ -14181,6 +14186,63 @@ names of the two comparison functions: -| sort: <87.1 93.4 95.6 100.0> -| rsort: <100.0 95.6 93.4 87.1> + Another example where indirect functions calls are useful can be +found in processing arrays. *note Walking Arrays::, presented a simple +function for "walking" an array of arrays. That function simply +printed the name and value of each scalar array element. However, it is +easy to generalize that function, by passing in the name of a function +to call when walking an array. The modified function looks like this: + + function process_array(arr, name, process, do_arrays, i, new_name) + { + for (i in arr) { + new_name = (name "[" i "]") + if (isarray(arr[i])) { + if (do_arrays) + @process(new_name, arr[i]) + process_array(arr[i], new_name, process, do_arrays) + } else + @process(new_name, arr[i]) + } + } + + The arguments are as follows: + +`arr' + The array. + +`name' + The name of the array (a string). + +`process' + The name of the function to call. + +`do_arrays' + If this is true, the function can handle elements that are + subarrays. + + If subarrays are to be processed, that is done before walking them +further. + + When run with the following scaffolding, the function produces the +same results as does the earlier `walk_array()' function: + + BEGIN { + a[1] = 1 + a[2][1] = 21 + a[2][2] = 22 + a[3] = 3 + a[4][1][1] = 411 + a[4][2] = 42 + + process_array(a, "a", "do_print", 0) + } + + function do_print(name, element) + { + printf "%s = %s\n", name, element + } + Remember that you must supply a leading `@' in front of an indirect function call. @@ -14454,6 +14516,7 @@ programming use. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the shell. File: gawk.info, Node: Strtonum Function, Next: Assert Function, Up: General Functions @@ -14929,7 +14992,7 @@ the `getlocaltime()' function would have allowed the user to supply an optional timestamp value to use instead of the current time. -File: gawk.info, Node: Readfile Function, Prev: Getlocaltime Function, Up: General Functions +File: gawk.info, Node: Readfile Function, Next: Shell Quoting, Prev: Getlocaltime Function, Up: General Functions 10.2.8 Reading A Whole File At Once ----------------------------------- @@ -14992,6 +15055,58 @@ test would be `contents == ""'. also reads an entire file into memory. +File: gawk.info, Node: Shell Quoting, Prev: Readfile Function, Up: General Functions + +10.2.9 Quoting Strings to Pass to The Shell +------------------------------------------- + +Michael Brennan offers the following programming pattern, which he uses +frequently: + + #! /bin/sh + + awkp=' + ... + ' + + INPUT_PROGRAM | awk "$awkp" | /bin/sh + + For example, a program of his named `flac-edit' has this form: + + $ flac-edit -song="Whoope! That's Great" file.flac + + It generates the following output, which is to be piped to the shell +(`/bin/sh'): + + chmod +w file.flac + metaflac --remove-tag=TITLE file.flac + LANG=en_US.88591 metaflac --set-tag=TITLE='Whoope! That'"'"'s Great' file.flac + chmod -w file.flac + + Note the need for shell quoting. The function `shell_quote()' does +it. `SINGLE' is the one-character string `"'"' and `QSINGLE' is the +three-character string `"\"'\""'. + + # shell_quote --- quote an argument for passing to the shell + + function shell_quote(s, # parameter + SINGLE, QSINGLE, i, X, n, ret) # locals + { + if (s == "") + return "\"\"" + + SINGLE = "\x27" # single quote + QSINGLE = "\"\x27\"" + n = split(s, X, SINGLE) + + ret = SINGLE X[1] SINGLE + for (i = 2; i <= n; i++) + ret = ret QSINGLE SINGLE X[i] SINGLE + + return ret + } + + File: gawk.info, Node: Data File Management, Next: Getopt Function, Prev: General Functions, Up: Library Functions 10.3 Data File Management @@ -16094,12 +16209,12 @@ value. Here is a main program to demonstrate: When run, the program produces the following output: $ gawk -f walk_array.awk - -| a[4][1][1] = 411 - -| a[4][2] = 42 -| a[1] = 1 -| a[2][1] = 21 -| a[2][2] = 22 -| a[3] = 3 + -| a[4][1][1] = 411 + -| a[4][2] = 42 File: gawk.info, Node: Library Functions Summary, Next: Library Exercises, Prev: Walking Arrays, Up: Library Functions @@ -17604,17 +17719,17 @@ there are more characters in the "from" list than in the "to" list, the last character of the "to" list is used for the remaining characters in the "from" list. - Once upon a time, a user proposed that a transliteration function -should be added to `gawk'. The following program was written to prove -that character transliteration could be done with a user-level -function. This program is not as complete as the system `tr' utility -but it does most of the job. + Once upon a time, a user proposed adding a transliteration function +to `gawk'. The following program was written to prove that character +transliteration could be done with a user-level function. This program +is not as complete as the system `tr' utility but it does most of the +job. - The `translate' program demonstrates one of the few weaknesses of -standard `awk': dealing with individual characters is very painful, -requiring repeated use of the `substr()', `index()', and `gsub()' -built-in functions (*note String Functions::).(2) There are two -functions. The first, `stranslate()', takes three arguments: + The `translate' program was written long before `gawk' acquired the +ability to split each character in a string into separate array +elements. Thus, it makes repeated use of the `substr()', `index()', +and `gsub()' built-in functions (*note String Functions::). There are +two functions. The first, `stranslate()', takes three arguments: `from' A list of characters from which to translate. @@ -17631,10 +17746,10 @@ simple loop goes through `from', one character at a time. For each character in `from', if the character appears in `target', it is replaced with the corresponding `to' character. - The `translate()' function simply calls `stranslate()' using `$0' as -the target. The main program sets two global variables, `FROM' and -`TO', from the command line, and then changes `ARGV' so that `awk' -reads from the standard input. + The `translate()' function calls `stranslate()' using `$0' as the +target. The main program sets two global variables, `FROM' and `TO', +from the command line, and then changes `ARGV' so that `awk' reads from +the standard input. Finally, the processing rule simply calls `translate()' for each record: @@ -17711,9 +17826,6 @@ program. enclosed in square brackets (`[a-z]') and quoted, to prevent the shell from attempting a file name expansion. This is not a feature. - (2) This program was also written before `gawk' acquired the ability -to split each character in a string into separate array elements. - File: gawk.info, Node: Labels Program, Next: Word Sorting, Prev: Translate Program, Up: Miscellaneous Programs @@ -27797,7 +27909,7 @@ than 32 bits. /name=(as_is,short) Compile time macros need to be defined before the first VMS-supplied -header file is included. +header file is included, as follows: #if (__CRTL_VER >= 70200000) && !defined (__VAX) #define _LARGEFILE 1 @@ -27811,6 +27923,12 @@ header file is included. #endif #endif + If you are writing your own extensions to run on VMS, you must +supply these definitions yourself. The `config.h' file created when +building `gawk' on VMS does this for you; if instead you use that file +or a similar one, then you must remember to include it before any +VMS-supplied header files. + File: gawk.info, Node: VMS Installation Details, Next: VMS Running, Prev: VMS Dynamic Extensions, Up: VMS Installation @@ -27979,11 +28097,11 @@ B.4 Reporting Problems and Bugs please report it to the developers; we cannot promise to do anything but we might well want to fix it. - Before reporting a bug, please make sure you have actually found a -real bug. Carefully reread the documentation and see if it really says -you can do what you're trying to do. If it's not clear whether you -should be able to do something or not, report that too; it's a bug in -the documentation! + Before reporting a bug, please make sure you have really found a +genuine bug. Carefully reread the documentation and see if it says you +can do what you're trying to do. If it's not clear whether you should +be able to do something or not, report that too; it's a bug in the +documentation! Before reporting a bug or trying to fix it yourself, try to isolate it to the smallest possible `awk' program and input data file that @@ -27996,7 +28114,8 @@ really in the documentation. Please include the version number of `gawk' you are using. You can get this information with the command `gawk --version'. - Once you have a precise problem, send email to <bug-gawk@gnu.org>. + Once you have a precise problem description, send email to +<bug-gawk@gnu.org>. The `gawk' maintainers subscribe to this address and thus they will receive your bug report. Although you can send mail to the maintainers @@ -31687,7 +31806,7 @@ Index * Brown, Martin: Contributors. (line 82) * BSD-based operating systems: Glossary. (line 611) * bt debugger command (alias for backtrace): Execution Stack. (line 13) -* Buening, Andreas <1>: Bugs. (line 71) +* Buening, Andreas <1>: Bugs. (line 72) * Buening, Andreas <2>: Contributors. (line 92) * Buening, Andreas: Acknowledgments. (line 60) * buffering, input/output <1>: Two-way I/O. (line 52) @@ -31802,7 +31921,7 @@ Index * common extensions, RS as a regexp: gawk split records. (line 6) * common extensions, single character fields: Single Character Fields. (line 6) -* comp.lang.awk newsgroup: Bugs. (line 38) +* comp.lang.awk newsgroup: Bugs. (line 39) * comparison expressions: Typing and Comparison. (line 9) * comparison expressions, as patterns: Expression Patterns. (line 14) @@ -32059,7 +32178,7 @@ Index * decimal point character, locale specific: Options. (line 272) * decrement operators: Increment Ops. (line 35) * default keyword: Switch Statement. (line 6) -* Deifik, Scott <1>: Bugs. (line 71) +* Deifik, Scott <1>: Bugs. (line 72) * Deifik, Scott <2>: Contributors. (line 53) * Deifik, Scott: Acknowledgments. (line 60) * delete ARRAY: Delete. (line 39) @@ -32990,7 +33109,7 @@ Index * mail-list file: Sample Data Files. (line 6) * mailing labels, printing: Labels Program. (line 6) * mailing list, GNITS: Acknowledgments. (line 52) -* Malmberg, John <1>: Bugs. (line 71) +* Malmberg, John <1>: Bugs. (line 72) * Malmberg, John: Acknowledgments. (line 60) * Malmberg, John E.: Contributors. (line 137) * mark parity: Ordinal Functions. (line 45) @@ -33229,7 +33348,7 @@ Index (line 6) * pipe, input: Getline/Pipe. (line 9) * pipe, output: Redirection. (line 57) -* Pitts, Dave <1>: Bugs. (line 71) +* Pitts, Dave <1>: Bugs. (line 72) * Pitts, Dave: Acknowledgments. (line 60) * Plauger, P.J.: Library Functions. (line 12) * plug-in: Extension Intro. (line 6) @@ -33435,7 +33554,7 @@ Index * range expressions (regexps): Bracket Expressions. (line 6) * range patterns: Ranges. (line 6) * range patterns, line continuation and: Ranges. (line 65) -* Rankin, Pat <1>: Bugs. (line 71) +* Rankin, Pat <1>: Bugs. (line 72) * Rankin, Pat <2>: Contributors. (line 37) * Rankin, Pat <3>: Assignment Ops. (line 100) * Rankin, Pat: Acknowledgments. (line 60) @@ -33544,7 +33663,7 @@ Index * RLENGTH variable: Auto-set. (line 251) * RLENGTH variable, match() function and: String Functions. (line 227) * Robbins, Arnold <1>: Future Extensions. (line 6) -* Robbins, Arnold <2>: Bugs. (line 71) +* Robbins, Arnold <2>: Bugs. (line 72) * Robbins, Arnold <3>: Contributors. (line 144) * Robbins, Arnold <4>: General Data Types. (line 6) * Robbins, Arnold <5>: Alarm Program. (line 6) @@ -34075,7 +34194,7 @@ Index * xor: Bitwise Functions. (line 56) * XOR bitwise operation: Bitwise Functions. (line 6) * Yawitz, Efraim: Contributors. (line 131) -* Zaretskii, Eli <1>: Bugs. (line 71) +* Zaretskii, Eli <1>: Bugs. (line 72) * Zaretskii, Eli <2>: Contributors. (line 55) * Zaretskii, Eli: Acknowledgments. (line 60) * zerofile.awk program: Empty Files. (line 21) @@ -34108,557 +34227,557 @@ Index Tag Table: Node: Top1204 -Node: Foreword41980 -Node: Preface46327 -Ref: Preface-Footnote-149222 -Ref: Preface-Footnote-249329 -Ref: Preface-Footnote-349562 -Node: History49704 -Node: Names52078 -Ref: Names-Footnote-153172 -Node: This Manual53318 -Ref: This Manual-Footnote-159155 -Node: Conventions59255 -Node: Manual History61600 -Ref: Manual History-Footnote-164676 -Ref: Manual History-Footnote-264717 -Node: How To Contribute64791 -Node: Acknowledgments66030 -Node: Getting Started70778 -Node: Running gawk73212 -Node: One-shot74402 -Node: Read Terminal75627 -Node: Long77654 -Node: Executable Scripts79170 -Ref: Executable Scripts-Footnote-181959 -Node: Comments82061 -Node: Quoting84534 -Node: DOS Quoting90044 -Node: Sample Data Files90719 -Node: Very Simple93312 -Node: Two Rules98203 -Node: More Complex100089 -Node: Statements/Lines102951 -Ref: Statements/Lines-Footnote-1107407 -Node: Other Features107672 -Node: When108603 -Ref: When-Footnote-1110359 -Node: Intro Summary110424 -Node: Invoking Gawk111307 -Node: Command Line112822 -Node: Options113613 -Ref: Options-Footnote-1129508 -Node: Other Arguments129533 -Node: Naming Standard Input132494 -Node: Environment Variables133587 -Node: AWKPATH Variable134145 -Ref: AWKPATH Variable-Footnote-1136997 -Ref: AWKPATH Variable-Footnote-2137042 -Node: AWKLIBPATH Variable137302 -Node: Other Environment Variables138061 -Node: Exit Status141763 -Node: Include Files142438 -Node: Loading Shared Libraries146016 -Node: Obsolete147443 -Node: Undocumented148140 -Node: Invoking Summary148407 -Node: Regexp150073 -Node: Regexp Usage151532 -Node: Escape Sequences153565 -Node: Regexp Operators159582 -Ref: Regexp Operators-Footnote-1167017 -Ref: Regexp Operators-Footnote-2167164 -Node: Bracket Expressions167262 -Ref: table-char-classes169279 -Node: Leftmost Longest172219 -Node: Computed Regexps173521 -Node: GNU Regexp Operators176918 -Node: Case-sensitivity180624 -Ref: Case-sensitivity-Footnote-1183514 -Ref: Case-sensitivity-Footnote-2183749 -Node: Regexp Summary183857 -Node: Reading Files185326 -Node: Records187420 -Node: awk split records188152 -Node: gawk split records193066 -Ref: gawk split records-Footnote-1197605 -Node: Fields197642 -Ref: Fields-Footnote-1200440 -Node: Nonconstant Fields200526 -Ref: Nonconstant Fields-Footnote-1202756 -Node: Changing Fields202958 -Node: Field Separators208890 -Node: Default Field Splitting211594 -Node: Regexp Field Splitting212711 -Node: Single Character Fields216061 -Node: Command Line Field Separator217120 -Node: Full Line Fields220332 -Ref: Full Line Fields-Footnote-1220840 -Node: Field Splitting Summary220886 -Ref: Field Splitting Summary-Footnote-1224017 -Node: Constant Size224118 -Node: Splitting By Content228724 -Ref: Splitting By Content-Footnote-1232797 -Node: Multiple Line232837 -Ref: Multiple Line-Footnote-1238726 -Node: Getline238905 -Node: Plain Getline241116 -Node: Getline/Variable243756 -Node: Getline/File244903 -Node: Getline/Variable/File246287 -Ref: Getline/Variable/File-Footnote-1247888 -Node: Getline/Pipe247975 -Node: Getline/Variable/Pipe250658 -Node: Getline/Coprocess251789 -Node: Getline/Variable/Coprocess253041 -Node: Getline Notes253780 -Node: Getline Summary256572 -Ref: table-getline-variants256984 -Node: Read Timeout257813 -Ref: Read Timeout-Footnote-1261627 -Node: Command-line directories261685 -Node: Input Summary262589 -Node: Input Exercises265841 -Node: Printing266569 -Node: Print268346 -Node: Print Examples269803 -Node: Output Separators272582 -Node: OFMT274600 -Node: Printf275954 -Node: Basic Printf276739 -Node: Control Letters278310 -Node: Format Modifiers282294 -Node: Printf Examples288301 -Node: Redirection290783 -Node: Special FD297514 -Ref: Special FD-Footnote-1300671 -Node: Special Files300745 -Node: Other Inherited Files301361 -Node: Special Network302361 -Node: Special Caveats303222 -Node: Close Files And Pipes304173 -Ref: Close Files And Pipes-Footnote-1311352 -Ref: Close Files And Pipes-Footnote-2311500 -Node: Output Summary311650 -Node: Output Exercises312646 -Node: Expressions313326 -Node: Values314511 -Node: Constants315187 -Node: Scalar Constants315867 -Ref: Scalar Constants-Footnote-1316726 -Node: Nondecimal-numbers316976 -Node: Regexp Constants319976 -Node: Using Constant Regexps320501 -Node: Variables323639 -Node: Using Variables324294 -Node: Assignment Options326204 -Node: Conversion328079 -Node: Strings And Numbers328603 -Ref: Strings And Numbers-Footnote-1331667 -Node: Locale influences conversions331776 -Ref: table-locale-affects334491 -Node: All Operators335079 -Node: Arithmetic Ops335709 -Node: Concatenation338214 -Ref: Concatenation-Footnote-1341033 -Node: Assignment Ops341139 -Ref: table-assign-ops346122 -Node: Increment Ops347400 -Node: Truth Values and Conditions350838 -Node: Truth Values351921 -Node: Typing and Comparison352970 -Node: Variable Typing353763 -Node: Comparison Operators357415 -Ref: table-relational-ops357825 -Node: POSIX String Comparison361340 -Ref: POSIX String Comparison-Footnote-1362412 -Node: Boolean Ops362550 -Ref: Boolean Ops-Footnote-1367029 -Node: Conditional Exp367120 -Node: Function Calls368847 -Node: Precedence372727 -Node: Locales376395 -Node: Expressions Summary378026 -Node: Patterns and Actions380600 -Node: Pattern Overview381720 -Node: Regexp Patterns383399 -Node: Expression Patterns383942 -Node: Ranges387722 -Node: BEGIN/END390828 -Node: Using BEGIN/END391590 -Ref: Using BEGIN/END-Footnote-1394327 -Node: I/O And BEGIN/END394433 -Node: BEGINFILE/ENDFILE396747 -Node: Empty399648 -Node: Using Shell Variables399965 -Node: Action Overview402241 -Node: Statements404568 -Node: If Statement406416 -Node: While Statement407914 -Node: Do Statement409942 -Node: For Statement411084 -Node: Switch Statement414239 -Node: Break Statement416627 -Node: Continue Statement418668 -Node: Next Statement420493 -Node: Nextfile Statement422873 -Node: Exit Statement425503 -Node: Built-in Variables427906 -Node: User-modified429039 -Ref: User-modified-Footnote-1436719 -Node: Auto-set436781 -Ref: Auto-set-Footnote-1449638 -Ref: Auto-set-Footnote-2449843 -Node: ARGC and ARGV449899 -Node: Pattern Action Summary454103 -Node: Arrays456530 -Node: Array Basics457859 -Node: Array Intro458703 -Ref: figure-array-elements460676 -Ref: Array Intro-Footnote-1463200 -Node: Reference to Elements463328 -Node: Assigning Elements465778 -Node: Array Example466269 -Node: Scanning an Array468027 -Node: Controlling Scanning471043 -Ref: Controlling Scanning-Footnote-1476232 -Node: Numeric Array Subscripts476548 -Node: Uninitialized Subscripts478733 -Node: Delete480350 -Ref: Delete-Footnote-1483094 -Node: Multidimensional483151 -Node: Multiscanning486246 -Node: Arrays of Arrays487835 -Node: Arrays Summary492596 -Node: Functions494701 -Node: Built-in495574 -Node: Calling Built-in496652 -Node: Numeric Functions498640 -Ref: Numeric Functions-Footnote-1502662 -Ref: Numeric Functions-Footnote-2503019 -Ref: Numeric Functions-Footnote-3503067 -Node: String Functions503336 -Ref: String Functions-Footnote-1526800 -Ref: String Functions-Footnote-2526929 -Ref: String Functions-Footnote-3527177 -Node: Gory Details527264 -Ref: table-sub-escapes529045 -Ref: table-sub-proposed530565 -Ref: table-posix-sub531929 -Ref: table-gensub-escapes533469 -Ref: Gory Details-Footnote-1534301 -Node: I/O Functions534452 -Ref: I/O Functions-Footnote-1541553 -Node: Time Functions541700 -Ref: Time Functions-Footnote-1552169 -Ref: Time Functions-Footnote-2552237 -Ref: Time Functions-Footnote-3552395 -Ref: Time Functions-Footnote-4552506 -Ref: Time Functions-Footnote-5552618 -Ref: Time Functions-Footnote-6552845 -Node: Bitwise Functions553111 -Ref: table-bitwise-ops553673 -Ref: Bitwise Functions-Footnote-1557981 -Node: Type Functions558150 -Node: I18N Functions559299 -Node: User-defined560944 -Node: Definition Syntax561748 -Ref: Definition Syntax-Footnote-1567154 -Node: Function Example567223 -Ref: Function Example-Footnote-1570140 -Node: Function Caveats570162 -Node: Calling A Function570680 -Node: Variable Scope571635 -Node: Pass By Value/Reference574623 -Node: Return Statement578133 -Node: Dynamic Typing581117 -Node: Indirect Calls582046 -Ref: Indirect Calls-Footnote-1591767 -Node: Functions Summary591895 -Node: Library Functions594594 -Ref: Library Functions-Footnote-1598212 -Ref: Library Functions-Footnote-2598355 -Node: Library Names598526 -Ref: Library Names-Footnote-1601986 -Ref: Library Names-Footnote-2602206 -Node: General Functions602292 -Node: Strtonum Function603320 -Node: Assert Function606340 -Node: Round Function609664 -Node: Cliff Random Function611205 -Node: Ordinal Functions612221 -Ref: Ordinal Functions-Footnote-1615286 -Ref: Ordinal Functions-Footnote-2615538 -Node: Join Function615749 -Ref: Join Function-Footnote-1617520 -Node: Getlocaltime Function617720 -Node: Readfile Function621461 -Node: Data File Management623409 -Node: Filetrans Function624041 -Node: Rewind Function628100 -Node: File Checking629485 -Ref: File Checking-Footnote-1630813 -Node: Empty Files631014 -Node: Ignoring Assigns632993 -Node: Getopt Function634544 -Ref: Getopt Function-Footnote-1646004 -Node: Passwd Functions646207 -Ref: Passwd Functions-Footnote-1655058 -Node: Group Functions655146 -Ref: Group Functions-Footnote-1663049 -Node: Walking Arrays663262 -Node: Library Functions Summary664865 -Node: Library Exercises666266 -Node: Sample Programs667546 -Node: Running Examples668316 -Node: Clones669044 -Node: Cut Program670268 -Node: Egrep Program679998 -Ref: Egrep Program-Footnote-1687502 -Node: Id Program687612 -Node: Split Program691256 -Ref: Split Program-Footnote-1694702 -Node: Tee Program694830 -Node: Uniq Program697617 -Node: Wc Program705038 -Ref: Wc Program-Footnote-1709286 -Node: Miscellaneous Programs709378 -Node: Dupword Program710591 -Node: Alarm Program712622 -Node: Translate Program717426 -Ref: Translate Program-Footnote-1721999 -Ref: Translate Program-Footnote-2722269 -Node: Labels Program722408 -Ref: Labels Program-Footnote-1725757 -Node: Word Sorting725841 -Node: History Sorting729911 -Node: Extract Program731747 -Node: Simple Sed739279 -Node: Igawk Program742341 -Ref: Igawk Program-Footnote-1756667 -Ref: Igawk Program-Footnote-2756868 -Ref: Igawk Program-Footnote-3756990 -Node: Anagram Program757105 -Node: Signature Program760167 -Node: Programs Summary761414 -Node: Programs Exercises762607 -Ref: Programs Exercises-Footnote-1766738 -Node: Advanced Features766829 -Node: Nondecimal Data768777 -Node: Array Sorting770367 -Node: Controlling Array Traversal771064 -Ref: Controlling Array Traversal-Footnote-1779395 -Node: Array Sorting Functions779513 -Ref: Array Sorting Functions-Footnote-1783405 -Node: Two-way I/O783599 -Ref: Two-way I/O-Footnote-1788543 -Ref: Two-way I/O-Footnote-2788729 -Node: TCP/IP Networking788811 -Node: Profiling791688 -Node: Advanced Features Summary799232 -Node: Internationalization801165 -Node: I18N and L10N802645 -Node: Explaining gettext803331 -Ref: Explaining gettext-Footnote-1808360 -Ref: Explaining gettext-Footnote-2808544 -Node: Programmer i18n808709 -Ref: Programmer i18n-Footnote-1813575 -Node: Translator i18n813624 -Node: String Extraction814418 -Ref: String Extraction-Footnote-1815549 -Node: Printf Ordering815635 -Ref: Printf Ordering-Footnote-1818421 -Node: I18N Portability818485 -Ref: I18N Portability-Footnote-1820934 -Node: I18N Example820997 -Ref: I18N Example-Footnote-1823797 -Node: Gawk I18N823869 -Node: I18N Summary824507 -Node: Debugger825846 -Node: Debugging826868 -Node: Debugging Concepts827309 -Node: Debugging Terms829166 -Node: Awk Debugging831741 -Node: Sample Debugging Session832633 -Node: Debugger Invocation833153 -Node: Finding The Bug834537 -Node: List of Debugger Commands841012 -Node: Breakpoint Control842344 -Node: Debugger Execution Control846036 -Node: Viewing And Changing Data849400 -Node: Execution Stack852765 -Node: Debugger Info854403 -Node: Miscellaneous Debugger Commands858420 -Node: Readline Support863612 -Node: Limitations864504 -Node: Debugging Summary866601 -Node: Arbitrary Precision Arithmetic867769 -Node: Computer Arithmetic869185 -Ref: table-numeric-ranges872786 -Ref: Computer Arithmetic-Footnote-1873645 -Node: Math Definitions873702 -Ref: table-ieee-formats876989 -Ref: Math Definitions-Footnote-1877593 -Node: MPFR features877698 -Node: FP Math Caution879367 -Ref: FP Math Caution-Footnote-1880417 -Node: Inexactness of computations880786 -Node: Inexact representation881734 -Node: Comparing FP Values883089 -Node: Errors accumulate884162 -Node: Getting Accuracy885595 -Node: Try To Round888254 -Node: Setting precision889153 -Ref: table-predefined-precision-strings889837 -Node: Setting the rounding mode891631 -Ref: table-gawk-rounding-modes891995 -Ref: Setting the rounding mode-Footnote-1895449 -Node: Arbitrary Precision Integers895628 -Ref: Arbitrary Precision Integers-Footnote-1898619 -Node: POSIX Floating Point Problems898768 -Ref: POSIX Floating Point Problems-Footnote-1902644 -Node: Floating point summary902682 -Node: Dynamic Extensions904874 -Node: Extension Intro906426 -Node: Plugin License907692 -Node: Extension Mechanism Outline908489 -Ref: figure-load-extension908917 -Ref: figure-register-new-function910397 -Ref: figure-call-new-function911401 -Node: Extension API Description913387 -Node: Extension API Functions Introduction914837 -Node: General Data Types919673 -Ref: General Data Types-Footnote-1925360 -Node: Memory Allocation Functions925659 -Ref: Memory Allocation Functions-Footnote-1928489 -Node: Constructor Functions928585 -Node: Registration Functions930319 -Node: Extension Functions931004 -Node: Exit Callback Functions933300 -Node: Extension Version String934548 -Node: Input Parsers935198 -Node: Output Wrappers945013 -Node: Two-way processors949529 -Node: Printing Messages951733 -Ref: Printing Messages-Footnote-1952810 -Node: Updating `ERRNO'952962 -Node: Requesting Values953702 -Ref: table-value-types-returned954430 -Node: Accessing Parameters955388 -Node: Symbol Table Access956619 -Node: Symbol table by name957133 -Node: Symbol table by cookie959113 -Ref: Symbol table by cookie-Footnote-1963252 -Node: Cached values963315 -Ref: Cached values-Footnote-1966819 -Node: Array Manipulation966910 -Ref: Array Manipulation-Footnote-1968008 -Node: Array Data Types968047 -Ref: Array Data Types-Footnote-1970704 -Node: Array Functions970796 -Node: Flattening Arrays974650 -Node: Creating Arrays981537 -Node: Extension API Variables986304 -Node: Extension Versioning986940 -Node: Extension API Informational Variables988841 -Node: Extension API Boilerplate989929 -Node: Finding Extensions993745 -Node: Extension Example994305 -Node: Internal File Description995077 -Node: Internal File Ops999144 -Ref: Internal File Ops-Footnote-11010802 -Node: Using Internal File Ops1010942 -Ref: Using Internal File Ops-Footnote-11013325 -Node: Extension Samples1013598 -Node: Extension Sample File Functions1015122 -Node: Extension Sample Fnmatch1022724 -Node: Extension Sample Fork1024206 -Node: Extension Sample Inplace1025419 -Node: Extension Sample Ord1027094 -Node: Extension Sample Readdir1027930 -Ref: table-readdir-file-types1028786 -Node: Extension Sample Revout1029597 -Node: Extension Sample Rev2way1030188 -Node: Extension Sample Read write array1030929 -Node: Extension Sample Readfile1032868 -Node: Extension Sample Time1033963 -Node: Extension Sample API Tests1035312 -Node: gawkextlib1035803 -Node: Extension summary1038453 -Node: Extension Exercises1042135 -Node: Language History1042857 -Node: V7/SVR3.11044514 -Node: SVR41046695 -Node: POSIX1048140 -Node: BTL1049529 -Node: POSIX/GNU1050263 -Node: Feature History1055832 -Node: Common Extensions1068923 -Node: Ranges and Locales1070247 -Ref: Ranges and Locales-Footnote-11074886 -Ref: Ranges and Locales-Footnote-21074913 -Ref: Ranges and Locales-Footnote-31075147 -Node: Contributors1075368 -Node: History summary1080908 -Node: Installation1082277 -Node: Gawk Distribution1083233 -Node: Getting1083717 -Node: Extracting1084541 -Node: Distribution contents1086183 -Node: Unix Installation1091900 -Node: Quick Installation1092517 -Node: Additional Configuration Options1094948 -Node: Configuration Philosophy1096688 -Node: Non-Unix Installation1099039 -Node: PC Installation1099497 -Node: PC Binary Installation1100823 -Node: PC Compiling1102671 -Ref: PC Compiling-Footnote-11105692 -Node: PC Testing1105797 -Node: PC Using1106973 -Node: Cygwin1111088 -Node: MSYS1111911 -Node: VMS Installation1112409 -Node: VMS Compilation1113201 -Ref: VMS Compilation-Footnote-11114423 -Node: VMS Dynamic Extensions1114481 -Node: VMS Installation Details1115854 -Node: VMS Running1118106 -Node: VMS GNV1120947 -Node: VMS Old Gawk1121676 -Node: Bugs1122146 -Node: Other Versions1126110 -Node: Installation summary1132323 -Node: Notes1133379 -Node: Compatibility Mode1134244 -Node: Additions1135026 -Node: Accessing The Source1135951 -Node: Adding Code1137387 -Node: New Ports1143559 -Node: Derived Files1148040 -Ref: Derived Files-Footnote-11153515 -Ref: Derived Files-Footnote-21153549 -Ref: Derived Files-Footnote-31154145 -Node: Future Extensions1154259 -Node: Implementation Limitations1154865 -Node: Extension Design1156113 -Node: Old Extension Problems1157267 -Ref: Old Extension Problems-Footnote-11158784 -Node: Extension New Mechanism Goals1158841 -Ref: Extension New Mechanism Goals-Footnote-11162201 -Node: Extension Other Design Decisions1162390 -Node: Extension Future Growth1164498 -Node: Old Extension Mechanism1165334 -Node: Notes summary1167096 -Node: Basic Concepts1168282 -Node: Basic High Level1168963 -Ref: figure-general-flow1169235 -Ref: figure-process-flow1169834 -Ref: Basic High Level-Footnote-11173063 -Node: Basic Data Typing1173248 -Node: Glossary1176576 -Node: Copying1201734 -Node: GNU Free Documentation License1239290 -Node: Index1264426 +Node: Foreword42103 +Node: Preface46450 +Ref: Preface-Footnote-149345 +Ref: Preface-Footnote-249452 +Ref: Preface-Footnote-349685 +Node: History49827 +Node: Names52201 +Ref: Names-Footnote-153295 +Node: This Manual53441 +Ref: This Manual-Footnote-159278 +Node: Conventions59378 +Node: Manual History61723 +Ref: Manual History-Footnote-164799 +Ref: Manual History-Footnote-264840 +Node: How To Contribute64914 +Node: Acknowledgments66153 +Node: Getting Started70901 +Node: Running gawk73335 +Node: One-shot74525 +Node: Read Terminal75750 +Node: Long77777 +Node: Executable Scripts79293 +Ref: Executable Scripts-Footnote-182082 +Node: Comments82184 +Node: Quoting84657 +Node: DOS Quoting90167 +Node: Sample Data Files90842 +Node: Very Simple93435 +Node: Two Rules98326 +Node: More Complex100212 +Node: Statements/Lines103074 +Ref: Statements/Lines-Footnote-1107530 +Node: Other Features107795 +Node: When108726 +Ref: When-Footnote-1110482 +Node: Intro Summary110547 +Node: Invoking Gawk111430 +Node: Command Line112945 +Node: Options113736 +Ref: Options-Footnote-1129631 +Node: Other Arguments129656 +Node: Naming Standard Input132617 +Node: Environment Variables133710 +Node: AWKPATH Variable134268 +Ref: AWKPATH Variable-Footnote-1137120 +Ref: AWKPATH Variable-Footnote-2137165 +Node: AWKLIBPATH Variable137425 +Node: Other Environment Variables138184 +Node: Exit Status141886 +Node: Include Files142561 +Node: Loading Shared Libraries146139 +Node: Obsolete147566 +Node: Undocumented148263 +Node: Invoking Summary148530 +Node: Regexp150196 +Node: Regexp Usage151655 +Node: Escape Sequences153688 +Node: Regexp Operators159705 +Ref: Regexp Operators-Footnote-1167140 +Ref: Regexp Operators-Footnote-2167287 +Node: Bracket Expressions167385 +Ref: table-char-classes169402 +Node: Leftmost Longest172342 +Node: Computed Regexps173644 +Node: GNU Regexp Operators177041 +Node: Case-sensitivity180747 +Ref: Case-sensitivity-Footnote-1183637 +Ref: Case-sensitivity-Footnote-2183872 +Node: Regexp Summary183980 +Node: Reading Files185449 +Node: Records187543 +Node: awk split records188275 +Node: gawk split records193189 +Ref: gawk split records-Footnote-1197728 +Node: Fields197765 +Ref: Fields-Footnote-1200563 +Node: Nonconstant Fields200649 +Ref: Nonconstant Fields-Footnote-1202879 +Node: Changing Fields203081 +Node: Field Separators209013 +Node: Default Field Splitting211717 +Node: Regexp Field Splitting212834 +Node: Single Character Fields216184 +Node: Command Line Field Separator217243 +Node: Full Line Fields220455 +Ref: Full Line Fields-Footnote-1220963 +Node: Field Splitting Summary221009 +Ref: Field Splitting Summary-Footnote-1224140 +Node: Constant Size224241 +Node: Splitting By Content228847 +Ref: Splitting By Content-Footnote-1232920 +Node: Multiple Line232960 +Ref: Multiple Line-Footnote-1238849 +Node: Getline239028 +Node: Plain Getline241239 +Node: Getline/Variable243879 +Node: Getline/File245026 +Node: Getline/Variable/File246410 +Ref: Getline/Variable/File-Footnote-1248011 +Node: Getline/Pipe248098 +Node: Getline/Variable/Pipe250781 +Node: Getline/Coprocess251912 +Node: Getline/Variable/Coprocess253164 +Node: Getline Notes253903 +Node: Getline Summary256695 +Ref: table-getline-variants257107 +Node: Read Timeout257936 +Ref: Read Timeout-Footnote-1261750 +Node: Command-line directories261808 +Node: Input Summary262712 +Node: Input Exercises265964 +Node: Printing266692 +Node: Print268469 +Node: Print Examples269926 +Node: Output Separators272705 +Node: OFMT274723 +Node: Printf276077 +Node: Basic Printf276862 +Node: Control Letters278433 +Node: Format Modifiers282417 +Node: Printf Examples288424 +Node: Redirection290906 +Node: Special FD297745 +Ref: Special FD-Footnote-1300902 +Node: Special Files300976 +Node: Other Inherited Files301592 +Node: Special Network302592 +Node: Special Caveats303453 +Node: Close Files And Pipes304404 +Ref: Close Files And Pipes-Footnote-1311583 +Ref: Close Files And Pipes-Footnote-2311731 +Node: Output Summary311881 +Node: Output Exercises312877 +Node: Expressions313557 +Node: Values314742 +Node: Constants315418 +Node: Scalar Constants316098 +Ref: Scalar Constants-Footnote-1316957 +Node: Nondecimal-numbers317207 +Node: Regexp Constants320207 +Node: Using Constant Regexps320732 +Node: Variables323870 +Node: Using Variables324525 +Node: Assignment Options326435 +Node: Conversion328310 +Node: Strings And Numbers328834 +Ref: Strings And Numbers-Footnote-1331898 +Node: Locale influences conversions332007 +Ref: table-locale-affects334722 +Node: All Operators335310 +Node: Arithmetic Ops335940 +Node: Concatenation338445 +Ref: Concatenation-Footnote-1341264 +Node: Assignment Ops341370 +Ref: table-assign-ops346353 +Node: Increment Ops347631 +Node: Truth Values and Conditions351069 +Node: Truth Values352152 +Node: Typing and Comparison353201 +Node: Variable Typing353994 +Node: Comparison Operators357646 +Ref: table-relational-ops358056 +Node: POSIX String Comparison361571 +Ref: POSIX String Comparison-Footnote-1362643 +Node: Boolean Ops362781 +Ref: Boolean Ops-Footnote-1367260 +Node: Conditional Exp367351 +Node: Function Calls369078 +Node: Precedence372958 +Node: Locales376626 +Node: Expressions Summary378257 +Node: Patterns and Actions380831 +Node: Pattern Overview381951 +Node: Regexp Patterns383630 +Node: Expression Patterns384173 +Node: Ranges387953 +Node: BEGIN/END391059 +Node: Using BEGIN/END391821 +Ref: Using BEGIN/END-Footnote-1394558 +Node: I/O And BEGIN/END394664 +Node: BEGINFILE/ENDFILE396978 +Node: Empty399879 +Node: Using Shell Variables400196 +Node: Action Overview402472 +Node: Statements404799 +Node: If Statement406647 +Node: While Statement408145 +Node: Do Statement410173 +Node: For Statement411315 +Node: Switch Statement414470 +Node: Break Statement416858 +Node: Continue Statement418899 +Node: Next Statement420724 +Node: Nextfile Statement423104 +Node: Exit Statement425734 +Node: Built-in Variables428137 +Node: User-modified429270 +Ref: User-modified-Footnote-1436950 +Node: Auto-set437012 +Ref: Auto-set-Footnote-1449869 +Ref: Auto-set-Footnote-2450074 +Node: ARGC and ARGV450130 +Node: Pattern Action Summary454334 +Node: Arrays456761 +Node: Array Basics458090 +Node: Array Intro458934 +Ref: figure-array-elements460907 +Ref: Array Intro-Footnote-1463431 +Node: Reference to Elements463559 +Node: Assigning Elements466009 +Node: Array Example466500 +Node: Scanning an Array468258 +Node: Controlling Scanning471274 +Ref: Controlling Scanning-Footnote-1476463 +Node: Numeric Array Subscripts476779 +Node: Uninitialized Subscripts478964 +Node: Delete480581 +Ref: Delete-Footnote-1483325 +Node: Multidimensional483382 +Node: Multiscanning486477 +Node: Arrays of Arrays488066 +Node: Arrays Summary492827 +Node: Functions494932 +Node: Built-in495805 +Node: Calling Built-in496883 +Node: Numeric Functions498871 +Ref: Numeric Functions-Footnote-1502893 +Ref: Numeric Functions-Footnote-2503250 +Ref: Numeric Functions-Footnote-3503298 +Node: String Functions503567 +Ref: String Functions-Footnote-1527031 +Ref: String Functions-Footnote-2527160 +Ref: String Functions-Footnote-3527408 +Node: Gory Details527495 +Ref: table-sub-escapes529276 +Ref: table-sub-proposed530796 +Ref: table-posix-sub532160 +Ref: table-gensub-escapes533700 +Ref: Gory Details-Footnote-1534532 +Node: I/O Functions534683 +Ref: I/O Functions-Footnote-1541784 +Node: Time Functions541931 +Ref: Time Functions-Footnote-1552400 +Ref: Time Functions-Footnote-2552468 +Ref: Time Functions-Footnote-3552626 +Ref: Time Functions-Footnote-4552737 +Ref: Time Functions-Footnote-5552849 +Ref: Time Functions-Footnote-6553076 +Node: Bitwise Functions553342 +Ref: table-bitwise-ops553904 +Ref: Bitwise Functions-Footnote-1558212 +Node: Type Functions558381 +Node: I18N Functions559530 +Node: User-defined561175 +Node: Definition Syntax561979 +Ref: Definition Syntax-Footnote-1567385 +Node: Function Example567454 +Ref: Function Example-Footnote-1570371 +Node: Function Caveats570393 +Node: Calling A Function570911 +Node: Variable Scope571866 +Node: Pass By Value/Reference574854 +Node: Return Statement578364 +Node: Dynamic Typing581348 +Node: Indirect Calls582277 +Ref: Indirect Calls-Footnote-1593581 +Node: Functions Summary593709 +Node: Library Functions596408 +Ref: Library Functions-Footnote-1600026 +Ref: Library Functions-Footnote-2600169 +Node: Library Names600340 +Ref: Library Names-Footnote-1603800 +Ref: Library Names-Footnote-2604020 +Node: General Functions604106 +Node: Strtonum Function605209 +Node: Assert Function608229 +Node: Round Function611553 +Node: Cliff Random Function613094 +Node: Ordinal Functions614110 +Ref: Ordinal Functions-Footnote-1617175 +Ref: Ordinal Functions-Footnote-2617427 +Node: Join Function617638 +Ref: Join Function-Footnote-1619409 +Node: Getlocaltime Function619609 +Node: Readfile Function623350 +Node: Shell Quoting625320 +Node: Data File Management626721 +Node: Filetrans Function627353 +Node: Rewind Function631412 +Node: File Checking632797 +Ref: File Checking-Footnote-1634125 +Node: Empty Files634326 +Node: Ignoring Assigns636305 +Node: Getopt Function637856 +Ref: Getopt Function-Footnote-1649316 +Node: Passwd Functions649519 +Ref: Passwd Functions-Footnote-1658370 +Node: Group Functions658458 +Ref: Group Functions-Footnote-1666361 +Node: Walking Arrays666574 +Node: Library Functions Summary668177 +Node: Library Exercises669578 +Node: Sample Programs670858 +Node: Running Examples671628 +Node: Clones672356 +Node: Cut Program673580 +Node: Egrep Program683310 +Ref: Egrep Program-Footnote-1690814 +Node: Id Program690924 +Node: Split Program694568 +Ref: Split Program-Footnote-1698014 +Node: Tee Program698142 +Node: Uniq Program700929 +Node: Wc Program708350 +Ref: Wc Program-Footnote-1712598 +Node: Miscellaneous Programs712690 +Node: Dupword Program713903 +Node: Alarm Program715934 +Node: Translate Program720738 +Ref: Translate Program-Footnote-1725302 +Node: Labels Program725572 +Ref: Labels Program-Footnote-1728921 +Node: Word Sorting729005 +Node: History Sorting733075 +Node: Extract Program734911 +Node: Simple Sed742443 +Node: Igawk Program745505 +Ref: Igawk Program-Footnote-1759831 +Ref: Igawk Program-Footnote-2760032 +Ref: Igawk Program-Footnote-3760154 +Node: Anagram Program760269 +Node: Signature Program763331 +Node: Programs Summary764578 +Node: Programs Exercises765771 +Ref: Programs Exercises-Footnote-1769902 +Node: Advanced Features769993 +Node: Nondecimal Data771941 +Node: Array Sorting773531 +Node: Controlling Array Traversal774228 +Ref: Controlling Array Traversal-Footnote-1782559 +Node: Array Sorting Functions782677 +Ref: Array Sorting Functions-Footnote-1786569 +Node: Two-way I/O786763 +Ref: Two-way I/O-Footnote-1791707 +Ref: Two-way I/O-Footnote-2791893 +Node: TCP/IP Networking791975 +Node: Profiling794852 +Node: Advanced Features Summary802396 +Node: Internationalization804329 +Node: I18N and L10N805809 +Node: Explaining gettext806495 +Ref: Explaining gettext-Footnote-1811524 +Ref: Explaining gettext-Footnote-2811708 +Node: Programmer i18n811873 +Ref: Programmer i18n-Footnote-1816739 +Node: Translator i18n816788 +Node: String Extraction817582 +Ref: String Extraction-Footnote-1818713 +Node: Printf Ordering818799 +Ref: Printf Ordering-Footnote-1821585 +Node: I18N Portability821649 +Ref: I18N Portability-Footnote-1824098 +Node: I18N Example824161 +Ref: I18N Example-Footnote-1826961 +Node: Gawk I18N827033 +Node: I18N Summary827671 +Node: Debugger829010 +Node: Debugging830032 +Node: Debugging Concepts830473 +Node: Debugging Terms832330 +Node: Awk Debugging834905 +Node: Sample Debugging Session835797 +Node: Debugger Invocation836317 +Node: Finding The Bug837701 +Node: List of Debugger Commands844176 +Node: Breakpoint Control845508 +Node: Debugger Execution Control849200 +Node: Viewing And Changing Data852564 +Node: Execution Stack855929 +Node: Debugger Info857567 +Node: Miscellaneous Debugger Commands861584 +Node: Readline Support866776 +Node: Limitations867668 +Node: Debugging Summary869765 +Node: Arbitrary Precision Arithmetic870933 +Node: Computer Arithmetic872349 +Ref: table-numeric-ranges875950 +Ref: Computer Arithmetic-Footnote-1876809 +Node: Math Definitions876866 +Ref: table-ieee-formats880153 +Ref: Math Definitions-Footnote-1880757 +Node: MPFR features880862 +Node: FP Math Caution882531 +Ref: FP Math Caution-Footnote-1883581 +Node: Inexactness of computations883950 +Node: Inexact representation884898 +Node: Comparing FP Values886253 +Node: Errors accumulate887326 +Node: Getting Accuracy888759 +Node: Try To Round891418 +Node: Setting precision892317 +Ref: table-predefined-precision-strings893001 +Node: Setting the rounding mode894795 +Ref: table-gawk-rounding-modes895159 +Ref: Setting the rounding mode-Footnote-1898613 +Node: Arbitrary Precision Integers898792 +Ref: Arbitrary Precision Integers-Footnote-1901783 +Node: POSIX Floating Point Problems901932 +Ref: POSIX Floating Point Problems-Footnote-1905808 +Node: Floating point summary905846 +Node: Dynamic Extensions908038 +Node: Extension Intro909590 +Node: Plugin License910856 +Node: Extension Mechanism Outline911653 +Ref: figure-load-extension912081 +Ref: figure-register-new-function913561 +Ref: figure-call-new-function914565 +Node: Extension API Description916551 +Node: Extension API Functions Introduction918001 +Node: General Data Types922837 +Ref: General Data Types-Footnote-1928524 +Node: Memory Allocation Functions928823 +Ref: Memory Allocation Functions-Footnote-1931653 +Node: Constructor Functions931749 +Node: Registration Functions933483 +Node: Extension Functions934168 +Node: Exit Callback Functions936464 +Node: Extension Version String937712 +Node: Input Parsers938362 +Node: Output Wrappers948177 +Node: Two-way processors952693 +Node: Printing Messages954897 +Ref: Printing Messages-Footnote-1955974 +Node: Updating `ERRNO'956126 +Node: Requesting Values956866 +Ref: table-value-types-returned957594 +Node: Accessing Parameters958552 +Node: Symbol Table Access959783 +Node: Symbol table by name960297 +Node: Symbol table by cookie962277 +Ref: Symbol table by cookie-Footnote-1966416 +Node: Cached values966479 +Ref: Cached values-Footnote-1969983 +Node: Array Manipulation970074 +Ref: Array Manipulation-Footnote-1971172 +Node: Array Data Types971211 +Ref: Array Data Types-Footnote-1973868 +Node: Array Functions973960 +Node: Flattening Arrays977814 +Node: Creating Arrays984701 +Node: Extension API Variables989468 +Node: Extension Versioning990104 +Node: Extension API Informational Variables992005 +Node: Extension API Boilerplate993093 +Node: Finding Extensions996909 +Node: Extension Example997469 +Node: Internal File Description998241 +Node: Internal File Ops1002308 +Ref: Internal File Ops-Footnote-11013966 +Node: Using Internal File Ops1014106 +Ref: Using Internal File Ops-Footnote-11016489 +Node: Extension Samples1016762 +Node: Extension Sample File Functions1018286 +Node: Extension Sample Fnmatch1025888 +Node: Extension Sample Fork1027370 +Node: Extension Sample Inplace1028583 +Node: Extension Sample Ord1030258 +Node: Extension Sample Readdir1031094 +Ref: table-readdir-file-types1031950 +Node: Extension Sample Revout1032761 +Node: Extension Sample Rev2way1033352 +Node: Extension Sample Read write array1034093 +Node: Extension Sample Readfile1036032 +Node: Extension Sample Time1037127 +Node: Extension Sample API Tests1038476 +Node: gawkextlib1038967 +Node: Extension summary1041617 +Node: Extension Exercises1045299 +Node: Language History1046021 +Node: V7/SVR3.11047678 +Node: SVR41049859 +Node: POSIX1051304 +Node: BTL1052693 +Node: POSIX/GNU1053427 +Node: Feature History1058996 +Node: Common Extensions1072087 +Node: Ranges and Locales1073411 +Ref: Ranges and Locales-Footnote-11078050 +Ref: Ranges and Locales-Footnote-21078077 +Ref: Ranges and Locales-Footnote-31078311 +Node: Contributors1078532 +Node: History summary1084072 +Node: Installation1085441 +Node: Gawk Distribution1086397 +Node: Getting1086881 +Node: Extracting1087705 +Node: Distribution contents1089347 +Node: Unix Installation1095064 +Node: Quick Installation1095681 +Node: Additional Configuration Options1098112 +Node: Configuration Philosophy1099852 +Node: Non-Unix Installation1102203 +Node: PC Installation1102661 +Node: PC Binary Installation1103987 +Node: PC Compiling1105835 +Ref: PC Compiling-Footnote-11108856 +Node: PC Testing1108961 +Node: PC Using1110137 +Node: Cygwin1114252 +Node: MSYS1115075 +Node: VMS Installation1115573 +Node: VMS Compilation1116365 +Ref: VMS Compilation-Footnote-11117587 +Node: VMS Dynamic Extensions1117645 +Node: VMS Installation Details1119329 +Node: VMS Running1121581 +Node: VMS GNV1124422 +Node: VMS Old Gawk1125151 +Node: Bugs1125621 +Node: Other Versions1129591 +Node: Installation summary1135804 +Node: Notes1136860 +Node: Compatibility Mode1137725 +Node: Additions1138507 +Node: Accessing The Source1139432 +Node: Adding Code1140868 +Node: New Ports1147040 +Node: Derived Files1151521 +Ref: Derived Files-Footnote-11156996 +Ref: Derived Files-Footnote-21157030 +Ref: Derived Files-Footnote-31157626 +Node: Future Extensions1157740 +Node: Implementation Limitations1158346 +Node: Extension Design1159594 +Node: Old Extension Problems1160748 +Ref: Old Extension Problems-Footnote-11162265 +Node: Extension New Mechanism Goals1162322 +Ref: Extension New Mechanism Goals-Footnote-11165682 +Node: Extension Other Design Decisions1165871 +Node: Extension Future Growth1167979 +Node: Old Extension Mechanism1168815 +Node: Notes summary1170577 +Node: Basic Concepts1171763 +Node: Basic High Level1172444 +Ref: figure-general-flow1172716 +Ref: figure-process-flow1173315 +Ref: Basic High Level-Footnote-11176544 +Node: Basic Data Typing1176729 +Node: Glossary1180057 +Node: Copying1205215 +Node: GNU Free Documentation License1242771 +Node: Index1267907 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 8040e06e..f314c99f 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -792,6 +792,8 @@ particular records in a file and perform operations upon them. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the + shell. * Data File Management:: Functions for managing command-line data files. * Filetrans Function:: A function for handling data file @@ -9796,6 +9798,9 @@ The program builds up a list of command lines, using the @command{mv} utility to rename the files. It then sends the list to the shell for execution. +@xref{Shell Quoting}, for a function that can help in generating +command lines to be fed to the shell. + @docbook </sidebar> @end docbook @@ -9827,6 +9832,9 @@ uppercase characters converted to lowercase The program builds up a list of command lines, using the @command{mv} utility to rename the files. It then sends the list to the shell for execution. + +@xref{Shell Quoting}, for a function that can help in generating +command lines to be fed to the shell. @end cartouche @end ifnotdocbook @c ENDOFRANGE outre @@ -20234,6 +20242,69 @@ $ @kbd{gawk -f quicksort.awk -f indirectcall.awk class_data2} @print{} rsort: <100.0 95.6 93.4 87.1> @end example +Another example where indirect functions calls are useful can be found in +processing arrays. @DBREF{Walking Arrays} presented a simple function +for ``walking'' an array of arrays. That function simply printed the +name and value of each scalar array element. However, it is easy to +generalize that function, by passing in the name of a function to call +when walking an array. The modified function looks like this: + +@example +@c file eg/lib/processarray.awk +function process_array(arr, name, process, do_arrays, i, new_name) +@{ + for (i in arr) @{ + new_name = (name "[" i "]") + if (isarray(arr[i])) @{ + if (do_arrays) + @@process(new_name, arr[i]) + process_array(arr[i], new_name, process, do_arrays) + @} else + @@process(new_name, arr[i]) + @} +@} +@c endfile +@end example + +The arguments are as follows: + +@table @code +@item arr +The array. + +@item name +The name of the array (a string). + +@item process +The name of the function to call. + +@item do_arrays +If this is true, the function can handle elements that are subarrays. +@end table + +If subarrays are to be processed, that is done before walking them further. + +When run with the following scaffolding, the function produces the same +results as does the earlier @code{walk_array()} function: + +@example +BEGIN @{ + a[1] = 1 + a[2][1] = 21 + a[2][2] = 22 + a[3] = 3 + a[4][1][1] = 411 + a[4][2] = 42 + + process_array(a, "a", "do_print", 0) +@} + +function do_print(name, element) +@{ + printf "%s = %s\n", name, element +@} +@end example + Remember that you must supply a leading @samp{@@} in front of an indirect function call. Starting with @value{PVERSION} 4.1.2 of @command{gawk}, indirect function @@ -20562,6 +20633,7 @@ programming use. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the shell. @end menu @node Strtonum Function @@ -21269,6 +21341,84 @@ test would be @samp{contents == ""}. @xref{Extension Sample Readfile}, for an extension function that also reads an entire file into memory. +@node Shell Quoting +@subsection Quoting Strings to Pass to The Shell + +@c included by permission +@ignore +Date: Sun, 27 Jul 2014 17:16:16 -0700 +Message-ID: <CAKuGj+iCF_obaCLDUX60aSAgbfocFVtguG39GyeoNxTFby5sqQ@mail.gmail.com> +Subject: Useful awk function +From: Mike Brennan <mike@madronabluff.com> +To: Arnold Robbins <arnold@skeeve.com> +@end ignore + +Michael Brennan offers the following programming pattern, +which he uses frequently: + +@example +#! /bin/sh + +awkp=' + @dots{} + ' + +@var{input_program} | awk "$awkp" | /bin/sh +@end example + +For example, a program of his named @command{flac-edit} has this form: + +@example +$ @kbd{flac-edit -song="Whoope! That's Great" file.flac} +@end example + +It generates the following output, which is to be piped to +the shell (@file{/bin/sh}): + +@example +chmod +w file.flac +metaflac --remove-tag=TITLE file.flac +LANG=en_US.88591 metaflac --set-tag=TITLE='Whoope! That'"'"'s Great' file.flac +chmod -w file.flac +@end example + +Note the need for shell quoting. The function @code{shell_quote()} +does it. @code{SINGLE} is the one-character string @code{"'"} and +@code{QSINGLE} is the three-character string @code{"\"'\""}. + +@example +@c file eg/lib/shellquote.awk +# shell_quote --- quote an argument for passing to the shell +@c endfile +@ignore +@c file eg/lib/shellquote.awk +# +# Michael Brennan +# brennan@@madronabluff.com +# September 2014 +@c endfile +@end ignore +@c file eg/lib/shellquote.awk + +function shell_quote(s, # parameter + SINGLE, QSINGLE, i, X, n, ret) # locals +@{ + if (s == "") + return "\"\"" + + SINGLE = "\x27" # single quote + QSINGLE = "\"\x27\"" + n = split(s, X, SINGLE) + + ret = SINGLE X[1] SINGLE + for (i = 2; i <= n; i++) + ret = ret QSINGLE SINGLE X[i] SINGLE + + return ret +@} +@c endfile +@end example + @node Data File Management @section @value{DDF} Management @@ -22808,12 +22958,12 @@ When run, the program produces the following output: @example $ @kbd{gawk -f walk_array.awk} -@print{} a[4][1][1] = 411 -@print{} a[4][2] = 42 @print{} a[1] = 1 @print{} a[2][1] = 21 @print{} a[2][2] = 22 @print{} a[3] = 3 +@print{} a[4][1][1] = 411 +@print{} a[4][2] = 42 @end example @c ENDOFRANGE libfgdata @@ -24829,8 +24979,8 @@ character of the ``to'' list is used for the remaining characters in the Once upon a time, @c early or mid-1989! -a user proposed that a transliteration function should -be added to @command{gawk}. +a user proposed adding a transliteration function +to @command{gawk}. @c Wishing to avoid gratuitous new features, @c at least theoretically The following program was written to @@ -24838,15 +24988,12 @@ prove that character transliteration could be done with a user-level function. This program is not as complete as the system @command{tr} utility but it does most of the job. -The @command{translate} program demonstrates one of the few weaknesses -of standard @command{awk}: dealing with individual characters is very -painful, requiring repeated use of the @code{substr()}, @code{index()}, -and @code{gsub()} built-in functions -(@pxref{String Functions}).@footnote{This -program was also written before @command{gawk} acquired the ability to -split each character in a string into separate array elements.} -There are two functions. The first, @code{stranslate()}, takes three -arguments: +The @command{translate} program was written long before @command{gawk} +acquired the ability to split each character in a string into separate +array elements. Thus, it makes repeated use of the @code{substr()}, +@code{index()}, and @code{gsub()} built-in functions (@pxref{String +Functions}). There are two functions. The first, @code{stranslate()}, +takes three arguments: @table @code @item from @@ -24865,7 +25012,7 @@ loop goes through @code{from}, one character at a time. For each character in @code{from}, if the character appears in @code{target}, it is replaced with the corresponding @code{to} character. -The @code{translate()} function simply calls @code{stranslate()} using @code{$0} +The @code{translate()} function calls @code{stranslate()} using @code{$0} as the target. The main program sets two global variables, @code{FROM} and @code{TO}, from the command line, and then changes @code{ARGV} so that @command{awk} reads from the standard input. @@ -37695,7 +37842,7 @@ For VAX: @end example Compile time macros need to be defined before the first VMS-supplied -header file is included. +header file is included, as follows: @example #if (__CRTL_VER >= 70200000) && !defined (__VAX) @@ -37711,6 +37858,11 @@ header file is included. #endif @end example +If you are writing your own extensions to run on VMS, you must supply these +definitions yourself. The @file{config.h} file created when building @command{gawk} +on VMS does this for you; if instead you use that file or a similar one, then you +must remember to include it before any VMS-supplied header files. + @node VMS Installation Details @appendixsubsubsec Installing @command{gawk} on VMS @@ -37935,8 +38087,8 @@ If you have problems with @command{gawk} or think that you have found a bug, please report it to the developers; we cannot promise to do anything but we might well want to fix it. -Before reporting a bug, please make sure you have actually found a real bug. -Carefully reread the documentation and see if it really says you can do +Before reporting a bug, please make sure you have really found a genuine bug. +Carefully reread the documentation and see if it says you can do what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation! @@ -37954,7 +38106,7 @@ You can get this information with the command @samp{gawk --version}. @cindex @code{bug-gawk@@gnu.org} bug reporting address @cindex email address for bug reports, @code{bug-gawk@@gnu.org} @cindex bug reports, email address, @code{bug-gawk@@gnu.org} -Once you have a precise problem, send email to +Once you have a precise problem description, send email to @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. The @command{gawk} maintainers subscribe to this address and diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 3b2214df..f041935f 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -787,6 +787,8 @@ particular records in a file and perform operations upon them. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the + shell. * Data File Management:: Functions for managing command-line data files. * Filetrans Function:: A function for handling data file @@ -9391,6 +9393,9 @@ uppercase characters converted to lowercase The program builds up a list of command lines, using the @command{mv} utility to rename the files. It then sends the list to the shell for execution. + +@xref{Shell Quoting}, for a function that can help in generating +command lines to be fed to the shell. @end sidebar @c ENDOFRANGE outre @c ENDOFRANGE reout @@ -19360,6 +19365,69 @@ $ @kbd{gawk -f quicksort.awk -f indirectcall.awk class_data2} @print{} rsort: <100.0 95.6 93.4 87.1> @end example +Another example where indirect functions calls are useful can be found in +processing arrays. @DBREF{Walking Arrays} presented a simple function +for ``walking'' an array of arrays. That function simply printed the +name and value of each scalar array element. However, it is easy to +generalize that function, by passing in the name of a function to call +when walking an array. The modified function looks like this: + +@example +@c file eg/lib/processarray.awk +function process_array(arr, name, process, do_arrays, i, new_name) +@{ + for (i in arr) @{ + new_name = (name "[" i "]") + if (isarray(arr[i])) @{ + if (do_arrays) + @@process(new_name, arr[i]) + process_array(arr[i], new_name, process, do_arrays) + @} else + @@process(new_name, arr[i]) + @} +@} +@c endfile +@end example + +The arguments are as follows: + +@table @code +@item arr +The array. + +@item name +The name of the array (a string). + +@item process +The name of the function to call. + +@item do_arrays +If this is true, the function can handle elements that are subarrays. +@end table + +If subarrays are to be processed, that is done before walking them further. + +When run with the following scaffolding, the function produces the same +results as does the earlier @code{walk_array()} function: + +@example +BEGIN @{ + a[1] = 1 + a[2][1] = 21 + a[2][2] = 22 + a[3] = 3 + a[4][1][1] = 411 + a[4][2] = 42 + + process_array(a, "a", "do_print", 0) +@} + +function do_print(name, element) +@{ + printf "%s = %s\n", name, element +@} +@end example + Remember that you must supply a leading @samp{@@} in front of an indirect function call. Starting with @value{PVERSION} 4.1.2 of @command{gawk}, indirect function @@ -19688,6 +19756,7 @@ programming use. * Join Function:: A function to join an array into a string. * Getlocaltime Function:: A function to get formatted times. * Readfile Function:: A function to read an entire file at once. +* Shell Quoting:: A function to quote strings for the shell. @end menu @node Strtonum Function @@ -20395,6 +20464,84 @@ test would be @samp{contents == ""}. @xref{Extension Sample Readfile}, for an extension function that also reads an entire file into memory. +@node Shell Quoting +@subsection Quoting Strings to Pass to The Shell + +@c included by permission +@ignore +Date: Sun, 27 Jul 2014 17:16:16 -0700 +Message-ID: <CAKuGj+iCF_obaCLDUX60aSAgbfocFVtguG39GyeoNxTFby5sqQ@mail.gmail.com> +Subject: Useful awk function +From: Mike Brennan <mike@madronabluff.com> +To: Arnold Robbins <arnold@skeeve.com> +@end ignore + +Michael Brennan offers the following programming pattern, +which he uses frequently: + +@example +#! /bin/sh + +awkp=' + @dots{} + ' + +@var{input_program} | awk "$awkp" | /bin/sh +@end example + +For example, a program of his named @command{flac-edit} has this form: + +@example +$ @kbd{flac-edit -song="Whoope! That's Great" file.flac} +@end example + +It generates the following output, which is to be piped to +the shell (@file{/bin/sh}): + +@example +chmod +w file.flac +metaflac --remove-tag=TITLE file.flac +LANG=en_US.88591 metaflac --set-tag=TITLE='Whoope! That'"'"'s Great' file.flac +chmod -w file.flac +@end example + +Note the need for shell quoting. The function @code{shell_quote()} +does it. @code{SINGLE} is the one-character string @code{"'"} and +@code{QSINGLE} is the three-character string @code{"\"'\""}. + +@example +@c file eg/lib/shellquote.awk +# shell_quote --- quote an argument for passing to the shell +@c endfile +@ignore +@c file eg/lib/shellquote.awk +# +# Michael Brennan +# brennan@@madronabluff.com +# September 2014 +@c endfile +@end ignore +@c file eg/lib/shellquote.awk + +function shell_quote(s, # parameter + SINGLE, QSINGLE, i, X, n, ret) # locals +@{ + if (s == "") + return "\"\"" + + SINGLE = "\x27" # single quote + QSINGLE = "\"\x27\"" + n = split(s, X, SINGLE) + + ret = SINGLE X[1] SINGLE + for (i = 2; i <= n; i++) + ret = ret QSINGLE SINGLE X[i] SINGLE + + return ret +@} +@c endfile +@end example + @node Data File Management @section @value{DDF} Management @@ -21905,12 +22052,12 @@ When run, the program produces the following output: @example $ @kbd{gawk -f walk_array.awk} -@print{} a[4][1][1] = 411 -@print{} a[4][2] = 42 @print{} a[1] = 1 @print{} a[2][1] = 21 @print{} a[2][2] = 22 @print{} a[3] = 3 +@print{} a[4][1][1] = 411 +@print{} a[4][2] = 42 @end example @c ENDOFRANGE libfgdata @@ -23926,8 +24073,8 @@ character of the ``to'' list is used for the remaining characters in the Once upon a time, @c early or mid-1989! -a user proposed that a transliteration function should -be added to @command{gawk}. +a user proposed adding a transliteration function +to @command{gawk}. @c Wishing to avoid gratuitous new features, @c at least theoretically The following program was written to @@ -23935,15 +24082,12 @@ prove that character transliteration could be done with a user-level function. This program is not as complete as the system @command{tr} utility but it does most of the job. -The @command{translate} program demonstrates one of the few weaknesses -of standard @command{awk}: dealing with individual characters is very -painful, requiring repeated use of the @code{substr()}, @code{index()}, -and @code{gsub()} built-in functions -(@pxref{String Functions}).@footnote{This -program was also written before @command{gawk} acquired the ability to -split each character in a string into separate array elements.} -There are two functions. The first, @code{stranslate()}, takes three -arguments: +The @command{translate} program was written long before @command{gawk} +acquired the ability to split each character in a string into separate +array elements. Thus, it makes repeated use of the @code{substr()}, +@code{index()}, and @code{gsub()} built-in functions (@pxref{String +Functions}). There are two functions. The first, @code{stranslate()}, +takes three arguments: @table @code @item from @@ -23962,7 +24106,7 @@ loop goes through @code{from}, one character at a time. For each character in @code{from}, if the character appears in @code{target}, it is replaced with the corresponding @code{to} character. -The @code{translate()} function simply calls @code{stranslate()} using @code{$0} +The @code{translate()} function calls @code{stranslate()} using @code{$0} as the target. The main program sets two global variables, @code{FROM} and @code{TO}, from the command line, and then changes @code{ARGV} so that @command{awk} reads from the standard input. @@ -36792,7 +36936,7 @@ For VAX: @end example Compile time macros need to be defined before the first VMS-supplied -header file is included. +header file is included, as follows: @example #if (__CRTL_VER >= 70200000) && !defined (__VAX) @@ -36808,6 +36952,11 @@ header file is included. #endif @end example +If you are writing your own extensions to run on VMS, you must supply these +definitions yourself. The @file{config.h} file created when building @command{gawk} +on VMS does this for you; if instead you use that file or a similar one, then you +must remember to include it before any VMS-supplied header files. + @node VMS Installation Details @appendixsubsubsec Installing @command{gawk} on VMS @@ -37032,8 +37181,8 @@ If you have problems with @command{gawk} or think that you have found a bug, please report it to the developers; we cannot promise to do anything but we might well want to fix it. -Before reporting a bug, please make sure you have actually found a real bug. -Carefully reread the documentation and see if it really says you can do +Before reporting a bug, please make sure you have really found a genuine bug. +Carefully reread the documentation and see if it says you can do what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation! @@ -37051,7 +37200,7 @@ You can get this information with the command @samp{gawk --version}. @cindex @code{bug-gawk@@gnu.org} bug reporting address @cindex email address for bug reports, @code{bug-gawk@@gnu.org} @cindex bug reports, email address, @code{bug-gawk@@gnu.org} -Once you have a precise problem, send email to +Once you have a precise problem description, send email to @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. The @command{gawk} maintainers subscribe to this address and |