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 b2257736..89015ce3 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 47cbde92..dfa21a7b 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 @@ -6792,6 +6794,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 @@ -14197,6 +14202,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. @@ -14470,6 +14532,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 @@ -14945,7 +15008,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 ----------------------------------- @@ -15008,6 +15071,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 @@ -16110,12 +16225,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 @@ -17620,17 +17735,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. @@ -17647,10 +17762,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: @@ -17727,9 +17842,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 @@ -27839,7 +27951,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 @@ -27853,6 +27965,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 @@ -28021,11 +28139,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 @@ -28038,7 +28156,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 @@ -31729,7 +31848,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) @@ -31844,7 +31963,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) @@ -32101,7 +32220,7 @@ Index * decimal point character, locale specific: Options. (line 270) * decrement operators: Increment Ops. (line 35) * default keyword: Switch Statement. (line 6) -* Deifik, Scott <1>: Bugs. (line 71) +* Deifik, Scott <1>: Bugs. (line 72) * Deifik, Scott <2>: Contributors. (line 53) * Deifik, Scott: Acknowledgments. (line 60) * delete ARRAY: Delete. (line 39) @@ -33033,7 +33152,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) @@ -33272,7 +33391,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) @@ -33478,7 +33597,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) @@ -33587,7 +33706,7 @@ Index * RLENGTH variable: Auto-set. (line 259) * RLENGTH variable, match() function and: String Functions. (line 227) * Robbins, Arnold <1>: Future Extensions. (line 6) -* Robbins, Arnold <2>: Bugs. (line 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) @@ -34118,7 +34237,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) @@ -34151,557 +34270,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-1129379 -Node: Other Arguments129404 -Node: Naming Standard Input132365 -Node: Environment Variables133458 -Node: AWKPATH Variable134016 -Ref: AWKPATH Variable-Footnote-1136868 -Ref: AWKPATH Variable-Footnote-2136913 -Node: AWKLIBPATH Variable137173 -Node: Other Environment Variables137932 -Node: Exit Status141405 -Node: Include Files142080 -Node: Loading Shared Libraries145658 -Node: Obsolete147085 -Node: Undocumented147782 -Node: Invoking Summary148049 -Node: Regexp149715 -Node: Regexp Usage151174 -Node: Escape Sequences153207 -Node: Regexp Operators159307 -Ref: Regexp Operators-Footnote-1166742 -Ref: Regexp Operators-Footnote-2166889 -Node: Bracket Expressions166987 -Ref: table-char-classes169004 -Node: Leftmost Longest171944 -Node: Computed Regexps173246 -Node: GNU Regexp Operators176643 -Node: Case-sensitivity180349 -Ref: Case-sensitivity-Footnote-1183239 -Ref: Case-sensitivity-Footnote-2183474 -Node: Regexp Summary183582 -Node: Reading Files185051 -Node: Records187145 -Node: awk split records187877 -Node: gawk split records192791 -Ref: gawk split records-Footnote-1197330 -Node: Fields197367 -Ref: Fields-Footnote-1200165 -Node: Nonconstant Fields200251 -Ref: Nonconstant Fields-Footnote-1202481 -Node: Changing Fields202683 -Node: Field Separators208615 -Node: Default Field Splitting211319 -Node: Regexp Field Splitting212436 -Node: Single Character Fields215786 -Node: Command Line Field Separator216845 -Node: Full Line Fields220057 -Ref: Full Line Fields-Footnote-1220565 -Node: Field Splitting Summary220611 -Ref: Field Splitting Summary-Footnote-1223742 -Node: Constant Size223843 -Node: Splitting By Content228449 -Ref: Splitting By Content-Footnote-1232522 -Node: Multiple Line232562 -Ref: Multiple Line-Footnote-1238451 -Node: Getline238630 -Node: Plain Getline240841 -Node: Getline/Variable243481 -Node: Getline/File244628 -Node: Getline/Variable/File246012 -Ref: Getline/Variable/File-Footnote-1247613 -Node: Getline/Pipe247700 -Node: Getline/Variable/Pipe250383 -Node: Getline/Coprocess251514 -Node: Getline/Variable/Coprocess252766 -Node: Getline Notes253505 -Node: Getline Summary256297 -Ref: table-getline-variants256709 -Node: Read Timeout257538 -Ref: Read Timeout-Footnote-1261352 -Node: Command-line directories261410 -Node: Input Summary262314 -Node: Input Exercises265566 -Node: Printing266294 -Node: Print268071 -Node: Print Examples269528 -Node: Output Separators272307 -Node: OFMT274325 -Node: Printf275679 -Node: Basic Printf276464 -Node: Control Letters278035 -Node: Format Modifiers282019 -Node: Printf Examples288026 -Node: Redirection290508 -Node: Special FD297239 -Ref: Special FD-Footnote-1300396 -Node: Special Files300470 -Node: Other Inherited Files301086 -Node: Special Network302086 -Node: Special Caveats302947 -Node: Close Files And Pipes303898 -Ref: Close Files And Pipes-Footnote-1311077 -Ref: Close Files And Pipes-Footnote-2311225 -Node: Output Summary311375 -Node: Output Exercises312371 -Node: Expressions313051 -Node: Values314236 -Node: Constants314912 -Node: Scalar Constants315592 -Ref: Scalar Constants-Footnote-1316451 -Node: Nondecimal-numbers316701 -Node: Regexp Constants319701 -Node: Using Constant Regexps320226 -Node: Variables323364 -Node: Using Variables324019 -Node: Assignment Options325929 -Node: Conversion327804 -Node: Strings And Numbers328328 -Ref: Strings And Numbers-Footnote-1331392 -Node: Locale influences conversions331501 -Ref: table-locale-affects334216 -Node: All Operators334804 -Node: Arithmetic Ops335434 -Node: Concatenation337939 -Ref: Concatenation-Footnote-1340758 -Node: Assignment Ops340864 -Ref: table-assign-ops345847 -Node: Increment Ops347125 -Node: Truth Values and Conditions350563 -Node: Truth Values351646 -Node: Typing and Comparison352695 -Node: Variable Typing353488 -Node: Comparison Operators357140 -Ref: table-relational-ops357550 -Node: POSIX String Comparison361065 -Ref: POSIX String Comparison-Footnote-1362137 -Node: Boolean Ops362275 -Ref: Boolean Ops-Footnote-1366754 -Node: Conditional Exp366845 -Node: Function Calls368572 -Node: Precedence372452 -Node: Locales376120 -Node: Expressions Summary377751 -Node: Patterns and Actions380325 -Node: Pattern Overview381445 -Node: Regexp Patterns383124 -Node: Expression Patterns383667 -Node: Ranges387447 -Node: BEGIN/END390553 -Node: Using BEGIN/END391315 -Ref: Using BEGIN/END-Footnote-1394052 -Node: I/O And BEGIN/END394158 -Node: BEGINFILE/ENDFILE396472 -Node: Empty399373 -Node: Using Shell Variables399690 -Node: Action Overview401966 -Node: Statements404293 -Node: If Statement406141 -Node: While Statement407639 -Node: Do Statement409667 -Node: For Statement410809 -Node: Switch Statement413964 -Node: Break Statement416352 -Node: Continue Statement418393 -Node: Next Statement420218 -Node: Nextfile Statement422598 -Node: Exit Statement425228 -Node: Built-in Variables427631 -Node: User-modified428764 -Ref: User-modified-Footnote-1436444 -Node: Auto-set436506 -Ref: Auto-set-Footnote-1449700 -Ref: Auto-set-Footnote-2449905 -Node: ARGC and ARGV449961 -Node: Pattern Action Summary454165 -Node: Arrays456592 -Node: Array Basics457921 -Node: Array Intro458765 -Ref: figure-array-elements460738 -Ref: Array Intro-Footnote-1463262 -Node: Reference to Elements463390 -Node: Assigning Elements465840 -Node: Array Example466331 -Node: Scanning an Array468089 -Node: Controlling Scanning471105 -Ref: Controlling Scanning-Footnote-1476294 -Node: Numeric Array Subscripts476610 -Node: Uninitialized Subscripts478795 -Node: Delete480412 -Ref: Delete-Footnote-1483156 -Node: Multidimensional483213 -Node: Multiscanning486308 -Node: Arrays of Arrays487897 -Node: Arrays Summary492658 -Node: Functions494763 -Node: Built-in495636 -Node: Calling Built-in496714 -Node: Numeric Functions498702 -Ref: Numeric Functions-Footnote-1503526 -Ref: Numeric Functions-Footnote-2503883 -Ref: Numeric Functions-Footnote-3503931 -Node: String Functions504200 -Ref: String Functions-Footnote-1527664 -Ref: String Functions-Footnote-2527793 -Ref: String Functions-Footnote-3528041 -Node: Gory Details528128 -Ref: table-sub-escapes529909 -Ref: table-sub-proposed531429 -Ref: table-posix-sub532793 -Ref: table-gensub-escapes534333 -Ref: Gory Details-Footnote-1535165 -Node: I/O Functions535316 -Ref: I/O Functions-Footnote-1542417 -Node: Time Functions542564 -Ref: Time Functions-Footnote-1553033 -Ref: Time Functions-Footnote-2553101 -Ref: Time Functions-Footnote-3553259 -Ref: Time Functions-Footnote-4553370 -Ref: Time Functions-Footnote-5553482 -Ref: Time Functions-Footnote-6553709 -Node: Bitwise Functions553975 -Ref: table-bitwise-ops554537 -Ref: Bitwise Functions-Footnote-1558845 -Node: Type Functions559014 -Node: I18N Functions560163 -Node: User-defined561808 -Node: Definition Syntax562612 -Ref: Definition Syntax-Footnote-1568018 -Node: Function Example568087 -Ref: Function Example-Footnote-1571004 -Node: Function Caveats571026 -Node: Calling A Function571544 -Node: Variable Scope572499 -Node: Pass By Value/Reference575487 -Node: Return Statement578997 -Node: Dynamic Typing581981 -Node: Indirect Calls582910 -Ref: Indirect Calls-Footnote-1592631 -Node: Functions Summary592759 -Node: Library Functions595458 -Ref: Library Functions-Footnote-1599076 -Ref: Library Functions-Footnote-2599219 -Node: Library Names599390 -Ref: Library Names-Footnote-1602850 -Ref: Library Names-Footnote-2603070 -Node: General Functions603156 -Node: Strtonum Function604184 -Node: Assert Function607204 -Node: Round Function610528 -Node: Cliff Random Function612069 -Node: Ordinal Functions613085 -Ref: Ordinal Functions-Footnote-1616150 -Ref: Ordinal Functions-Footnote-2616402 -Node: Join Function616613 -Ref: Join Function-Footnote-1618384 -Node: Getlocaltime Function618584 -Node: Readfile Function622325 -Node: Data File Management624273 -Node: Filetrans Function624905 -Node: Rewind Function628964 -Node: File Checking630349 -Ref: File Checking-Footnote-1631677 -Node: Empty Files631878 -Node: Ignoring Assigns633857 -Node: Getopt Function635408 -Ref: Getopt Function-Footnote-1646868 -Node: Passwd Functions647071 -Ref: Passwd Functions-Footnote-1655922 -Node: Group Functions656010 -Ref: Group Functions-Footnote-1663913 -Node: Walking Arrays664126 -Node: Library Functions Summary665729 -Node: Library Exercises667130 -Node: Sample Programs668410 -Node: Running Examples669180 -Node: Clones669908 -Node: Cut Program671132 -Node: Egrep Program680862 -Ref: Egrep Program-Footnote-1688366 -Node: Id Program688476 -Node: Split Program692120 -Ref: Split Program-Footnote-1695566 -Node: Tee Program695694 -Node: Uniq Program698481 -Node: Wc Program705902 -Ref: Wc Program-Footnote-1710150 -Node: Miscellaneous Programs710242 -Node: Dupword Program711455 -Node: Alarm Program713486 -Node: Translate Program718290 -Ref: Translate Program-Footnote-1722863 -Ref: Translate Program-Footnote-2723133 -Node: Labels Program723272 -Ref: Labels Program-Footnote-1726621 -Node: Word Sorting726705 -Node: History Sorting730775 -Node: Extract Program732611 -Node: Simple Sed740143 -Node: Igawk Program743205 -Ref: Igawk Program-Footnote-1757531 -Ref: Igawk Program-Footnote-2757732 -Ref: Igawk Program-Footnote-3757854 -Node: Anagram Program757969 -Node: Signature Program761031 -Node: Programs Summary762278 -Node: Programs Exercises763471 -Ref: Programs Exercises-Footnote-1767602 -Node: Advanced Features767693 -Node: Nondecimal Data769641 -Node: Array Sorting771231 -Node: Controlling Array Traversal771928 -Ref: Controlling Array Traversal-Footnote-1780259 -Node: Array Sorting Functions780377 -Ref: Array Sorting Functions-Footnote-1784269 -Node: Two-way I/O784463 -Ref: Two-way I/O-Footnote-1789407 -Ref: Two-way I/O-Footnote-2789593 -Node: TCP/IP Networking789675 -Node: Profiling792552 -Node: Advanced Features Summary800105 -Node: Internationalization802038 -Node: I18N and L10N803518 -Node: Explaining gettext804204 -Ref: Explaining gettext-Footnote-1809233 -Ref: Explaining gettext-Footnote-2809417 -Node: Programmer i18n809582 -Ref: Programmer i18n-Footnote-1814448 -Node: Translator i18n814497 -Node: String Extraction815291 -Ref: String Extraction-Footnote-1816422 -Node: Printf Ordering816508 -Ref: Printf Ordering-Footnote-1819294 -Node: I18N Portability819358 -Ref: I18N Portability-Footnote-1821807 -Node: I18N Example821870 -Ref: I18N Example-Footnote-1824670 -Node: Gawk I18N824742 -Node: I18N Summary825380 -Node: Debugger826719 -Node: Debugging827741 -Node: Debugging Concepts828182 -Node: Debugging Terms830039 -Node: Awk Debugging832614 -Node: Sample Debugging Session833506 -Node: Debugger Invocation834026 -Node: Finding The Bug835410 -Node: List of Debugger Commands841885 -Node: Breakpoint Control843217 -Node: Debugger Execution Control846909 -Node: Viewing And Changing Data850273 -Node: Execution Stack853638 -Node: Debugger Info855276 -Node: Miscellaneous Debugger Commands859293 -Node: Readline Support864485 -Node: Limitations865377 -Node: Debugging Summary867474 -Node: Arbitrary Precision Arithmetic868642 -Node: Computer Arithmetic870058 -Ref: table-numeric-ranges873659 -Ref: Computer Arithmetic-Footnote-1874518 -Node: Math Definitions874575 -Ref: table-ieee-formats877862 -Ref: Math Definitions-Footnote-1878466 -Node: MPFR features878571 -Node: FP Math Caution880240 -Ref: FP Math Caution-Footnote-1881290 -Node: Inexactness of computations881659 -Node: Inexact representation882607 -Node: Comparing FP Values883962 -Node: Errors accumulate885035 -Node: Getting Accuracy886468 -Node: Try To Round889127 -Node: Setting precision890026 -Ref: table-predefined-precision-strings890710 -Node: Setting the rounding mode892504 -Ref: table-gawk-rounding-modes892868 -Ref: Setting the rounding mode-Footnote-1896322 -Node: Arbitrary Precision Integers896501 -Ref: Arbitrary Precision Integers-Footnote-1900284 -Node: POSIX Floating Point Problems900433 -Ref: POSIX Floating Point Problems-Footnote-1904309 -Node: Floating point summary904347 -Node: Dynamic Extensions906539 -Node: Extension Intro908091 -Node: Plugin License909357 -Node: Extension Mechanism Outline910154 -Ref: figure-load-extension910582 -Ref: figure-register-new-function912062 -Ref: figure-call-new-function913066 -Node: Extension API Description915052 -Node: Extension API Functions Introduction916502 -Node: General Data Types921338 -Ref: General Data Types-Footnote-1927025 -Node: Memory Allocation Functions927324 -Ref: Memory Allocation Functions-Footnote-1930154 -Node: Constructor Functions930250 -Node: Registration Functions931984 -Node: Extension Functions932669 -Node: Exit Callback Functions934965 -Node: Extension Version String936213 -Node: Input Parsers936863 -Node: Output Wrappers946678 -Node: Two-way processors951194 -Node: Printing Messages953398 -Ref: Printing Messages-Footnote-1954475 -Node: Updating `ERRNO'954627 -Node: Requesting Values955367 -Ref: table-value-types-returned956095 -Node: Accessing Parameters957053 -Node: Symbol Table Access958284 -Node: Symbol table by name958798 -Node: Symbol table by cookie960778 -Ref: Symbol table by cookie-Footnote-1964917 -Node: Cached values964980 -Ref: Cached values-Footnote-1968484 -Node: Array Manipulation968575 -Ref: Array Manipulation-Footnote-1969673 -Node: Array Data Types969712 -Ref: Array Data Types-Footnote-1972369 -Node: Array Functions972461 -Node: Flattening Arrays976315 -Node: Creating Arrays983202 -Node: Extension API Variables987969 -Node: Extension Versioning988605 -Node: Extension API Informational Variables990506 -Node: Extension API Boilerplate991594 -Node: Finding Extensions995410 -Node: Extension Example995970 -Node: Internal File Description996742 -Node: Internal File Ops1000809 -Ref: Internal File Ops-Footnote-11012467 -Node: Using Internal File Ops1012607 -Ref: Using Internal File Ops-Footnote-11014990 -Node: Extension Samples1015263 -Node: Extension Sample File Functions1016787 -Node: Extension Sample Fnmatch1024389 -Node: Extension Sample Fork1025871 -Node: Extension Sample Inplace1027084 -Node: Extension Sample Ord1028759 -Node: Extension Sample Readdir1029595 -Ref: table-readdir-file-types1030451 -Node: Extension Sample Revout1031262 -Node: Extension Sample Rev2way1031853 -Node: Extension Sample Read write array1032594 -Node: Extension Sample Readfile1034533 -Node: Extension Sample Time1035628 -Node: Extension Sample API Tests1036977 -Node: gawkextlib1037468 -Node: Extension summary1040118 -Node: Extension Exercises1043800 -Node: Language History1044522 -Node: V7/SVR3.11046179 -Node: SVR41048360 -Node: POSIX1049805 -Node: BTL1051194 -Node: POSIX/GNU1051928 -Node: Feature History1057557 -Node: Common Extensions1070648 -Node: Ranges and Locales1071972 -Ref: Ranges and Locales-Footnote-11076611 -Ref: Ranges and Locales-Footnote-21076638 -Ref: Ranges and Locales-Footnote-31076872 -Node: Contributors1077093 -Node: History summary1082633 -Node: Installation1084002 -Node: Gawk Distribution1084958 -Node: Getting1085442 -Node: Extracting1086266 -Node: Distribution contents1087908 -Node: Unix Installation1093678 -Node: Quick Installation1094295 -Node: Additional Configuration Options1096726 -Node: Configuration Philosophy1098466 -Node: Non-Unix Installation1100817 -Node: PC Installation1101275 -Node: PC Binary Installation1102601 -Node: PC Compiling1104449 -Ref: PC Compiling-Footnote-11107470 -Node: PC Testing1107575 -Node: PC Using1108751 -Node: Cygwin1112866 -Node: MSYS1113689 -Node: VMS Installation1114187 -Node: VMS Compilation1114979 -Ref: VMS Compilation-Footnote-11116201 -Node: VMS Dynamic Extensions1116259 -Node: VMS Installation Details1117632 -Node: VMS Running1119884 -Node: VMS GNV1122725 -Node: VMS Old Gawk1123454 -Node: Bugs1123924 -Node: Other Versions1127888 -Node: Installation summary1134101 -Node: Notes1135157 -Node: Compatibility Mode1136022 -Node: Additions1136804 -Node: Accessing The Source1137729 -Node: Adding Code1139165 -Node: New Ports1145337 -Node: Derived Files1149818 -Ref: Derived Files-Footnote-11155293 -Ref: Derived Files-Footnote-21155327 -Ref: Derived Files-Footnote-31155923 -Node: Future Extensions1156037 -Node: Implementation Limitations1156643 -Node: Extension Design1157891 -Node: Old Extension Problems1159045 -Ref: Old Extension Problems-Footnote-11160562 -Node: Extension New Mechanism Goals1160619 -Ref: Extension New Mechanism Goals-Footnote-11163979 -Node: Extension Other Design Decisions1164168 -Node: Extension Future Growth1166276 -Node: Old Extension Mechanism1167112 -Node: Notes summary1168874 -Node: Basic Concepts1170060 -Node: Basic High Level1170741 -Ref: figure-general-flow1171013 -Ref: figure-process-flow1171612 -Ref: Basic High Level-Footnote-11174841 -Node: Basic Data Typing1175026 -Node: Glossary1178354 -Node: Copying1203512 -Node: GNU Free Documentation License1241068 -Node: Index1266204 +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-1129502 +Node: Other Arguments129527 +Node: Naming Standard Input132488 +Node: Environment Variables133581 +Node: AWKPATH Variable134139 +Ref: AWKPATH Variable-Footnote-1136991 +Ref: AWKPATH Variable-Footnote-2137036 +Node: AWKLIBPATH Variable137296 +Node: Other Environment Variables138055 +Node: Exit Status141528 +Node: Include Files142203 +Node: Loading Shared Libraries145781 +Node: Obsolete147208 +Node: Undocumented147905 +Node: Invoking Summary148172 +Node: Regexp149838 +Node: Regexp Usage151297 +Node: Escape Sequences153330 +Node: Regexp Operators159430 +Ref: Regexp Operators-Footnote-1166865 +Ref: Regexp Operators-Footnote-2167012 +Node: Bracket Expressions167110 +Ref: table-char-classes169127 +Node: Leftmost Longest172067 +Node: Computed Regexps173369 +Node: GNU Regexp Operators176766 +Node: Case-sensitivity180472 +Ref: Case-sensitivity-Footnote-1183362 +Ref: Case-sensitivity-Footnote-2183597 +Node: Regexp Summary183705 +Node: Reading Files185174 +Node: Records187268 +Node: awk split records188000 +Node: gawk split records192914 +Ref: gawk split records-Footnote-1197453 +Node: Fields197490 +Ref: Fields-Footnote-1200288 +Node: Nonconstant Fields200374 +Ref: Nonconstant Fields-Footnote-1202604 +Node: Changing Fields202806 +Node: Field Separators208738 +Node: Default Field Splitting211442 +Node: Regexp Field Splitting212559 +Node: Single Character Fields215909 +Node: Command Line Field Separator216968 +Node: Full Line Fields220180 +Ref: Full Line Fields-Footnote-1220688 +Node: Field Splitting Summary220734 +Ref: Field Splitting Summary-Footnote-1223865 +Node: Constant Size223966 +Node: Splitting By Content228572 +Ref: Splitting By Content-Footnote-1232645 +Node: Multiple Line232685 +Ref: Multiple Line-Footnote-1238574 +Node: Getline238753 +Node: Plain Getline240964 +Node: Getline/Variable243604 +Node: Getline/File244751 +Node: Getline/Variable/File246135 +Ref: Getline/Variable/File-Footnote-1247736 +Node: Getline/Pipe247823 +Node: Getline/Variable/Pipe250506 +Node: Getline/Coprocess251637 +Node: Getline/Variable/Coprocess252889 +Node: Getline Notes253628 +Node: Getline Summary256420 +Ref: table-getline-variants256832 +Node: Read Timeout257661 +Ref: Read Timeout-Footnote-1261475 +Node: Command-line directories261533 +Node: Input Summary262437 +Node: Input Exercises265689 +Node: Printing266417 +Node: Print268194 +Node: Print Examples269651 +Node: Output Separators272430 +Node: OFMT274448 +Node: Printf275802 +Node: Basic Printf276587 +Node: Control Letters278158 +Node: Format Modifiers282142 +Node: Printf Examples288149 +Node: Redirection290631 +Node: Special FD297470 +Ref: Special FD-Footnote-1300627 +Node: Special Files300701 +Node: Other Inherited Files301317 +Node: Special Network302317 +Node: Special Caveats303178 +Node: Close Files And Pipes304129 +Ref: Close Files And Pipes-Footnote-1311308 +Ref: Close Files And Pipes-Footnote-2311456 +Node: Output Summary311606 +Node: Output Exercises312602 +Node: Expressions313282 +Node: Values314467 +Node: Constants315143 +Node: Scalar Constants315823 +Ref: Scalar Constants-Footnote-1316682 +Node: Nondecimal-numbers316932 +Node: Regexp Constants319932 +Node: Using Constant Regexps320457 +Node: Variables323595 +Node: Using Variables324250 +Node: Assignment Options326160 +Node: Conversion328035 +Node: Strings And Numbers328559 +Ref: Strings And Numbers-Footnote-1331623 +Node: Locale influences conversions331732 +Ref: table-locale-affects334447 +Node: All Operators335035 +Node: Arithmetic Ops335665 +Node: Concatenation338170 +Ref: Concatenation-Footnote-1340989 +Node: Assignment Ops341095 +Ref: table-assign-ops346078 +Node: Increment Ops347356 +Node: Truth Values and Conditions350794 +Node: Truth Values351877 +Node: Typing and Comparison352926 +Node: Variable Typing353719 +Node: Comparison Operators357371 +Ref: table-relational-ops357781 +Node: POSIX String Comparison361296 +Ref: POSIX String Comparison-Footnote-1362368 +Node: Boolean Ops362506 +Ref: Boolean Ops-Footnote-1366985 +Node: Conditional Exp367076 +Node: Function Calls368803 +Node: Precedence372683 +Node: Locales376351 +Node: Expressions Summary377982 +Node: Patterns and Actions380556 +Node: Pattern Overview381676 +Node: Regexp Patterns383355 +Node: Expression Patterns383898 +Node: Ranges387678 +Node: BEGIN/END390784 +Node: Using BEGIN/END391546 +Ref: Using BEGIN/END-Footnote-1394283 +Node: I/O And BEGIN/END394389 +Node: BEGINFILE/ENDFILE396703 +Node: Empty399604 +Node: Using Shell Variables399921 +Node: Action Overview402197 +Node: Statements404524 +Node: If Statement406372 +Node: While Statement407870 +Node: Do Statement409898 +Node: For Statement411040 +Node: Switch Statement414195 +Node: Break Statement416583 +Node: Continue Statement418624 +Node: Next Statement420449 +Node: Nextfile Statement422829 +Node: Exit Statement425459 +Node: Built-in Variables427862 +Node: User-modified428995 +Ref: User-modified-Footnote-1436675 +Node: Auto-set436737 +Ref: Auto-set-Footnote-1449931 +Ref: Auto-set-Footnote-2450136 +Node: ARGC and ARGV450192 +Node: Pattern Action Summary454396 +Node: Arrays456823 +Node: Array Basics458152 +Node: Array Intro458996 +Ref: figure-array-elements460969 +Ref: Array Intro-Footnote-1463493 +Node: Reference to Elements463621 +Node: Assigning Elements466071 +Node: Array Example466562 +Node: Scanning an Array468320 +Node: Controlling Scanning471336 +Ref: Controlling Scanning-Footnote-1476525 +Node: Numeric Array Subscripts476841 +Node: Uninitialized Subscripts479026 +Node: Delete480643 +Ref: Delete-Footnote-1483387 +Node: Multidimensional483444 +Node: Multiscanning486539 +Node: Arrays of Arrays488128 +Node: Arrays Summary492889 +Node: Functions494994 +Node: Built-in495867 +Node: Calling Built-in496945 +Node: Numeric Functions498933 +Ref: Numeric Functions-Footnote-1503757 +Ref: Numeric Functions-Footnote-2504114 +Ref: Numeric Functions-Footnote-3504162 +Node: String Functions504431 +Ref: String Functions-Footnote-1527895 +Ref: String Functions-Footnote-2528024 +Ref: String Functions-Footnote-3528272 +Node: Gory Details528359 +Ref: table-sub-escapes530140 +Ref: table-sub-proposed531660 +Ref: table-posix-sub533024 +Ref: table-gensub-escapes534564 +Ref: Gory Details-Footnote-1535396 +Node: I/O Functions535547 +Ref: I/O Functions-Footnote-1542648 +Node: Time Functions542795 +Ref: Time Functions-Footnote-1553264 +Ref: Time Functions-Footnote-2553332 +Ref: Time Functions-Footnote-3553490 +Ref: Time Functions-Footnote-4553601 +Ref: Time Functions-Footnote-5553713 +Ref: Time Functions-Footnote-6553940 +Node: Bitwise Functions554206 +Ref: table-bitwise-ops554768 +Ref: Bitwise Functions-Footnote-1559076 +Node: Type Functions559245 +Node: I18N Functions560394 +Node: User-defined562039 +Node: Definition Syntax562843 +Ref: Definition Syntax-Footnote-1568249 +Node: Function Example568318 +Ref: Function Example-Footnote-1571235 +Node: Function Caveats571257 +Node: Calling A Function571775 +Node: Variable Scope572730 +Node: Pass By Value/Reference575718 +Node: Return Statement579228 +Node: Dynamic Typing582212 +Node: Indirect Calls583141 +Ref: Indirect Calls-Footnote-1594445 +Node: Functions Summary594573 +Node: Library Functions597272 +Ref: Library Functions-Footnote-1600890 +Ref: Library Functions-Footnote-2601033 +Node: Library Names601204 +Ref: Library Names-Footnote-1604664 +Ref: Library Names-Footnote-2604884 +Node: General Functions604970 +Node: Strtonum Function606073 +Node: Assert Function609093 +Node: Round Function612417 +Node: Cliff Random Function613958 +Node: Ordinal Functions614974 +Ref: Ordinal Functions-Footnote-1618039 +Ref: Ordinal Functions-Footnote-2618291 +Node: Join Function618502 +Ref: Join Function-Footnote-1620273 +Node: Getlocaltime Function620473 +Node: Readfile Function624214 +Node: Shell Quoting626184 +Node: Data File Management627585 +Node: Filetrans Function628217 +Node: Rewind Function632276 +Node: File Checking633661 +Ref: File Checking-Footnote-1634989 +Node: Empty Files635190 +Node: Ignoring Assigns637169 +Node: Getopt Function638720 +Ref: Getopt Function-Footnote-1650180 +Node: Passwd Functions650383 +Ref: Passwd Functions-Footnote-1659234 +Node: Group Functions659322 +Ref: Group Functions-Footnote-1667225 +Node: Walking Arrays667438 +Node: Library Functions Summary669041 +Node: Library Exercises670442 +Node: Sample Programs671722 +Node: Running Examples672492 +Node: Clones673220 +Node: Cut Program674444 +Node: Egrep Program684174 +Ref: Egrep Program-Footnote-1691678 +Node: Id Program691788 +Node: Split Program695432 +Ref: Split Program-Footnote-1698878 +Node: Tee Program699006 +Node: Uniq Program701793 +Node: Wc Program709214 +Ref: Wc Program-Footnote-1713462 +Node: Miscellaneous Programs713554 +Node: Dupword Program714767 +Node: Alarm Program716798 +Node: Translate Program721602 +Ref: Translate Program-Footnote-1726166 +Node: Labels Program726436 +Ref: Labels Program-Footnote-1729785 +Node: Word Sorting729869 +Node: History Sorting733939 +Node: Extract Program735775 +Node: Simple Sed743307 +Node: Igawk Program746369 +Ref: Igawk Program-Footnote-1760695 +Ref: Igawk Program-Footnote-2760896 +Ref: Igawk Program-Footnote-3761018 +Node: Anagram Program761133 +Node: Signature Program764195 +Node: Programs Summary765442 +Node: Programs Exercises766635 +Ref: Programs Exercises-Footnote-1770766 +Node: Advanced Features770857 +Node: Nondecimal Data772805 +Node: Array Sorting774395 +Node: Controlling Array Traversal775092 +Ref: Controlling Array Traversal-Footnote-1783423 +Node: Array Sorting Functions783541 +Ref: Array Sorting Functions-Footnote-1787433 +Node: Two-way I/O787627 +Ref: Two-way I/O-Footnote-1792571 +Ref: Two-way I/O-Footnote-2792757 +Node: TCP/IP Networking792839 +Node: Profiling795716 +Node: Advanced Features Summary803269 +Node: Internationalization805202 +Node: I18N and L10N806682 +Node: Explaining gettext807368 +Ref: Explaining gettext-Footnote-1812397 +Ref: Explaining gettext-Footnote-2812581 +Node: Programmer i18n812746 +Ref: Programmer i18n-Footnote-1817612 +Node: Translator i18n817661 +Node: String Extraction818455 +Ref: String Extraction-Footnote-1819586 +Node: Printf Ordering819672 +Ref: Printf Ordering-Footnote-1822458 +Node: I18N Portability822522 +Ref: I18N Portability-Footnote-1824971 +Node: I18N Example825034 +Ref: I18N Example-Footnote-1827834 +Node: Gawk I18N827906 +Node: I18N Summary828544 +Node: Debugger829883 +Node: Debugging830905 +Node: Debugging Concepts831346 +Node: Debugging Terms833203 +Node: Awk Debugging835778 +Node: Sample Debugging Session836670 +Node: Debugger Invocation837190 +Node: Finding The Bug838574 +Node: List of Debugger Commands845049 +Node: Breakpoint Control846381 +Node: Debugger Execution Control850073 +Node: Viewing And Changing Data853437 +Node: Execution Stack856802 +Node: Debugger Info858440 +Node: Miscellaneous Debugger Commands862457 +Node: Readline Support867649 +Node: Limitations868541 +Node: Debugging Summary870638 +Node: Arbitrary Precision Arithmetic871806 +Node: Computer Arithmetic873222 +Ref: table-numeric-ranges876823 +Ref: Computer Arithmetic-Footnote-1877682 +Node: Math Definitions877739 +Ref: table-ieee-formats881026 +Ref: Math Definitions-Footnote-1881630 +Node: MPFR features881735 +Node: FP Math Caution883404 +Ref: FP Math Caution-Footnote-1884454 +Node: Inexactness of computations884823 +Node: Inexact representation885771 +Node: Comparing FP Values887126 +Node: Errors accumulate888199 +Node: Getting Accuracy889632 +Node: Try To Round892291 +Node: Setting precision893190 +Ref: table-predefined-precision-strings893874 +Node: Setting the rounding mode895668 +Ref: table-gawk-rounding-modes896032 +Ref: Setting the rounding mode-Footnote-1899486 +Node: Arbitrary Precision Integers899665 +Ref: Arbitrary Precision Integers-Footnote-1903448 +Node: POSIX Floating Point Problems903597 +Ref: POSIX Floating Point Problems-Footnote-1907473 +Node: Floating point summary907511 +Node: Dynamic Extensions909703 +Node: Extension Intro911255 +Node: Plugin License912521 +Node: Extension Mechanism Outline913318 +Ref: figure-load-extension913746 +Ref: figure-register-new-function915226 +Ref: figure-call-new-function916230 +Node: Extension API Description918216 +Node: Extension API Functions Introduction919666 +Node: General Data Types924502 +Ref: General Data Types-Footnote-1930189 +Node: Memory Allocation Functions930488 +Ref: Memory Allocation Functions-Footnote-1933318 +Node: Constructor Functions933414 +Node: Registration Functions935148 +Node: Extension Functions935833 +Node: Exit Callback Functions938129 +Node: Extension Version String939377 +Node: Input Parsers940027 +Node: Output Wrappers949842 +Node: Two-way processors954358 +Node: Printing Messages956562 +Ref: Printing Messages-Footnote-1957639 +Node: Updating `ERRNO'957791 +Node: Requesting Values958531 +Ref: table-value-types-returned959259 +Node: Accessing Parameters960217 +Node: Symbol Table Access961448 +Node: Symbol table by name961962 +Node: Symbol table by cookie963942 +Ref: Symbol table by cookie-Footnote-1968081 +Node: Cached values968144 +Ref: Cached values-Footnote-1971648 +Node: Array Manipulation971739 +Ref: Array Manipulation-Footnote-1972837 +Node: Array Data Types972876 +Ref: Array Data Types-Footnote-1975533 +Node: Array Functions975625 +Node: Flattening Arrays979479 +Node: Creating Arrays986366 +Node: Extension API Variables991133 +Node: Extension Versioning991769 +Node: Extension API Informational Variables993670 +Node: Extension API Boilerplate994758 +Node: Finding Extensions998574 +Node: Extension Example999134 +Node: Internal File Description999906 +Node: Internal File Ops1003973 +Ref: Internal File Ops-Footnote-11015631 +Node: Using Internal File Ops1015771 +Ref: Using Internal File Ops-Footnote-11018154 +Node: Extension Samples1018427 +Node: Extension Sample File Functions1019951 +Node: Extension Sample Fnmatch1027553 +Node: Extension Sample Fork1029035 +Node: Extension Sample Inplace1030248 +Node: Extension Sample Ord1031923 +Node: Extension Sample Readdir1032759 +Ref: table-readdir-file-types1033615 +Node: Extension Sample Revout1034426 +Node: Extension Sample Rev2way1035017 +Node: Extension Sample Read write array1035758 +Node: Extension Sample Readfile1037697 +Node: Extension Sample Time1038792 +Node: Extension Sample API Tests1040141 +Node: gawkextlib1040632 +Node: Extension summary1043282 +Node: Extension Exercises1046964 +Node: Language History1047686 +Node: V7/SVR3.11049343 +Node: SVR41051524 +Node: POSIX1052969 +Node: BTL1054358 +Node: POSIX/GNU1055092 +Node: Feature History1060721 +Node: Common Extensions1073812 +Node: Ranges and Locales1075136 +Ref: Ranges and Locales-Footnote-11079775 +Ref: Ranges and Locales-Footnote-21079802 +Ref: Ranges and Locales-Footnote-31080036 +Node: Contributors1080257 +Node: History summary1085797 +Node: Installation1087166 +Node: Gawk Distribution1088122 +Node: Getting1088606 +Node: Extracting1089430 +Node: Distribution contents1091072 +Node: Unix Installation1096842 +Node: Quick Installation1097459 +Node: Additional Configuration Options1099890 +Node: Configuration Philosophy1101630 +Node: Non-Unix Installation1103981 +Node: PC Installation1104439 +Node: PC Binary Installation1105765 +Node: PC Compiling1107613 +Ref: PC Compiling-Footnote-11110634 +Node: PC Testing1110739 +Node: PC Using1111915 +Node: Cygwin1116030 +Node: MSYS1116853 +Node: VMS Installation1117351 +Node: VMS Compilation1118143 +Ref: VMS Compilation-Footnote-11119365 +Node: VMS Dynamic Extensions1119423 +Node: VMS Installation Details1121107 +Node: VMS Running1123359 +Node: VMS GNV1126200 +Node: VMS Old Gawk1126929 +Node: Bugs1127399 +Node: Other Versions1131369 +Node: Installation summary1137582 +Node: Notes1138638 +Node: Compatibility Mode1139503 +Node: Additions1140285 +Node: Accessing The Source1141210 +Node: Adding Code1142646 +Node: New Ports1148818 +Node: Derived Files1153299 +Ref: Derived Files-Footnote-11158774 +Ref: Derived Files-Footnote-21158808 +Ref: Derived Files-Footnote-31159404 +Node: Future Extensions1159518 +Node: Implementation Limitations1160124 +Node: Extension Design1161372 +Node: Old Extension Problems1162526 +Ref: Old Extension Problems-Footnote-11164043 +Node: Extension New Mechanism Goals1164100 +Ref: Extension New Mechanism Goals-Footnote-11167460 +Node: Extension Other Design Decisions1167649 +Node: Extension Future Growth1169757 +Node: Old Extension Mechanism1170593 +Node: Notes summary1172355 +Node: Basic Concepts1173541 +Node: Basic High Level1174222 +Ref: figure-general-flow1174494 +Ref: figure-process-flow1175093 +Ref: Basic High Level-Footnote-11178322 +Node: Basic Data Typing1178507 +Node: Glossary1181835 +Node: Copying1206993 +Node: GNU Free Documentation License1244549 +Node: Index1269685 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index ac34949a..ebaafbf3 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 @@ -9787,6 +9789,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 @@ -9818,6 +9823,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 @@ -20250,6 +20258,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 @@ -20578,6 +20649,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 @@ -21285,6 +21357,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 @@ -22824,12 +22974,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 @@ -24845,8 +24995,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 @@ -24854,15 +25004,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 @@ -24881,7 +25028,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. @@ -37754,7 +37901,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) @@ -37770,6 +37917,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 @@ -37994,8 +38146,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! @@ -38013,7 +38165,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 2ce4bb87..96c0a76c 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 @@ -9382,6 +9384,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 @@ -19376,6 +19381,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 @@ -19704,6 +19772,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 @@ -20411,6 +20480,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 @@ -21921,12 +22068,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 @@ -23942,8 +24089,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 @@ -23951,15 +24098,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 @@ -23978,7 +24122,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. @@ -36851,7 +36995,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) @@ -36867,6 +37011,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 @@ -37091,8 +37240,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! @@ -37110,7 +37259,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 |