diff options
| -rw-r--r-- | doc/gawk.info | 912 | ||||
| -rw-r--r-- | doc/gawk.texi | 59 |
2 files changed, 488 insertions, 483 deletions
diff --git a/doc/gawk.info b/doc/gawk.info index 05170d45..df7d4929 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -548,7 +548,7 @@ version of new `awk' written by David Trueman and Arnold, and available under the GNU General Public License. (Incidentally, it's no longer difficult to find a new `awk'. `gawk' -ships with Linux, and you can download binaries or source code for +ships with GNU/Linux, and you can download binaries or source code for almost any system; my wife uses `gawk' on her VMS box.) My Unix system started out unplugged from the wall; it certainly was @@ -2659,20 +2659,19 @@ File: gawk.info, Node: Include Files, Next: Obsolete, Prev: Exit Status, Up: 2.7 Including Other Files Into Your Program =========================================== -*FIXME:* This section still needs some editing. +This minor node describes a feature that is specific to `gawk'. - The `@include' keyword can be used to read external source `awk' -files. That gives the ability to split large `awk' source files into -smaller, more manageable pieces, and also lets you reuse common `awk' -code from various `awk' scripts. In other words, you can group -together `awk' functions, used to carry out specific tasks, in external -files. These files can be used just like function libraries, using the -`@include' keyword in conjuction with the `AWKPATH' environment -variable. + The `@include' keyword can be used to read external `awk' source +files. This gives you the ability to split large `awk' source files +into smaller, more manageable pieces, and also lets you reuse common +`awk' code from various `awk' scripts. In other words, you can group +together `awk' functions, used to carry out specific tasks, into +external files. These files can be used just like function libraries, +using the `@include' keyword in conjuction with the `AWKPATH' +environment variable. - Let's see an example to demonstrate file inclusion in `gawk'. To do -so, we'll use two (trivial) `awk' scripts, namely `test1' and `test2'. -Here is the `test1' script: + Let's see an example. We'll start with two (trivial) `awk' scripts, +namely `test1' and `test2'. Here is the `test1' script: BEGIN { print "This is script test1." @@ -2691,16 +2690,16 @@ and here is `test2': -| This is file test1. -| This is file test2. - `gawk' runs the `test2' script where `test1' has been included in -the source of `test2' by means of the `@include' keyword. So, to -include external `awk' source files you just use `@include' followed by -the name of the file to be included, enclosed in double quotes. + `gawk' runs the `test2' script which includes `test1' using the +`@include' keyword. So, to include external `awk' source files you just +use `@include' followed by the name of the file to be included, +enclosed in double quotes. NOTE: Keep in mind that this is a language construct and the file name cannot be a string variable, but rather just a literal string in double quotes. - The files to be included may be nested; e.g. given a third script, + The files to be included may be nested; e.g., given a third script, namely `test3': @include "test2" @@ -2708,42 +2707,44 @@ namely `test3': print "This is script test3." } -and running `gawk' with the `test3' script you'll get the following -result: +Running `gawk' with the `test3' script produces the following results: $ gawk -f test3 -| This is file test1. -| This is file test2. -| This is file test3. - The file name can, of course, be a pathname, e.g. + The file name can, of course, be a pathname. For example: @include "../io_funcs" -or +or: @include "/usr/awklib/network" are valid. The `AWKPATH' environment variable can be of great value when using `@include'. The same rules for the use of the `AWKPATH' -variable in command line file searches apply to `@include' also. This -is very helpful in constructing `gawk' function libraries. You can -edit huge scripts containing useful `gawk' libraries and put those -files in a special directory. You can then include those "libraries" -using either the full pathnames of the files or by setting the -`AWKPATH' environment variable accordingly and then using `@include' -with just the name part of the full file pathname. Of course you can -have more than one directory to keep library files; the more complex -the working enviroment is, the more directories you may need to organize -the files to be included. +variable in command line file searches (*note AWKPATH Variable::) apply +to `@include' also. + + This is very helpful in constructing `gawk' function libraries. If +you have a large script with useful, general purpose `awk' functions, +you can break it down into library files and put those files in a +special directory. You can then include those "libraries," using +either the full pathnames of the files, or by setting the `AWKPATH' +environment variable accordingly and then using `@include' with just +the file part of the full pathname. Of course you can have more than +one directory to keep library files; the more complex the working +enviroment is, the more directories you may need to organize the files +to be included. Given the ability to specify multiple `-f' options, the `@include' mechanism is not strictly necessary. However, the `@include' keyword can help you in constructing self-contained `gawk' programs, thus -reducing the need of writing complex and tedious command lines. +reducing the need for writing complex and tedious command lines. As mentioned in *note AWKPATH Variable::, the current directory is -always search first for source files, before searching in `AWKPATH', +always searched first for source files, before searching in `AWKPATH', and this also applies to files named with `@include'. @@ -22775,12 +22776,13 @@ GNU GNU/Linux A variant of the GNU system using the Linux kernel, instead of the - Free Software Foundation's Hurd kernel. Linux is a stable, - efficient, full-featured clone of Unix that has been ported to a - variety of architectures. It is most popular on PC-class systems, - but runs well on a variety of other systems too. The Linux kernel - source code is available under the terms of the GNU General Public - License, which is perhaps its most important aspect. + Free Software Foundation's Hurd kernel. The Linux kernel is a + stable, efficient, full-featured clone of Unix that has been + ported to a variety of architectures. It is most popular on + PC-class systems, but runs well on a variety of other systems too. + The Linux kernel source code is available under the terms of the + GNU General Public License, which is perhaps its most important + aspect. GPL See "General Public License." @@ -25009,7 +25011,7 @@ Index * Brennan, Michael: Delete. (line 51) * Broder, Alan J.: Contributors. (line 80) * Brown, Martin: Contributors. (line 75) -* BSD-based operating systems: Glossary. (line 582) +* BSD-based operating systems: Glossary. (line 583) * bt debugger command (alias for backtrace): Dgawk Stack. (line 13) * Buening, Andreas <1>: Bugs. (line 70) * Buening, Andreas <2>: Contributors. (line 84) @@ -25688,7 +25690,7 @@ Index * Free Software Foundation (FSF) <1>: Glossary. (line 286) * Free Software Foundation (FSF) <2>: Getting. (line 10) * Free Software Foundation (FSF): Manual History. (line 6) -* FreeBSD: Glossary. (line 582) +* FreeBSD: Glossary. (line 583) * FS variable <1>: User-modified. (line 56) * FS variable: Field Separators. (line 14) * FS variable, --field-separator option and: Options. (line 21) @@ -25876,13 +25878,13 @@ Index * GNU Free Documentation License: GNU Free Documentation License. (line 6) * GNU General Public License: Glossary. (line 295) -* GNU Lesser General Public License: Glossary. (line 373) +* GNU Lesser General Public License: Glossary. (line 374) * GNU long options <1>: Options. (line 6) * GNU long options: Command Line. (line 13) * GNU long options, printing list of: Options. (line 142) * GNU Project <1>: Glossary. (line 304) * GNU Project: Manual History. (line 11) -* GNU/Linux <1>: Glossary. (line 582) +* GNU/Linux <1>: Glossary. (line 583) * GNU/Linux <2>: Atari Compiling. (line 16) * GNU/Linux <3>: I18N Example. (line 55) * GNU/Linux: Manual History. (line 28) @@ -26001,13 +26003,13 @@ Index * internationalization, localization, portability and: I18N Portability. (line 6) * internationalizing a program: Explaining gettext. (line 6) -* interpreted programs <1>: Glossary. (line 344) +* interpreted programs <1>: Glossary. (line 345) * interpreted programs: Basic High Level. (line 15) * interval expressions: Regexp Operators. (line 115) * inventory-shipped file: Sample Data Files. (line 32) * IOBUF internal structure: Internals. (line 162) * iop_alloc internal function: Internals. (line 162) -* ISO: Glossary. (line 355) +* ISO: Glossary. (line 356) * ISO 8859-1: Glossary. (line 137) * ISO Latin-1: Glossary. (line 137) * Jacobs, Andrew: Passwd Functions. (line 90) @@ -26056,8 +26058,8 @@ Index * left shift, bitwise: Bitwise Functions. (line 32) * leftmost longest match: Multiple Line. (line 26) * length() function: String Functions. (line 137) -* Lesser General Public License (LGPL): Glossary. (line 373) -* LGPL (Lesser General Public License): Glossary. (line 373) +* Lesser General Public License (LGPL): Glossary. (line 374) +* LGPL (Lesser General Public License): Glossary. (line 374) * libraries of awk functions: Library Functions. (line 6) * libraries of awk functions, assertions: Assert Function. (line 6) * libraries of awk functions, associative arrays and: Library Names. @@ -26103,7 +26105,7 @@ Index * lint checking, undefined functions: Pass By Value/Reference. (line 88) * LINT variable: User-modified. (line 98) -* Linux <1>: Glossary. (line 582) +* Linux <1>: Glossary. (line 583) * Linux <2>: Atari Compiling. (line 16) * Linux <3>: I18N Example. (line 55) * Linux: Manual History. (line 28) @@ -26175,7 +26177,7 @@ Index * nargs internal variable: Internals. (line 46) * nawk utility: Names. (line 17) * negative zero: Unexpected Results. (line 28) -* NetBSD: Glossary. (line 582) +* NetBSD: Glossary. (line 583) * networks, programming: TCP/IP Networking. (line 6) * networks, support for: Special Network. (line 6) * newlines <1>: Boolean Ops. (line 67) @@ -26266,7 +26268,7 @@ Index * OFS variable <1>: User-modified. (line 124) * OFS variable <2>: Output Separators. (line 6) * OFS variable: Changing Fields. (line 64) -* OpenBSD: Glossary. (line 582) +* OpenBSD: Glossary. (line 583) * OpenSolaris: Other Versions. (line 101) * operating systems, BSD-based: Manual History. (line 28) * operating systems, PC, gawk on: PC Using. (line 6) @@ -26335,7 +26337,7 @@ Index * output, standard: Special FD. (line 6) * p debugger command (alias for print): Viewing And Changing Data. (line 36) -* P1003.2 POSIX standard: Glossary. (line 426) +* P1003.2 POSIX standard: Glossary. (line 427) * parameters, number of: Internals. (line 46) * parentheses (): Regexp Operators. (line 78) * parentheses (), pgawk program: Profiling. (line 141) @@ -26957,7 +26959,7 @@ Index (line 6) * uniq utility: Uniq Program. (line 6) * uniq.awk program: Uniq Program. (line 65) -* Unix: Glossary. (line 582) +* Unix: Glossary. (line 583) * Unix awk, backslashes in escape sequences: Escape Sequences. (line 125) * Unix awk, close() function and: Close Files And Pipes. @@ -27095,407 +27097,407 @@ Index Tag Table: Node: Top1340 Node: Foreword30345 -Node: Preface34661 -Ref: Preface-Footnote-137613 -Ref: Preface-Footnote-237719 -Node: History37951 -Node: Names40183 -Ref: Names-Footnote-141660 -Node: This Manual41732 -Ref: This Manual-Footnote-146630 -Node: Conventions46730 -Node: Manual History48789 -Ref: Manual History-Footnote-151967 -Ref: Manual History-Footnote-252008 -Node: How To Contribute52082 -Node: Acknowledgments53226 -Node: Getting Started57495 -Node: Running gawk59874 -Node: One-shot61060 -Node: Read Terminal62285 -Ref: Read Terminal-Footnote-163935 -Ref: Read Terminal-Footnote-264209 -Node: Long64380 -Node: Executable Scripts65756 -Ref: Executable Scripts-Footnote-167617 -Ref: Executable Scripts-Footnote-267719 -Node: Comments68170 -Node: Quoting70538 -Node: DOS Quoting75155 -Node: Sample Data Files75823 -Node: Very Simple78855 -Node: Two Rules83452 -Node: More Complex85599 -Ref: More Complex-Footnote-188529 -Node: Statements/Lines88609 -Ref: Statements/Lines-Footnote-192967 -Node: Other Features93232 -Node: When94101 -Node: Invoking Gawk96244 -Node: Command Line97629 -Node: Options98412 -Ref: Options-Footnote-1111608 -Node: Other Arguments111633 -Node: Naming Standard Input114296 -Node: Environment Variables115260 -Node: AWKPATH Variable115704 -Ref: AWKPATH Variable-Footnote-1118441 -Node: Other Environment Variables118701 -Node: Exit Status121049 -Node: Include Files121724 -Node: Obsolete125086 -Node: Undocumented125772 -Node: Regexp126013 -Node: Regexp Usage127465 -Node: Escape Sequences129491 -Node: Regexp Operators135234 -Ref: Regexp Operators-Footnote-1142406 -Ref: Regexp Operators-Footnote-2142553 -Node: Character Lists142651 -Ref: table-char-classes144426 -Node: GNU Regexp Operators147051 -Node: Case-sensitivity150764 -Ref: Case-sensitivity-Footnote-1153719 -Ref: Case-sensitivity-Footnote-2153954 -Node: Leftmost Longest154062 -Node: Computed Regexps155263 -Node: Locales158680 -Node: Reading Files161770 -Node: Records163711 -Ref: Records-Footnote-1172277 -Node: Fields172314 -Ref: Fields-Footnote-1175346 -Node: Nonconstant Fields175432 -Node: Changing Fields177634 -Node: Field Separators182919 -Node: Default Field Splitting185548 -Node: Regexp Field Splitting186665 -Node: Single Character Fields190015 -Node: Command Line Field Separator191066 -Node: Field Splitting Summary194505 -Ref: Field Splitting Summary-Footnote-1197691 -Node: Constant Size197792 -Node: Splitting By Content202263 -Ref: Splitting By Content-Footnote-1205865 -Node: Multiple Line205905 -Ref: Multiple Line-Footnote-1211645 -Node: Getline211824 -Node: Plain Getline214052 -Node: Getline/Variable216141 -Node: Getline/File217282 -Node: Getline/Variable/File218604 -Ref: Getline/Variable/File-Footnote-1220203 -Node: Getline/Pipe220290 -Node: Getline/Variable/Pipe222838 -Node: Getline/Coprocess223945 -Node: Getline/Variable/Coprocess225188 -Node: Getline Notes225902 -Node: Getline Summary227844 -Ref: table-getline-variants228128 -Node: Command line directories229033 -Node: Printing229658 -Node: Print231289 -Node: Print Examples232626 -Node: Output Separators235410 -Node: OFMT237169 -Node: Printf238527 -Node: Basic Printf239433 -Node: Control Letters240970 -Node: Format Modifiers244782 -Node: Printf Examples250793 -Node: Redirection253508 -Node: Special Files260486 -Node: Special FD261019 -Ref: Special FD-Footnote-1264594 -Node: Special Network264668 -Node: Special Caveats265523 -Node: Close Files And Pipes266317 -Ref: Close Files And Pipes-Footnote-1273261 -Ref: Close Files And Pipes-Footnote-2273409 -Node: Expressions273559 -Node: Values274628 -Node: Constants275304 -Node: Scalar Constants275984 -Ref: Scalar Constants-Footnote-1276843 -Node: Nondecimal-numbers277025 -Node: Regexp Constants280084 -Node: Using Constant Regexps280559 -Node: Variables283564 -Node: Using Variables284219 -Node: Assignment Options285946 -Node: Conversion287827 -Ref: table-locale-affects293201 -Ref: Conversion-Footnote-1293825 -Node: All Operators293934 -Node: Arithmetic Ops294564 -Node: Concatenation297063 -Ref: Concatenation-Footnote-1299856 -Node: Assignment Ops299975 -Ref: table-assign-ops304963 -Node: Increment Ops306364 -Node: Truth Values and Conditions309842 -Node: Truth Values310925 -Node: Typing and Comparison311973 -Node: Variable Typing312762 -Ref: Variable Typing-Footnote-1316659 -Node: Comparison Operators316781 -Ref: table-relational-ops317191 -Node: POSIX String Comparison320740 -Ref: POSIX String Comparison-Footnote-1321697 -Node: Boolean Ops321835 -Ref: Boolean Ops-Footnote-1325913 -Node: Conditional Exp326004 -Node: Function Calls327736 -Node: Precedence331295 -Node: Patterns and Actions334948 -Node: Pattern Overview336002 -Node: Regexp Patterns337668 -Node: Expression Patterns338211 -Node: Ranges341785 -Node: BEGIN/END344751 -Node: Using BEGIN/END345501 -Ref: Using BEGIN/END-Footnote-1348232 -Node: I/O And BEGIN/END348346 -Node: Empty350615 -Node: BEGINFILE/ENDFILE350949 -Node: Using Shell Variables353774 -Node: Action Overview356053 -Node: Statements358410 -Node: If Statement360269 -Node: While Statement361768 -Node: Do Statement363812 -Node: For Statement364968 -Node: Switch Statement368120 -Node: Break Statement370217 -Node: Continue Statement372193 -Node: Next Statement373894 -Node: Nextfile Statement376276 -Node: Exit Statement378794 -Node: Built-in Variables381125 -Node: User-modified382220 -Ref: User-modified-Footnote-1390221 -Node: Auto-set390283 -Ref: Auto-set-Footnote-1399074 -Node: ARGC and ARGV399279 -Node: Arrays403038 -Node: Array Basics404609 -Node: Array Intro405320 -Node: Reference to Elements409638 -Node: Assigning Elements411908 -Node: Array Example412399 -Node: Scanning an Array414131 -Node: Delete416408 -Ref: Delete-Footnote-1418806 -Node: Numeric Array Subscripts418863 -Node: Uninitialized Subscripts421046 -Node: Multi-dimensional422674 -Node: Multi-scanning425765 -Node: Array Sorting427349 -Ref: Array Sorting-Footnote-1430547 -Node: Arrays of Arrays430741 -Node: Functions434849 -Node: Built-in435671 -Node: Calling Built-in436685 -Node: Numeric Functions438661 -Ref: Numeric Functions-Footnote-1442370 -Ref: Numeric Functions-Footnote-2442706 -Ref: Numeric Functions-Footnote-3442754 -Node: String Functions443023 -Ref: String Functions-Footnote-1464822 -Ref: String Functions-Footnote-2464951 -Ref: String Functions-Footnote-3465199 -Node: Gory Details465286 -Ref: table-sub-escapes466943 -Ref: table-posix-sub468257 -Ref: table-gensub-escapes469157 -Node: I/O Functions470328 -Ref: I/O Functions-Footnote-1477025 -Node: Time Functions477172 -Ref: Time Functions-Footnote-1487828 -Ref: Time Functions-Footnote-2487896 -Ref: Time Functions-Footnote-3488054 -Ref: Time Functions-Footnote-4488165 -Ref: Time Functions-Footnote-5488277 -Ref: Time Functions-Footnote-6488504 -Node: Bitwise Functions488770 -Ref: table-bitwise-ops489328 -Ref: Bitwise Functions-Footnote-1493488 -Node: I18N Functions493672 -Node: User-defined495302 -Node: Definition Syntax496106 -Ref: Definition Syntax-Footnote-1500736 -Node: Function Example500805 -Node: Function Caveats503399 -Node: Calling A Function503820 -Node: Variable Scope504909 -Node: Pass By Value/Reference506837 -Node: Return Statement510277 -Node: Dynamic Typing513219 -Node: Indirect Calls513956 -Node: Internationalization523641 -Node: I18N and L10N525069 -Node: Explaining gettext525755 -Ref: Explaining gettext-Footnote-1530817 -Ref: Explaining gettext-Footnote-2531000 -Node: Programmer i18n531165 -Node: Translator i18n535428 -Node: String Extraction536221 -Ref: String Extraction-Footnote-1537182 -Node: Printf Ordering537268 -Ref: Printf Ordering-Footnote-1540052 -Node: I18N Portability540116 -Ref: I18N Portability-Footnote-1542565 -Node: I18N Example542628 -Ref: I18N Example-Footnote-1545263 -Node: Gawk I18N545335 -Node: Advanced Features545904 -Node: Nondecimal Data547223 -Node: Two-way I/O548784 -Ref: Two-way I/O-Footnote-1554198 -Node: TCP/IP Networking554275 -Node: Profiling557128 -Node: Library Functions564528 -Ref: Library Functions-Footnote-1567498 -Node: Library Names567669 -Ref: Library Names-Footnote-1571140 -Ref: Library Names-Footnote-2571360 -Node: General Functions571446 -Node: Nextfile Function572509 -Node: Strtonum Function576890 -Node: Assert Function579841 -Node: Round Function583167 -Node: Cliff Random Function584708 -Node: Ordinal Functions585724 -Ref: Ordinal Functions-Footnote-1588794 -Ref: Ordinal Functions-Footnote-2589046 -Node: Join Function589262 -Ref: Join Function-Footnote-1591033 -Node: Gettimeofday Function591233 -Node: Data File Management594948 -Node: Filetrans Function595580 -Node: Rewind Function599817 -Node: File Checking601270 -Node: Empty Files602364 -Node: Ignoring Assigns604594 -Node: Getopt Function606147 -Ref: Getopt Function-Footnote-1617472 -Node: Passwd Functions617675 -Ref: Passwd Functions-Footnote-1626663 -Node: Group Functions626751 -Node: Sample Programs634831 -Node: Running Examples635500 -Node: Clones636228 -Node: Cut Program637360 -Node: Egrep Program647127 -Ref: Egrep Program-Footnote-1654881 -Node: Id Program654991 -Node: Split Program658598 -Node: Tee Program662066 -Node: Uniq Program664809 -Node: Wc Program672186 -Ref: Wc Program-Footnote-1676432 -Node: Miscellaneous Programs676628 -Node: Dupword Program677748 -Node: Alarm Program679779 -Node: Translate Program684323 -Ref: Translate Program-Footnote-1688702 -Ref: Translate Program-Footnote-2688939 -Node: Labels Program689073 -Ref: Labels Program-Footnote-1692364 -Node: Word Sorting692448 -Node: History Sorting696795 -Node: Extract Program698633 -Node: Simple Sed705996 -Node: Igawk Program709053 -Ref: Igawk Program-Footnote-1723788 -Ref: Igawk Program-Footnote-2723989 -Node: Signature Program724127 -Node: Debugger725207 -Node: Debugging726083 -Node: Debugging Concepts726397 -Node: Debugging Terms728250 -Node: Awk Debugging730798 -Node: Sample dgawk session731690 -Node: dgawk invocation732182 -Node: Finding The Bug733366 -Node: List of Debugger Commands739881 -Node: Breakpoint Control741196 -Node: Dgawk Execution Control744406 -Node: Viewing And Changing Data747755 -Node: Dgawk Stack751051 -Node: Dgawk Info752512 -Node: Miscellaneous Dgawk Commands756450 -Node: Readline Support762166 -Node: Dgawk Limitations762982 -Node: Language History765154 -Node: V7/SVR3.1766531 -Node: SVR4768826 -Node: POSIX770271 -Node: BTL771983 -Node: POSIX/GNU773673 -Node: Contributors783337 -Node: Installation786946 -Node: Gawk Distribution787917 -Node: Getting788401 -Node: Extracting789227 -Node: Distribution contents790615 -Node: Unix Installation795688 -Node: Quick Installation796279 -Node: Additional Configuration Options797981 -Node: Configuration Philosophy799744 -Node: Non-Unix Installation802108 -Node: PC Installation802573 -Node: PC Binary Installation803879 -Node: PC Compiling805722 -Node: PC Dynamic810227 -Node: PC Using812590 -Node: Cygwin817138 -Node: MSYS818122 -Node: VMS Installation818628 -Node: VMS Compilation819232 -Node: VMS Installation Details820809 -Node: VMS Running822439 -Node: VMS POSIX824036 -Node: VMS Old Gawk825334 -Node: Unsupported825803 -Node: Atari Installation826265 -Node: Atari Compiling827552 -Node: Atari Using829441 -Node: BeOS Installation832288 -Node: Tandem Installation833433 -Node: Bugs835112 -Node: Other Versions838944 -Node: Notes844166 -Node: Compatibility Mode844858 -Node: Additions845641 -Node: Adding Code846391 -Node: New Ports852443 -Node: Dynamic Extensions856575 -Node: Internals857956 -Node: Plugin License868361 -Node: Sample Library868995 -Node: Internal File Description869659 -Node: Internal File Ops873354 -Ref: Internal File Ops-Footnote-1878230 -Node: Using Internal File Ops878378 -Node: Future Extensions880403 -Node: Basic Concepts884440 -Node: Basic High Level885197 -Ref: Basic High Level-Footnote-1889316 -Node: Basic Data Typing889510 -Node: Floating Point Issues893947 -Node: String Conversion Precision895030 -Ref: String Conversion Precision-Footnote-1896724 -Node: Unexpected Results896833 -Node: POSIX Floating Point Problems898659 -Ref: POSIX Floating Point Problems-Footnote-1902358 -Node: Glossary902396 -Node: Copying926164 -Node: GNU Free Documentation License963721 -Node: next-edition988865 -Node: unresolved989217 -Node: revision989717 -Node: consistency990140 -Node: Index993493 +Node: Preface34665 +Ref: Preface-Footnote-137617 +Ref: Preface-Footnote-237723 +Node: History37955 +Node: Names40187 +Ref: Names-Footnote-141664 +Node: This Manual41736 +Ref: This Manual-Footnote-146634 +Node: Conventions46734 +Node: Manual History48793 +Ref: Manual History-Footnote-151971 +Ref: Manual History-Footnote-252012 +Node: How To Contribute52086 +Node: Acknowledgments53230 +Node: Getting Started57499 +Node: Running gawk59878 +Node: One-shot61064 +Node: Read Terminal62289 +Ref: Read Terminal-Footnote-163939 +Ref: Read Terminal-Footnote-264213 +Node: Long64384 +Node: Executable Scripts65760 +Ref: Executable Scripts-Footnote-167621 +Ref: Executable Scripts-Footnote-267723 +Node: Comments68174 +Node: Quoting70542 +Node: DOS Quoting75159 +Node: Sample Data Files75827 +Node: Very Simple78859 +Node: Two Rules83456 +Node: More Complex85603 +Ref: More Complex-Footnote-188533 +Node: Statements/Lines88613 +Ref: Statements/Lines-Footnote-192971 +Node: Other Features93236 +Node: When94105 +Node: Invoking Gawk96248 +Node: Command Line97633 +Node: Options98416 +Ref: Options-Footnote-1111612 +Node: Other Arguments111637 +Node: Naming Standard Input114300 +Node: Environment Variables115264 +Node: AWKPATH Variable115708 +Ref: AWKPATH Variable-Footnote-1118445 +Node: Other Environment Variables118705 +Node: Exit Status121053 +Node: Include Files121728 +Node: Obsolete125119 +Node: Undocumented125805 +Node: Regexp126046 +Node: Regexp Usage127498 +Node: Escape Sequences129524 +Node: Regexp Operators135267 +Ref: Regexp Operators-Footnote-1142439 +Ref: Regexp Operators-Footnote-2142586 +Node: Character Lists142684 +Ref: table-char-classes144459 +Node: GNU Regexp Operators147084 +Node: Case-sensitivity150797 +Ref: Case-sensitivity-Footnote-1153752 +Ref: Case-sensitivity-Footnote-2153987 +Node: Leftmost Longest154095 +Node: Computed Regexps155296 +Node: Locales158713 +Node: Reading Files161803 +Node: Records163744 +Ref: Records-Footnote-1172310 +Node: Fields172347 +Ref: Fields-Footnote-1175379 +Node: Nonconstant Fields175465 +Node: Changing Fields177667 +Node: Field Separators182952 +Node: Default Field Splitting185581 +Node: Regexp Field Splitting186698 +Node: Single Character Fields190048 +Node: Command Line Field Separator191099 +Node: Field Splitting Summary194538 +Ref: Field Splitting Summary-Footnote-1197724 +Node: Constant Size197825 +Node: Splitting By Content202296 +Ref: Splitting By Content-Footnote-1205898 +Node: Multiple Line205938 +Ref: Multiple Line-Footnote-1211678 +Node: Getline211857 +Node: Plain Getline214085 +Node: Getline/Variable216174 +Node: Getline/File217315 +Node: Getline/Variable/File218637 +Ref: Getline/Variable/File-Footnote-1220236 +Node: Getline/Pipe220323 +Node: Getline/Variable/Pipe222871 +Node: Getline/Coprocess223978 +Node: Getline/Variable/Coprocess225221 +Node: Getline Notes225935 +Node: Getline Summary227877 +Ref: table-getline-variants228161 +Node: Command line directories229066 +Node: Printing229691 +Node: Print231322 +Node: Print Examples232659 +Node: Output Separators235443 +Node: OFMT237202 +Node: Printf238560 +Node: Basic Printf239466 +Node: Control Letters241003 +Node: Format Modifiers244815 +Node: Printf Examples250826 +Node: Redirection253541 +Node: Special Files260519 +Node: Special FD261052 +Ref: Special FD-Footnote-1264627 +Node: Special Network264701 +Node: Special Caveats265556 +Node: Close Files And Pipes266350 +Ref: Close Files And Pipes-Footnote-1273294 +Ref: Close Files And Pipes-Footnote-2273442 +Node: Expressions273592 +Node: Values274661 +Node: Constants275337 +Node: Scalar Constants276017 +Ref: Scalar Constants-Footnote-1276876 +Node: Nondecimal-numbers277058 +Node: Regexp Constants280117 +Node: Using Constant Regexps280592 +Node: Variables283597 +Node: Using Variables284252 +Node: Assignment Options285979 +Node: Conversion287860 +Ref: table-locale-affects293234 +Ref: Conversion-Footnote-1293858 +Node: All Operators293967 +Node: Arithmetic Ops294597 +Node: Concatenation297096 +Ref: Concatenation-Footnote-1299889 +Node: Assignment Ops300008 +Ref: table-assign-ops304996 +Node: Increment Ops306397 +Node: Truth Values and Conditions309875 +Node: Truth Values310958 +Node: Typing and Comparison312006 +Node: Variable Typing312795 +Ref: Variable Typing-Footnote-1316692 +Node: Comparison Operators316814 +Ref: table-relational-ops317224 +Node: POSIX String Comparison320773 +Ref: POSIX String Comparison-Footnote-1321730 +Node: Boolean Ops321868 +Ref: Boolean Ops-Footnote-1325946 +Node: Conditional Exp326037 +Node: Function Calls327769 +Node: Precedence331328 +Node: Patterns and Actions334981 +Node: Pattern Overview336035 +Node: Regexp Patterns337701 +Node: Expression Patterns338244 +Node: Ranges341818 +Node: BEGIN/END344784 +Node: Using BEGIN/END345534 +Ref: Using BEGIN/END-Footnote-1348265 +Node: I/O And BEGIN/END348379 +Node: Empty350648 +Node: BEGINFILE/ENDFILE350982 +Node: Using Shell Variables353807 +Node: Action Overview356086 +Node: Statements358443 +Node: If Statement360302 +Node: While Statement361801 +Node: Do Statement363845 +Node: For Statement365001 +Node: Switch Statement368153 +Node: Break Statement370250 +Node: Continue Statement372226 +Node: Next Statement373927 +Node: Nextfile Statement376309 +Node: Exit Statement378827 +Node: Built-in Variables381158 +Node: User-modified382253 +Ref: User-modified-Footnote-1390254 +Node: Auto-set390316 +Ref: Auto-set-Footnote-1399107 +Node: ARGC and ARGV399312 +Node: Arrays403071 +Node: Array Basics404642 +Node: Array Intro405353 +Node: Reference to Elements409671 +Node: Assigning Elements411941 +Node: Array Example412432 +Node: Scanning an Array414164 +Node: Delete416441 +Ref: Delete-Footnote-1418839 +Node: Numeric Array Subscripts418896 +Node: Uninitialized Subscripts421079 +Node: Multi-dimensional422707 +Node: Multi-scanning425798 +Node: Array Sorting427382 +Ref: Array Sorting-Footnote-1430580 +Node: Arrays of Arrays430774 +Node: Functions434882 +Node: Built-in435704 +Node: Calling Built-in436718 +Node: Numeric Functions438694 +Ref: Numeric Functions-Footnote-1442403 +Ref: Numeric Functions-Footnote-2442739 +Ref: Numeric Functions-Footnote-3442787 +Node: String Functions443056 +Ref: String Functions-Footnote-1464855 +Ref: String Functions-Footnote-2464984 +Ref: String Functions-Footnote-3465232 +Node: Gory Details465319 +Ref: table-sub-escapes466976 +Ref: table-posix-sub468290 +Ref: table-gensub-escapes469190 +Node: I/O Functions470361 +Ref: I/O Functions-Footnote-1477058 +Node: Time Functions477205 +Ref: Time Functions-Footnote-1487861 +Ref: Time Functions-Footnote-2487929 +Ref: Time Functions-Footnote-3488087 +Ref: Time Functions-Footnote-4488198 +Ref: Time Functions-Footnote-5488310 +Ref: Time Functions-Footnote-6488537 +Node: Bitwise Functions488803 +Ref: table-bitwise-ops489361 +Ref: Bitwise Functions-Footnote-1493521 +Node: I18N Functions493705 +Node: User-defined495335 +Node: Definition Syntax496139 +Ref: Definition Syntax-Footnote-1500769 +Node: Function Example500838 +Node: Function Caveats503432 +Node: Calling A Function503853 +Node: Variable Scope504942 +Node: Pass By Value/Reference506870 +Node: Return Statement510310 +Node: Dynamic Typing513252 +Node: Indirect Calls513989 +Node: Internationalization523674 +Node: I18N and L10N525102 +Node: Explaining gettext525788 +Ref: Explaining gettext-Footnote-1530850 +Ref: Explaining gettext-Footnote-2531033 +Node: Programmer i18n531198 +Node: Translator i18n535461 +Node: String Extraction536254 +Ref: String Extraction-Footnote-1537215 +Node: Printf Ordering537301 +Ref: Printf Ordering-Footnote-1540085 +Node: I18N Portability540149 +Ref: I18N Portability-Footnote-1542598 +Node: I18N Example542661 +Ref: I18N Example-Footnote-1545296 +Node: Gawk I18N545368 +Node: Advanced Features545937 +Node: Nondecimal Data547256 +Node: Two-way I/O548817 +Ref: Two-way I/O-Footnote-1554231 +Node: TCP/IP Networking554308 +Node: Profiling557161 +Node: Library Functions564561 +Ref: Library Functions-Footnote-1567531 +Node: Library Names567702 +Ref: Library Names-Footnote-1571173 +Ref: Library Names-Footnote-2571393 +Node: General Functions571479 +Node: Nextfile Function572542 +Node: Strtonum Function576923 +Node: Assert Function579874 +Node: Round Function583200 +Node: Cliff Random Function584741 +Node: Ordinal Functions585757 +Ref: Ordinal Functions-Footnote-1588827 +Ref: Ordinal Functions-Footnote-2589079 +Node: Join Function589295 +Ref: Join Function-Footnote-1591066 +Node: Gettimeofday Function591266 +Node: Data File Management594981 +Node: Filetrans Function595613 +Node: Rewind Function599850 +Node: File Checking601303 +Node: Empty Files602397 +Node: Ignoring Assigns604627 +Node: Getopt Function606180 +Ref: Getopt Function-Footnote-1617505 +Node: Passwd Functions617708 +Ref: Passwd Functions-Footnote-1626696 +Node: Group Functions626784 +Node: Sample Programs634864 +Node: Running Examples635533 +Node: Clones636261 +Node: Cut Program637393 +Node: Egrep Program647160 +Ref: Egrep Program-Footnote-1654914 +Node: Id Program655024 +Node: Split Program658631 +Node: Tee Program662099 +Node: Uniq Program664842 +Node: Wc Program672219 +Ref: Wc Program-Footnote-1676465 +Node: Miscellaneous Programs676661 +Node: Dupword Program677781 +Node: Alarm Program679812 +Node: Translate Program684356 +Ref: Translate Program-Footnote-1688735 +Ref: Translate Program-Footnote-2688972 +Node: Labels Program689106 +Ref: Labels Program-Footnote-1692397 +Node: Word Sorting692481 +Node: History Sorting696828 +Node: Extract Program698666 +Node: Simple Sed706029 +Node: Igawk Program709086 +Ref: Igawk Program-Footnote-1723821 +Ref: Igawk Program-Footnote-2724022 +Node: Signature Program724160 +Node: Debugger725240 +Node: Debugging726116 +Node: Debugging Concepts726430 +Node: Debugging Terms728283 +Node: Awk Debugging730831 +Node: Sample dgawk session731723 +Node: dgawk invocation732215 +Node: Finding The Bug733399 +Node: List of Debugger Commands739914 +Node: Breakpoint Control741229 +Node: Dgawk Execution Control744439 +Node: Viewing And Changing Data747788 +Node: Dgawk Stack751084 +Node: Dgawk Info752545 +Node: Miscellaneous Dgawk Commands756483 +Node: Readline Support762199 +Node: Dgawk Limitations763015 +Node: Language History765187 +Node: V7/SVR3.1766564 +Node: SVR4768859 +Node: POSIX770304 +Node: BTL772016 +Node: POSIX/GNU773706 +Node: Contributors783370 +Node: Installation786979 +Node: Gawk Distribution787950 +Node: Getting788434 +Node: Extracting789260 +Node: Distribution contents790648 +Node: Unix Installation795721 +Node: Quick Installation796312 +Node: Additional Configuration Options798014 +Node: Configuration Philosophy799777 +Node: Non-Unix Installation802141 +Node: PC Installation802606 +Node: PC Binary Installation803912 +Node: PC Compiling805755 +Node: PC Dynamic810260 +Node: PC Using812623 +Node: Cygwin817171 +Node: MSYS818155 +Node: VMS Installation818661 +Node: VMS Compilation819265 +Node: VMS Installation Details820842 +Node: VMS Running822472 +Node: VMS POSIX824069 +Node: VMS Old Gawk825367 +Node: Unsupported825836 +Node: Atari Installation826298 +Node: Atari Compiling827585 +Node: Atari Using829474 +Node: BeOS Installation832321 +Node: Tandem Installation833466 +Node: Bugs835145 +Node: Other Versions838977 +Node: Notes844199 +Node: Compatibility Mode844891 +Node: Additions845674 +Node: Adding Code846424 +Node: New Ports852476 +Node: Dynamic Extensions856608 +Node: Internals857989 +Node: Plugin License868394 +Node: Sample Library869028 +Node: Internal File Description869692 +Node: Internal File Ops873387 +Ref: Internal File Ops-Footnote-1878263 +Node: Using Internal File Ops878411 +Node: Future Extensions880436 +Node: Basic Concepts884473 +Node: Basic High Level885230 +Ref: Basic High Level-Footnote-1889349 +Node: Basic Data Typing889543 +Node: Floating Point Issues893980 +Node: String Conversion Precision895063 +Ref: String Conversion Precision-Footnote-1896757 +Node: Unexpected Results896866 +Node: POSIX Floating Point Problems898692 +Ref: POSIX Floating Point Problems-Footnote-1902391 +Node: Glossary902429 +Node: Copying926212 +Node: GNU Free Documentation License963769 +Node: next-edition988913 +Node: unresolved989265 +Node: revision989765 +Node: consistency990188 +Node: Index993541 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 3b9a1bdd..e1100b5a 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -754,7 +754,7 @@ the GNU General Public License. (Incidentally, it's no longer difficult to find a new @command{awk}. @command{gawk} ships with -Linux, and you can download binaries or source code for almost +GNU/Linux, and you can download binaries or source code for almost any system; my wife uses @command{gawk} on her VMS box.) My Unix system started out unplugged from the wall; it certainly was not @@ -3689,19 +3689,19 @@ to @code{EXIT_FAILURE}. @c Panos Papadopoulos <panos1962@gmail.com> contributed the original @c text for this section. -@strong{FIXME:} This section still needs some editing. +This @value{SECTION} describes a feature that is specific to @command{gawk}. -The @samp{@@include} keyword can be used to read external source @command{awk} -files. That gives the ability to split large @command{awk} source files +The @samp{@@include} keyword can be used to read external @command{awk} source +files. This gives you the ability to split large @command{awk} source files into smaller, more manageable pieces, and also lets you reuse common @command{awk} code from various @command{awk} scripts. In other words, you can group together @command{awk} functions, used to carry out specific tasks, -in external files. These files can be used just like function libraries, +into external files. These files can be used just like function libraries, using the @samp{@@include} keyword in conjuction with the @code{AWKPATH} environment variable. -Let's see an example to demonstrate file inclusion in @command{gawk}. -To do so, we'll use two (trivial) @command{awk} scripts, namely +Let's see an example. +We'll start with two (trivial) @command{awk} scripts, namely @file{test1} and @file{test2}. Here is the @file{test1} script: @example @@ -3729,8 +3729,8 @@ $ @kbd{gawk -f test2} @print{} This is file test2. @end example -@code{gawk} runs the @file{test2} script where @file{test1} has been -included in the source of @file{test2} by means of the @samp{@@include} +@code{gawk} runs the @file{test2} script which includes @file{test1} +using the @samp{@@include} keyword. So, to include external @command{awk} source files you just use @samp{@@include} followed by the name of the file to be included, enclosed in double quotes. @@ -3740,7 +3740,7 @@ Keep in mind that this is a language construct and the @value{FN} cannot be a string variable, but rather just a literal string in double quotes. @end quotation -The files to be included may be nested; e.g. given a third +The files to be included may be nested; e.g., given a third script, namely @file{test3}: @example @@ -3751,8 +3751,8 @@ BEGIN @{ @end example @noindent -and running @command{gawk} with the @file{test3} script you'll get the -following result: +Running @command{gawk} with the @file{test3} script produces the +following results: @example $ @kbd{gawk -f test3} @@ -3761,14 +3761,14 @@ $ @kbd{gawk -f test3} @print{} This is file test3. @end example -The @value{FN} can, of course, be a pathname, e.g. +The @value{FN} can, of course, be a pathname. For example: @example @@include "../io_funcs" @end example @noindent -or +or: @example @@include "/usr/awklib/network" @@ -3777,26 +3777,29 @@ or @noindent are valid. The @code{AWKPATH} environment variable can be of great value when using @samp{@@include}. The same rules for the use -of the @code{AWKPATH} variable in command line file searches apply to -@samp{@@include} also. This is very helpful in -constructing @command{gawk} function libraries. You can edit huge -scripts containing useful @command{gawk} libraries and put those -files in a special directory. You can then include those ``libraries'' -using either the full pathnames of the files or by setting -the @code{AWKPATH} environment variable accordingly and then using @samp{@@include} -with just the name part of the full file pathname. Of course you can -have more than one directory to keep library files; the more complex -the working enviroment is, the more directories you may need to organize -the files to be included. +of the @code{AWKPATH} variable in command line file searches +(@pxref{AWKPATH Variable}) apply to +@samp{@@include} also. + +This is very helpful in constructing @command{gawk} function libraries. +If you have a large script with useful, general purpose @command{awk} +functions, you can break it down into library files and put those files +in a special directory. You can then include those ``libraries,'' using +either the full pathnames of the files, or by setting the @code{AWKPATH} +environment variable accordingly and then using @samp{@@include} with +just the file part of the full pathname. Of course you can have more +than one directory to keep library files; the more complex the working +enviroment is, the more directories you may need to organize the files +to be included. Given the ability to specify multiple @option{-f} options, the @samp{@@include} mechanism is not strictly necessary. However, the @samp{@@include} keyword can help you in constructing self-contained @command{gawk} programs, -thus reducing the need of writing complex and tedious command lines. +thus reducing the need for writing complex and tedious command lines. As mentioned in @ref{AWKPATH Variable}, the current directory is always -search first for source files, before searching in @env{AWKPATH}, +searched first for source files, before searching in @env{AWKPATH}, and this also applies to files named with @samp{@@include}. @node Obsolete @@ -30435,7 +30438,7 @@ environment. @item GNU/Linux A variant of the GNU system using the Linux kernel, instead of the Free Software Foundation's Hurd kernel. -Linux is a stable, efficient, full-featured clone of Unix that has +The Linux kernel is a stable, efficient, full-featured clone of Unix that has been ported to a variety of architectures. It is most popular on PC-class systems, but runs well on a variety of other systems too. |