diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/gawk.info | 1107 | ||||
| -rw-r--r-- | doc/gawk.texi | 50 | ||||
| -rw-r--r-- | doc/gawktexi.in | 50 |
4 files changed, 651 insertions, 562 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 959fa3e9..33930e84 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -51,6 +51,12 @@ typeof() behavior. Thanks to Mark Krauze <daburashka@ya.ru>, for pointing out the issues. +2019-06-05 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Invoking Summary): Added nice summarization of + argument processing contributed by Neil R. Ormos, + <ormos-gnulists17@ormos.org>. + 2019-05-22 Arnold D. Robbins <arnold@skeeve.com> * gawk.1, gawktexi.in: Document --lint=no-ext. diff --git a/doc/gawk.info b/doc/gawk.info index 16ff7247..88eae820 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -3368,8 +3368,35 @@ File: gawk.info, Node: Invoking Summary, Prev: Undocumented, Up: Invoking Gaw 2.11 Summary ============ - * Use either 'awk 'PROGRAM' FILES' or 'awk -f PROGRAM-FILE FILES' to - run 'awk'. + * 'gawk' parses arguments on the command line, left to right, to + determine if they should be treated as options or as non-option + arguments. + + * 'gawk' recognizes several options which control its operation, as + described in *note Options::. All options begin with '-'. + + * Any argument that is not recognized as an option is treated as a + non-option argument, even if it begins with '-'. + + - However, when an option itself requires an argument, and the + option is separated from that argument on the command line by + at least one space, the space is ignored, and the argument is + considered to be related to the option. Thus, in the + invocation, 'gawk -F x', the 'x' is treated as belonging to + the '-F' option, not as a separate non-option argument. + + * Once 'gawk' finds a non-option argument, it stops looking for + options. Therefore, all following arguments are also non-option + arguments, even if they resemble recognized options. + + * If no '-e' or '-f' options are present, 'gawk' expects the program + text to be in the first non-option argument. + + * All non-option arguments, except program text provided in the first + non-option argument, are placed in 'ARGV' as explained in *note + ARGC and ARGV::, and are processed as described in *note Other + Arguments::. Adjusting 'ARGC' and 'ARGV' affects how 'awk' + processes input. * The three standard options for all versions of 'awk' are '-f', '-F', and '-v'. 'gawk' supplies these and many others, as well as @@ -3380,10 +3407,6 @@ File: gawk.info, Node: Invoking Summary, Prev: Undocumented, Up: Invoking Gaw as variable assignments to be performed at that point in processing the input. - * All nonoption command-line arguments, excluding the program text, - are placed in the 'ARGV' array. Adjusting 'ARGC' and 'ARGV' - affects how 'awk' processes input. - * You can use a single minus sign ('-') to refer to standard input on the command line. 'gawk' also lets you use the special file name '/dev/stdin'. @@ -36978,541 +37001,541 @@ Node: Loading Shared Libraries155547 Node: Obsolete156975 Node: Undocumented157667 Node: Invoking Summary157964 -Node: Regexp159624 -Node: Regexp Usage161078 -Node: Escape Sequences163115 -Node: Regexp Operators169347 -Node: Regexp Operator Details169832 -Ref: Regexp Operator Details-Footnote-1176264 -Node: Interval Expressions176411 -Ref: Interval Expressions-Footnote-1177846 -Node: Bracket Expressions177944 -Ref: table-char-classes180420 -Node: Leftmost Longest183746 -Node: Computed Regexps185049 -Node: GNU Regexp Operators188476 -Node: Case-sensitivity192155 -Ref: Case-sensitivity-Footnote-1195021 -Ref: Case-sensitivity-Footnote-2195256 -Node: Regexp Summary195364 -Node: Reading Files196830 -Node: Records199099 -Node: awk split records200174 -Node: gawk split records205449 -Ref: gawk split records-Footnote-1210035 -Node: Fields210072 -Node: Nonconstant Fields212813 -Ref: Nonconstant Fields-Footnote-1215049 -Node: Changing Fields215253 -Node: Field Separators221284 -Node: Default Field Splitting223982 -Node: Regexp Field Splitting225100 -Node: Single Character Fields228453 -Node: Command Line Field Separator229513 -Node: Full Line Fields232731 -Ref: Full Line Fields-Footnote-1234253 -Ref: Full Line Fields-Footnote-2234299 -Node: Field Splitting Summary234400 -Node: Constant Size236474 -Node: Fixed width data237206 -Node: Skipping intervening240673 -Node: Allowing trailing data241471 -Node: Fields with fixed data242508 -Node: Splitting By Content244026 -Ref: Splitting By Content-Footnote-1247676 -Node: Testing field creation247839 -Node: Multiple Line249464 -Node: Getline255741 -Node: Plain Getline258210 -Node: Getline/Variable260783 -Node: Getline/File261934 -Node: Getline/Variable/File263322 -Ref: Getline/Variable/File-Footnote-1264927 -Node: Getline/Pipe265015 -Node: Getline/Variable/Pipe267719 -Node: Getline/Coprocess268854 -Node: Getline/Variable/Coprocess270121 -Node: Getline Notes270863 -Node: Getline Summary273660 -Ref: table-getline-variants274084 -Node: Read Timeout274832 -Ref: Read Timeout-Footnote-1278738 -Node: Retrying Input278796 -Node: Command-line directories279995 -Node: Input Summary280901 -Node: Input Exercises284073 -Node: Printing284507 -Node: Print286341 -Node: Print Examples287798 -Node: Output Separators290578 -Node: OFMT292595 -Node: Printf293951 -Node: Basic Printf294736 -Node: Control Letters296310 -Node: Format Modifiers301474 -Node: Printf Examples307489 -Node: Redirection309975 -Node: Special FD316816 -Ref: Special FD-Footnote-1319984 -Node: Special Files320058 -Node: Other Inherited Files320675 -Node: Special Network321676 -Node: Special Caveats322536 -Node: Close Files And Pipes323485 -Ref: table-close-pipe-return-values330392 -Ref: Close Files And Pipes-Footnote-1331205 -Ref: Close Files And Pipes-Footnote-2331353 -Node: Nonfatal331505 -Node: Output Summary333843 -Node: Output Exercises335065 -Node: Expressions335744 -Node: Values336932 -Node: Constants337610 -Node: Scalar Constants338301 -Ref: Scalar Constants-Footnote-1340825 -Node: Nondecimal-numbers341075 -Node: Regexp Constants344076 -Node: Using Constant Regexps344602 -Node: Standard Regexp Constants345224 -Node: Strong Regexp Constants348412 -Node: Variables351370 -Node: Using Variables352027 -Node: Assignment Options353937 -Node: Conversion356404 -Node: Strings And Numbers356928 -Ref: Strings And Numbers-Footnote-1359991 -Node: Locale influences conversions360100 -Ref: table-locale-affects362858 -Node: All Operators363476 -Node: Arithmetic Ops364105 -Node: Concatenation366611 -Ref: Concatenation-Footnote-1369458 -Node: Assignment Ops369565 -Ref: table-assign-ops374556 -Node: Increment Ops375869 -Node: Truth Values and Conditions379329 -Node: Truth Values380403 -Node: Typing and Comparison381451 -Node: Variable Typing382271 -Ref: Variable Typing-Footnote-1388734 -Ref: Variable Typing-Footnote-2388806 -Node: Comparison Operators388883 -Ref: table-relational-ops389302 -Node: POSIX String Comparison392797 -Ref: POSIX String Comparison-Footnote-1394492 -Ref: POSIX String Comparison-Footnote-2394631 -Node: Boolean Ops394715 -Ref: Boolean Ops-Footnote-1399197 -Node: Conditional Exp399289 -Node: Function Calls401025 -Node: Precedence404902 -Node: Locales408561 -Node: Expressions Summary410193 -Node: Patterns and Actions412766 -Node: Pattern Overview413886 -Node: Regexp Patterns415563 -Node: Expression Patterns416105 -Node: Ranges419886 -Node: BEGIN/END422994 -Node: Using BEGIN/END423755 -Ref: Using BEGIN/END-Footnote-1426491 -Node: I/O And BEGIN/END426597 -Node: BEGINFILE/ENDFILE428911 -Node: Empty431824 -Node: Using Shell Variables432141 -Node: Action Overview434415 -Node: Statements436740 -Node: If Statement438588 -Node: While Statement440083 -Node: Do Statement442111 -Node: For Statement443259 -Node: Switch Statement446430 -Node: Break Statement448816 -Node: Continue Statement450908 -Node: Next Statement452735 -Node: Nextfile Statement455118 -Node: Exit Statement457770 -Node: Built-in Variables460173 -Node: User-modified461306 -Node: Auto-set469073 -Ref: Auto-set-Footnote-1485880 -Ref: Auto-set-Footnote-2486086 -Node: ARGC and ARGV486142 -Node: Pattern Action Summary490355 -Node: Arrays492785 -Node: Array Basics494114 -Node: Array Intro494958 -Ref: figure-array-elements496933 -Ref: Array Intro-Footnote-1499637 -Node: Reference to Elements499765 -Node: Assigning Elements502229 -Node: Array Example502720 -Node: Scanning an Array504479 -Node: Controlling Scanning507501 -Ref: Controlling Scanning-Footnote-1512900 -Node: Numeric Array Subscripts513216 -Node: Uninitialized Subscripts515400 -Node: Delete517019 -Ref: Delete-Footnote-1519771 -Node: Multidimensional519828 -Node: Multiscanning522923 -Node: Arrays of Arrays524514 -Node: Arrays Summary529282 -Node: Functions531375 -Node: Built-in532413 -Node: Calling Built-in533494 -Node: Numeric Functions535490 -Ref: Numeric Functions-Footnote-1539518 -Ref: Numeric Functions-Footnote-2540166 -Ref: Numeric Functions-Footnote-3540214 -Node: String Functions540486 -Ref: String Functions-Footnote-1564344 -Ref: String Functions-Footnote-2564472 -Ref: String Functions-Footnote-3564720 -Node: Gory Details564807 -Ref: table-sub-escapes566598 -Ref: table-sub-proposed568117 -Ref: table-posix-sub569480 -Ref: table-gensub-escapes571021 -Ref: Gory Details-Footnote-1571844 -Node: I/O Functions571998 -Ref: table-system-return-values578466 -Ref: I/O Functions-Footnote-1580546 -Ref: I/O Functions-Footnote-2580694 -Node: Time Functions580814 -Ref: Time Functions-Footnote-1591485 -Ref: Time Functions-Footnote-2591553 -Ref: Time Functions-Footnote-3591711 -Ref: Time Functions-Footnote-4591822 -Ref: Time Functions-Footnote-5591934 -Ref: Time Functions-Footnote-6592161 -Node: Bitwise Functions592427 -Ref: table-bitwise-ops593021 -Ref: Bitwise Functions-Footnote-1599084 -Ref: Bitwise Functions-Footnote-2599257 -Node: Type Functions599448 -Node: I18N Functions602311 -Node: User-defined603962 -Node: Definition Syntax604774 -Ref: Definition Syntax-Footnote-1610461 -Node: Function Example610532 -Ref: Function Example-Footnote-1613454 -Node: Function Calling613476 -Node: Calling A Function614064 -Node: Variable Scope615022 -Node: Pass By Value/Reference618016 -Node: Function Caveats620660 -Ref: Function Caveats-Footnote-1622707 -Node: Return Statement622827 -Node: Dynamic Typing625806 -Node: Indirect Calls626736 -Ref: Indirect Calls-Footnote-1636988 -Node: Functions Summary637116 -Node: Library Functions639821 -Ref: Library Functions-Footnote-1643428 -Ref: Library Functions-Footnote-2643571 -Node: Library Names643742 -Ref: Library Names-Footnote-1647409 -Ref: Library Names-Footnote-2647632 -Node: General Functions647718 -Node: Strtonum Function648821 -Node: Assert Function651843 -Node: Round Function655169 -Node: Cliff Random Function656709 -Node: Ordinal Functions657725 -Ref: Ordinal Functions-Footnote-1660788 -Ref: Ordinal Functions-Footnote-2661040 -Node: Join Function661250 -Ref: Join Function-Footnote-1663020 -Node: Getlocaltime Function663220 -Node: Readfile Function666962 -Node: Shell Quoting668939 -Node: Data File Management670340 -Node: Filetrans Function670972 -Node: Rewind Function675068 -Node: File Checking676977 -Ref: File Checking-Footnote-1678311 -Node: Empty Files678512 -Node: Ignoring Assigns680491 -Node: Getopt Function682041 -Ref: Getopt Function-Footnote-1693510 -Node: Passwd Functions693710 -Ref: Passwd Functions-Footnote-1702549 -Node: Group Functions702637 -Ref: Group Functions-Footnote-1710535 -Node: Walking Arrays710742 -Node: Library Functions Summary713750 -Node: Library Exercises715156 -Node: Sample Programs715621 -Node: Running Examples716391 -Node: Clones717119 -Node: Cut Program718343 -Node: Egrep Program728272 -Ref: Egrep Program-Footnote-1735784 -Node: Id Program735894 -Node: Split Program739574 -Ref: Split Program-Footnote-1743032 -Node: Tee Program743161 -Node: Uniq Program745951 -Node: Wc Program753572 -Ref: Wc Program-Footnote-1757827 -Node: Miscellaneous Programs757921 -Node: Dupword Program759134 -Node: Alarm Program761164 -Node: Translate Program766019 -Ref: Translate Program-Footnote-1770584 -Node: Labels Program770854 -Ref: Labels Program-Footnote-1774205 -Node: Word Sorting774289 -Node: History Sorting778361 -Node: Extract Program780196 -Node: Simple Sed788250 -Node: Igawk Program791324 -Ref: Igawk Program-Footnote-1805655 -Ref: Igawk Program-Footnote-2805857 -Ref: Igawk Program-Footnote-3805979 -Node: Anagram Program806094 -Node: Signature Program809156 -Node: Programs Summary810403 -Node: Programs Exercises811617 -Ref: Programs Exercises-Footnote-1815746 -Node: Advanced Features815837 -Node: Nondecimal Data817827 -Node: Array Sorting819418 -Node: Controlling Array Traversal820118 -Ref: Controlling Array Traversal-Footnote-1828486 -Node: Array Sorting Functions828604 -Ref: Array Sorting Functions-Footnote-1833695 -Node: Two-way I/O833891 -Ref: Two-way I/O-Footnote-1841612 -Ref: Two-way I/O-Footnote-2841799 -Node: TCP/IP Networking841881 -Node: Profiling844999 -Node: Advanced Features Summary854014 -Node: Internationalization855858 -Node: I18N and L10N857338 -Node: Explaining gettext858025 -Ref: Explaining gettext-Footnote-1863917 -Ref: Explaining gettext-Footnote-2864102 -Node: Programmer i18n864267 -Ref: Programmer i18n-Footnote-1869216 -Node: Translator i18n869265 -Node: String Extraction870059 -Ref: String Extraction-Footnote-1871191 -Node: Printf Ordering871277 -Ref: Printf Ordering-Footnote-1874063 -Node: I18N Portability874127 -Ref: I18N Portability-Footnote-1876583 -Node: I18N Example876646 -Ref: I18N Example-Footnote-1879921 -Ref: I18N Example-Footnote-2879994 -Node: Gawk I18N880103 -Node: I18N Summary880752 -Node: Debugger882093 -Node: Debugging883093 -Node: Debugging Concepts883534 -Node: Debugging Terms885343 -Node: Awk Debugging887918 -Ref: Awk Debugging-Footnote-1888863 -Node: Sample Debugging Session888995 -Node: Debugger Invocation889529 -Node: Finding The Bug890915 -Node: List of Debugger Commands897389 -Node: Breakpoint Control898722 -Node: Debugger Execution Control902416 -Node: Viewing And Changing Data905778 -Node: Execution Stack909319 -Node: Debugger Info910956 -Node: Miscellaneous Debugger Commands915027 -Node: Readline Support920089 -Node: Limitations920985 -Node: Debugging Summary923539 -Node: Namespaces924818 -Node: Global Namespace925929 -Node: Qualified Names927327 -Node: Default Namespace928326 -Node: Changing The Namespace929067 -Node: Naming Rules930681 -Node: Internal Name Management932529 -Node: Namespace Example933571 -Node: Namespace And Features936133 -Node: Namespace Summary937568 -Node: Arbitrary Precision Arithmetic939045 -Node: Computer Arithmetic940532 -Ref: table-numeric-ranges944298 -Ref: table-floating-point-ranges944791 -Ref: Computer Arithmetic-Footnote-1945449 -Node: Math Definitions945506 -Ref: table-ieee-formats948822 -Ref: Math Definitions-Footnote-1949425 -Node: MPFR features949530 -Node: FP Math Caution951248 -Ref: FP Math Caution-Footnote-1952320 -Node: Inexactness of computations952689 -Node: Inexact representation953649 -Node: Comparing FP Values955009 -Node: Errors accumulate956250 -Node: Getting Accuracy957683 -Node: Try To Round960393 -Node: Setting precision961292 -Ref: table-predefined-precision-strings961989 -Node: Setting the rounding mode963819 -Ref: table-gawk-rounding-modes964193 -Ref: Setting the rounding mode-Footnote-1968124 -Node: Arbitrary Precision Integers968303 -Ref: Arbitrary Precision Integers-Footnote-1971478 -Node: Checking for MPFR971627 -Node: POSIX Floating Point Problems973101 -Ref: POSIX Floating Point Problems-Footnote-1977386 -Node: Floating point summary977424 -Node: Dynamic Extensions979614 -Node: Extension Intro981167 -Node: Plugin License982433 -Node: Extension Mechanism Outline983230 -Ref: figure-load-extension983669 -Ref: figure-register-new-function985234 -Ref: figure-call-new-function986326 -Node: Extension API Description988388 -Node: Extension API Functions Introduction990030 -Ref: table-api-std-headers991866 -Node: General Data Types995731 -Ref: General Data Types-Footnote-11004092 -Node: Memory Allocation Functions1004391 -Ref: Memory Allocation Functions-Footnote-11008601 -Node: Constructor Functions1008700 -Node: Registration Functions1012286 -Node: Extension Functions1012971 -Node: Exit Callback Functions1018293 -Node: Extension Version String1019543 -Node: Input Parsers1020206 -Node: Output Wrappers1032927 -Node: Two-way processors1037439 -Node: Printing Messages1039704 -Ref: Printing Messages-Footnote-11040875 -Node: Updating ERRNO1041028 -Node: Requesting Values1041767 -Ref: table-value-types-returned1042504 -Node: Accessing Parameters1043440 -Node: Symbol Table Access1044675 -Node: Symbol table by name1045187 -Ref: Symbol table by name-Footnote-11048211 -Node: Symbol table by cookie1048339 -Ref: Symbol table by cookie-Footnote-11052524 -Node: Cached values1052588 -Ref: Cached values-Footnote-11056124 -Node: Array Manipulation1056277 -Ref: Array Manipulation-Footnote-11057368 -Node: Array Data Types1057405 -Ref: Array Data Types-Footnote-11060063 -Node: Array Functions1060155 -Node: Flattening Arrays1064653 -Node: Creating Arrays1071629 -Node: Redirection API1076396 -Node: Extension API Variables1079229 -Node: Extension Versioning1079940 -Ref: gawk-api-version1080369 -Node: Extension GMP/MPFR Versioning1082100 -Node: Extension API Informational Variables1083728 -Node: Extension API Boilerplate1084801 -Node: Changes from API V11088775 -Node: Finding Extensions1090347 -Node: Extension Example1090906 -Node: Internal File Description1091704 -Node: Internal File Ops1095784 -Ref: Internal File Ops-Footnote-11107134 -Node: Using Internal File Ops1107274 -Ref: Using Internal File Ops-Footnote-11109657 -Node: Extension Samples1109931 -Node: Extension Sample File Functions1111460 -Node: Extension Sample Fnmatch1119109 -Node: Extension Sample Fork1120596 -Node: Extension Sample Inplace1121814 -Node: Extension Sample Ord1125439 -Node: Extension Sample Readdir1126275 -Ref: table-readdir-file-types1127164 -Node: Extension Sample Revout1127969 -Node: Extension Sample Rev2way1128558 -Node: Extension Sample Read write array1129298 -Node: Extension Sample Readfile1131240 -Node: Extension Sample Time1132335 -Node: Extension Sample API Tests1133683 -Node: gawkextlib1134175 -Node: Extension summary1137093 -Node: Extension Exercises1140795 -Node: Language History1142037 -Node: V7/SVR3.11143693 -Node: SVR41145845 -Node: POSIX1147279 -Node: BTL1148659 -Node: POSIX/GNU1149388 -Node: Feature History1155166 -Node: Common Extensions1171359 -Node: Ranges and Locales1172642 -Ref: Ranges and Locales-Footnote-11177258 -Ref: Ranges and Locales-Footnote-21177285 -Ref: Ranges and Locales-Footnote-31177520 -Node: Contributors1177741 -Node: History summary1183694 -Node: Installation1185074 -Node: Gawk Distribution1186018 -Node: Getting1186502 -Node: Extracting1187465 -Node: Distribution contents1189103 -Node: Unix Installation1195583 -Node: Quick Installation1196265 -Node: Shell Startup Files1198679 -Node: Additional Configuration Options1199768 -Node: Configuration Philosophy1202083 -Node: Non-Unix Installation1204452 -Node: PC Installation1204912 -Node: PC Binary Installation1205750 -Node: PC Compiling1206185 -Node: PC Using1207302 -Node: Cygwin1210855 -Node: MSYS1211954 -Node: VMS Installation1212455 -Node: VMS Compilation1213246 -Ref: VMS Compilation-Footnote-11214475 -Node: VMS Dynamic Extensions1214533 -Node: VMS Installation Details1216218 -Node: VMS Running1218471 -Node: VMS GNV1222750 -Node: VMS Old Gawk1223485 -Node: Bugs1223956 -Node: Bug address1224619 -Node: Usenet1227601 -Node: Maintainers1228605 -Node: Other Versions1229866 -Node: Installation summary1236954 -Node: Notes1238156 -Node: Compatibility Mode1238950 -Node: Additions1239732 -Node: Accessing The Source1240657 -Node: Adding Code1242094 -Node: New Ports1248313 -Node: Derived Files1252688 -Ref: Derived Files-Footnote-11258348 -Ref: Derived Files-Footnote-21258383 -Ref: Derived Files-Footnote-31258981 -Node: Future Extensions1259095 -Node: Implementation Limitations1259753 -Node: Extension Design1260936 -Node: Old Extension Problems1262080 -Ref: Old Extension Problems-Footnote-11263598 -Node: Extension New Mechanism Goals1263655 -Ref: Extension New Mechanism Goals-Footnote-11267019 -Node: Extension Other Design Decisions1267208 -Node: Extension Future Growth1269321 -Node: Notes summary1270157 -Node: Basic Concepts1271315 -Node: Basic High Level1271996 -Ref: figure-general-flow1272278 -Ref: figure-process-flow1272963 -Ref: Basic High Level-Footnote-11276264 -Node: Basic Data Typing1276449 -Node: Glossary1279777 -Node: Copying1311615 -Node: GNU Free Documentation License1349158 -Node: Index1374278 +Node: Regexp160805 +Node: Regexp Usage162259 +Node: Escape Sequences164296 +Node: Regexp Operators170528 +Node: Regexp Operator Details171013 +Ref: Regexp Operator Details-Footnote-1177445 +Node: Interval Expressions177592 +Ref: Interval Expressions-Footnote-1179027 +Node: Bracket Expressions179125 +Ref: table-char-classes181601 +Node: Leftmost Longest184927 +Node: Computed Regexps186230 +Node: GNU Regexp Operators189657 +Node: Case-sensitivity193336 +Ref: Case-sensitivity-Footnote-1196202 +Ref: Case-sensitivity-Footnote-2196437 +Node: Regexp Summary196545 +Node: Reading Files198011 +Node: Records200280 +Node: awk split records201355 +Node: gawk split records206630 +Ref: gawk split records-Footnote-1211216 +Node: Fields211253 +Node: Nonconstant Fields213994 +Ref: Nonconstant Fields-Footnote-1216230 +Node: Changing Fields216434 +Node: Field Separators222465 +Node: Default Field Splitting225163 +Node: Regexp Field Splitting226281 +Node: Single Character Fields229634 +Node: Command Line Field Separator230694 +Node: Full Line Fields233912 +Ref: Full Line Fields-Footnote-1235434 +Ref: Full Line Fields-Footnote-2235480 +Node: Field Splitting Summary235581 +Node: Constant Size237655 +Node: Fixed width data238387 +Node: Skipping intervening241854 +Node: Allowing trailing data242652 +Node: Fields with fixed data243689 +Node: Splitting By Content245207 +Ref: Splitting By Content-Footnote-1248857 +Node: Testing field creation249020 +Node: Multiple Line250645 +Node: Getline256922 +Node: Plain Getline259391 +Node: Getline/Variable261964 +Node: Getline/File263115 +Node: Getline/Variable/File264503 +Ref: Getline/Variable/File-Footnote-1266108 +Node: Getline/Pipe266196 +Node: Getline/Variable/Pipe268900 +Node: Getline/Coprocess270035 +Node: Getline/Variable/Coprocess271302 +Node: Getline Notes272044 +Node: Getline Summary274841 +Ref: table-getline-variants275265 +Node: Read Timeout276013 +Ref: Read Timeout-Footnote-1279919 +Node: Retrying Input279977 +Node: Command-line directories281176 +Node: Input Summary282082 +Node: Input Exercises285254 +Node: Printing285688 +Node: Print287522 +Node: Print Examples288979 +Node: Output Separators291759 +Node: OFMT293776 +Node: Printf295132 +Node: Basic Printf295917 +Node: Control Letters297491 +Node: Format Modifiers302655 +Node: Printf Examples308670 +Node: Redirection311156 +Node: Special FD317997 +Ref: Special FD-Footnote-1321165 +Node: Special Files321239 +Node: Other Inherited Files321856 +Node: Special Network322857 +Node: Special Caveats323717 +Node: Close Files And Pipes324666 +Ref: table-close-pipe-return-values331573 +Ref: Close Files And Pipes-Footnote-1332386 +Ref: Close Files And Pipes-Footnote-2332534 +Node: Nonfatal332686 +Node: Output Summary335024 +Node: Output Exercises336246 +Node: Expressions336925 +Node: Values338113 +Node: Constants338791 +Node: Scalar Constants339482 +Ref: Scalar Constants-Footnote-1342006 +Node: Nondecimal-numbers342256 +Node: Regexp Constants345257 +Node: Using Constant Regexps345783 +Node: Standard Regexp Constants346405 +Node: Strong Regexp Constants349593 +Node: Variables352551 +Node: Using Variables353208 +Node: Assignment Options355118 +Node: Conversion357585 +Node: Strings And Numbers358109 +Ref: Strings And Numbers-Footnote-1361172 +Node: Locale influences conversions361281 +Ref: table-locale-affects364039 +Node: All Operators364657 +Node: Arithmetic Ops365286 +Node: Concatenation367792 +Ref: Concatenation-Footnote-1370639 +Node: Assignment Ops370746 +Ref: table-assign-ops375737 +Node: Increment Ops377050 +Node: Truth Values and Conditions380510 +Node: Truth Values381584 +Node: Typing and Comparison382632 +Node: Variable Typing383452 +Ref: Variable Typing-Footnote-1389915 +Ref: Variable Typing-Footnote-2389987 +Node: Comparison Operators390064 +Ref: table-relational-ops390483 +Node: POSIX String Comparison393978 +Ref: POSIX String Comparison-Footnote-1395673 +Ref: POSIX String Comparison-Footnote-2395812 +Node: Boolean Ops395896 +Ref: Boolean Ops-Footnote-1400378 +Node: Conditional Exp400470 +Node: Function Calls402206 +Node: Precedence406083 +Node: Locales409742 +Node: Expressions Summary411374 +Node: Patterns and Actions413947 +Node: Pattern Overview415067 +Node: Regexp Patterns416744 +Node: Expression Patterns417286 +Node: Ranges421067 +Node: BEGIN/END424175 +Node: Using BEGIN/END424936 +Ref: Using BEGIN/END-Footnote-1427672 +Node: I/O And BEGIN/END427778 +Node: BEGINFILE/ENDFILE430092 +Node: Empty433005 +Node: Using Shell Variables433322 +Node: Action Overview435596 +Node: Statements437921 +Node: If Statement439769 +Node: While Statement441264 +Node: Do Statement443292 +Node: For Statement444440 +Node: Switch Statement447611 +Node: Break Statement449997 +Node: Continue Statement452089 +Node: Next Statement453916 +Node: Nextfile Statement456299 +Node: Exit Statement458951 +Node: Built-in Variables461354 +Node: User-modified462487 +Node: Auto-set470254 +Ref: Auto-set-Footnote-1487061 +Ref: Auto-set-Footnote-2487267 +Node: ARGC and ARGV487323 +Node: Pattern Action Summary491536 +Node: Arrays493966 +Node: Array Basics495295 +Node: Array Intro496139 +Ref: figure-array-elements498114 +Ref: Array Intro-Footnote-1500818 +Node: Reference to Elements500946 +Node: Assigning Elements503410 +Node: Array Example503901 +Node: Scanning an Array505660 +Node: Controlling Scanning508682 +Ref: Controlling Scanning-Footnote-1514081 +Node: Numeric Array Subscripts514397 +Node: Uninitialized Subscripts516581 +Node: Delete518200 +Ref: Delete-Footnote-1520952 +Node: Multidimensional521009 +Node: Multiscanning524104 +Node: Arrays of Arrays525695 +Node: Arrays Summary530463 +Node: Functions532556 +Node: Built-in533594 +Node: Calling Built-in534675 +Node: Numeric Functions536671 +Ref: Numeric Functions-Footnote-1540699 +Ref: Numeric Functions-Footnote-2541347 +Ref: Numeric Functions-Footnote-3541395 +Node: String Functions541667 +Ref: String Functions-Footnote-1565525 +Ref: String Functions-Footnote-2565653 +Ref: String Functions-Footnote-3565901 +Node: Gory Details565988 +Ref: table-sub-escapes567779 +Ref: table-sub-proposed569298 +Ref: table-posix-sub570661 +Ref: table-gensub-escapes572202 +Ref: Gory Details-Footnote-1573025 +Node: I/O Functions573179 +Ref: table-system-return-values579647 +Ref: I/O Functions-Footnote-1581727 +Ref: I/O Functions-Footnote-2581875 +Node: Time Functions581995 +Ref: Time Functions-Footnote-1592666 +Ref: Time Functions-Footnote-2592734 +Ref: Time Functions-Footnote-3592892 +Ref: Time Functions-Footnote-4593003 +Ref: Time Functions-Footnote-5593115 +Ref: Time Functions-Footnote-6593342 +Node: Bitwise Functions593608 +Ref: table-bitwise-ops594202 +Ref: Bitwise Functions-Footnote-1600265 +Ref: Bitwise Functions-Footnote-2600438 +Node: Type Functions600629 +Node: I18N Functions603492 +Node: User-defined605143 +Node: Definition Syntax605955 +Ref: Definition Syntax-Footnote-1611642 +Node: Function Example611713 +Ref: Function Example-Footnote-1614635 +Node: Function Calling614657 +Node: Calling A Function615245 +Node: Variable Scope616203 +Node: Pass By Value/Reference619197 +Node: Function Caveats621841 +Ref: Function Caveats-Footnote-1623888 +Node: Return Statement624008 +Node: Dynamic Typing626987 +Node: Indirect Calls627917 +Ref: Indirect Calls-Footnote-1638169 +Node: Functions Summary638297 +Node: Library Functions641002 +Ref: Library Functions-Footnote-1644609 +Ref: Library Functions-Footnote-2644752 +Node: Library Names644923 +Ref: Library Names-Footnote-1648590 +Ref: Library Names-Footnote-2648813 +Node: General Functions648899 +Node: Strtonum Function650002 +Node: Assert Function653024 +Node: Round Function656350 +Node: Cliff Random Function657890 +Node: Ordinal Functions658906 +Ref: Ordinal Functions-Footnote-1661969 +Ref: Ordinal Functions-Footnote-2662221 +Node: Join Function662431 +Ref: Join Function-Footnote-1664201 +Node: Getlocaltime Function664401 +Node: Readfile Function668143 +Node: Shell Quoting670120 +Node: Data File Management671521 +Node: Filetrans Function672153 +Node: Rewind Function676249 +Node: File Checking678158 +Ref: File Checking-Footnote-1679492 +Node: Empty Files679693 +Node: Ignoring Assigns681672 +Node: Getopt Function683222 +Ref: Getopt Function-Footnote-1694691 +Node: Passwd Functions694891 +Ref: Passwd Functions-Footnote-1703730 +Node: Group Functions703818 +Ref: Group Functions-Footnote-1711716 +Node: Walking Arrays711923 +Node: Library Functions Summary714931 +Node: Library Exercises716337 +Node: Sample Programs716802 +Node: Running Examples717572 +Node: Clones718300 +Node: Cut Program719524 +Node: Egrep Program729453 +Ref: Egrep Program-Footnote-1736965 +Node: Id Program737075 +Node: Split Program740755 +Ref: Split Program-Footnote-1744213 +Node: Tee Program744342 +Node: Uniq Program747132 +Node: Wc Program754753 +Ref: Wc Program-Footnote-1759008 +Node: Miscellaneous Programs759102 +Node: Dupword Program760315 +Node: Alarm Program762345 +Node: Translate Program767200 +Ref: Translate Program-Footnote-1771765 +Node: Labels Program772035 +Ref: Labels Program-Footnote-1775386 +Node: Word Sorting775470 +Node: History Sorting779542 +Node: Extract Program781377 +Node: Simple Sed789431 +Node: Igawk Program792505 +Ref: Igawk Program-Footnote-1806836 +Ref: Igawk Program-Footnote-2807038 +Ref: Igawk Program-Footnote-3807160 +Node: Anagram Program807275 +Node: Signature Program810337 +Node: Programs Summary811584 +Node: Programs Exercises812798 +Ref: Programs Exercises-Footnote-1816927 +Node: Advanced Features817018 +Node: Nondecimal Data819008 +Node: Array Sorting820599 +Node: Controlling Array Traversal821299 +Ref: Controlling Array Traversal-Footnote-1829667 +Node: Array Sorting Functions829785 +Ref: Array Sorting Functions-Footnote-1834876 +Node: Two-way I/O835072 +Ref: Two-way I/O-Footnote-1842793 +Ref: Two-way I/O-Footnote-2842980 +Node: TCP/IP Networking843062 +Node: Profiling846180 +Node: Advanced Features Summary855195 +Node: Internationalization857039 +Node: I18N and L10N858519 +Node: Explaining gettext859206 +Ref: Explaining gettext-Footnote-1865098 +Ref: Explaining gettext-Footnote-2865283 +Node: Programmer i18n865448 +Ref: Programmer i18n-Footnote-1870397 +Node: Translator i18n870446 +Node: String Extraction871240 +Ref: String Extraction-Footnote-1872372 +Node: Printf Ordering872458 +Ref: Printf Ordering-Footnote-1875244 +Node: I18N Portability875308 +Ref: I18N Portability-Footnote-1877764 +Node: I18N Example877827 +Ref: I18N Example-Footnote-1881102 +Ref: I18N Example-Footnote-2881175 +Node: Gawk I18N881284 +Node: I18N Summary881933 +Node: Debugger883274 +Node: Debugging884274 +Node: Debugging Concepts884715 +Node: Debugging Terms886524 +Node: Awk Debugging889099 +Ref: Awk Debugging-Footnote-1890044 +Node: Sample Debugging Session890176 +Node: Debugger Invocation890710 +Node: Finding The Bug892096 +Node: List of Debugger Commands898570 +Node: Breakpoint Control899903 +Node: Debugger Execution Control903597 +Node: Viewing And Changing Data906959 +Node: Execution Stack910500 +Node: Debugger Info912137 +Node: Miscellaneous Debugger Commands916208 +Node: Readline Support921270 +Node: Limitations922166 +Node: Debugging Summary924720 +Node: Namespaces925999 +Node: Global Namespace927110 +Node: Qualified Names928508 +Node: Default Namespace929507 +Node: Changing The Namespace930248 +Node: Naming Rules931862 +Node: Internal Name Management933710 +Node: Namespace Example934752 +Node: Namespace And Features937314 +Node: Namespace Summary938749 +Node: Arbitrary Precision Arithmetic940226 +Node: Computer Arithmetic941713 +Ref: table-numeric-ranges945479 +Ref: table-floating-point-ranges945972 +Ref: Computer Arithmetic-Footnote-1946630 +Node: Math Definitions946687 +Ref: table-ieee-formats950003 +Ref: Math Definitions-Footnote-1950606 +Node: MPFR features950711 +Node: FP Math Caution952429 +Ref: FP Math Caution-Footnote-1953501 +Node: Inexactness of computations953870 +Node: Inexact representation954830 +Node: Comparing FP Values956190 +Node: Errors accumulate957431 +Node: Getting Accuracy958864 +Node: Try To Round961574 +Node: Setting precision962473 +Ref: table-predefined-precision-strings963170 +Node: Setting the rounding mode965000 +Ref: table-gawk-rounding-modes965374 +Ref: Setting the rounding mode-Footnote-1969305 +Node: Arbitrary Precision Integers969484 +Ref: Arbitrary Precision Integers-Footnote-1972659 +Node: Checking for MPFR972808 +Node: POSIX Floating Point Problems974282 +Ref: POSIX Floating Point Problems-Footnote-1978567 +Node: Floating point summary978605 +Node: Dynamic Extensions980795 +Node: Extension Intro982348 +Node: Plugin License983614 +Node: Extension Mechanism Outline984411 +Ref: figure-load-extension984850 +Ref: figure-register-new-function986415 +Ref: figure-call-new-function987507 +Node: Extension API Description989569 +Node: Extension API Functions Introduction991211 +Ref: table-api-std-headers993047 +Node: General Data Types996912 +Ref: General Data Types-Footnote-11005273 +Node: Memory Allocation Functions1005572 +Ref: Memory Allocation Functions-Footnote-11009782 +Node: Constructor Functions1009881 +Node: Registration Functions1013467 +Node: Extension Functions1014152 +Node: Exit Callback Functions1019474 +Node: Extension Version String1020724 +Node: Input Parsers1021387 +Node: Output Wrappers1034108 +Node: Two-way processors1038620 +Node: Printing Messages1040885 +Ref: Printing Messages-Footnote-11042056 +Node: Updating ERRNO1042209 +Node: Requesting Values1042948 +Ref: table-value-types-returned1043685 +Node: Accessing Parameters1044621 +Node: Symbol Table Access1045856 +Node: Symbol table by name1046368 +Ref: Symbol table by name-Footnote-11049392 +Node: Symbol table by cookie1049520 +Ref: Symbol table by cookie-Footnote-11053705 +Node: Cached values1053769 +Ref: Cached values-Footnote-11057305 +Node: Array Manipulation1057458 +Ref: Array Manipulation-Footnote-11058549 +Node: Array Data Types1058586 +Ref: Array Data Types-Footnote-11061244 +Node: Array Functions1061336 +Node: Flattening Arrays1065834 +Node: Creating Arrays1072810 +Node: Redirection API1077577 +Node: Extension API Variables1080410 +Node: Extension Versioning1081121 +Ref: gawk-api-version1081550 +Node: Extension GMP/MPFR Versioning1083281 +Node: Extension API Informational Variables1084909 +Node: Extension API Boilerplate1085982 +Node: Changes from API V11089956 +Node: Finding Extensions1091528 +Node: Extension Example1092087 +Node: Internal File Description1092885 +Node: Internal File Ops1096965 +Ref: Internal File Ops-Footnote-11108315 +Node: Using Internal File Ops1108455 +Ref: Using Internal File Ops-Footnote-11110838 +Node: Extension Samples1111112 +Node: Extension Sample File Functions1112641 +Node: Extension Sample Fnmatch1120290 +Node: Extension Sample Fork1121777 +Node: Extension Sample Inplace1122995 +Node: Extension Sample Ord1126620 +Node: Extension Sample Readdir1127456 +Ref: table-readdir-file-types1128345 +Node: Extension Sample Revout1129150 +Node: Extension Sample Rev2way1129739 +Node: Extension Sample Read write array1130479 +Node: Extension Sample Readfile1132421 +Node: Extension Sample Time1133516 +Node: Extension Sample API Tests1134864 +Node: gawkextlib1135356 +Node: Extension summary1138274 +Node: Extension Exercises1141976 +Node: Language History1143218 +Node: V7/SVR3.11144874 +Node: SVR41147026 +Node: POSIX1148460 +Node: BTL1149840 +Node: POSIX/GNU1150569 +Node: Feature History1156347 +Node: Common Extensions1172540 +Node: Ranges and Locales1173823 +Ref: Ranges and Locales-Footnote-11178439 +Ref: Ranges and Locales-Footnote-21178466 +Ref: Ranges and Locales-Footnote-31178701 +Node: Contributors1178922 +Node: History summary1184875 +Node: Installation1186255 +Node: Gawk Distribution1187199 +Node: Getting1187683 +Node: Extracting1188646 +Node: Distribution contents1190284 +Node: Unix Installation1196764 +Node: Quick Installation1197446 +Node: Shell Startup Files1199860 +Node: Additional Configuration Options1200949 +Node: Configuration Philosophy1203264 +Node: Non-Unix Installation1205633 +Node: PC Installation1206093 +Node: PC Binary Installation1206931 +Node: PC Compiling1207366 +Node: PC Using1208483 +Node: Cygwin1212036 +Node: MSYS1213135 +Node: VMS Installation1213636 +Node: VMS Compilation1214427 +Ref: VMS Compilation-Footnote-11215656 +Node: VMS Dynamic Extensions1215714 +Node: VMS Installation Details1217399 +Node: VMS Running1219652 +Node: VMS GNV1223931 +Node: VMS Old Gawk1224666 +Node: Bugs1225137 +Node: Bug address1225800 +Node: Usenet1228782 +Node: Maintainers1229786 +Node: Other Versions1231047 +Node: Installation summary1238135 +Node: Notes1239337 +Node: Compatibility Mode1240131 +Node: Additions1240913 +Node: Accessing The Source1241838 +Node: Adding Code1243275 +Node: New Ports1249494 +Node: Derived Files1253869 +Ref: Derived Files-Footnote-11259529 +Ref: Derived Files-Footnote-21259564 +Ref: Derived Files-Footnote-31260162 +Node: Future Extensions1260276 +Node: Implementation Limitations1260934 +Node: Extension Design1262117 +Node: Old Extension Problems1263261 +Ref: Old Extension Problems-Footnote-11264779 +Node: Extension New Mechanism Goals1264836 +Ref: Extension New Mechanism Goals-Footnote-11268200 +Node: Extension Other Design Decisions1268389 +Node: Extension Future Growth1270502 +Node: Notes summary1271338 +Node: Basic Concepts1272496 +Node: Basic High Level1273177 +Ref: figure-general-flow1273459 +Ref: figure-process-flow1274144 +Ref: Basic High Level-Footnote-11277445 +Node: Basic Data Typing1277630 +Node: Glossary1280958 +Node: Copying1312796 +Node: GNU Free Documentation License1350339 +Node: Index1375459 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 9c6f9e29..1d7ee3f4 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -5064,12 +5064,47 @@ $ @kbd{gawk -v LINENO=10 'BEGIN @{ print("hi" @}'} @section Summary @itemize @value{BULLET} + +@c From Neil R. Ormos @item -Use either -@samp{awk '@var{program}' @var{files}} -or -@samp{awk -f @var{program-file} @var{files}} -to run @command{awk}. +@command{gawk} parses arguments on the command line, left to right, to +determine if they should be treated as options or as non-option arguments. + +@item +@command{gawk} recognizes several options which control its operation, +as described in @ref{Options}. All options begin with @samp{-}. + +@item +Any argument that is not recognized as an option is treated as a +non-option argument, even if it begins with @samp{-}. + +@itemize @value{MINUS} +@item +However, when an option itself requires an argument, and the option is separated +from that argument on the command line by at least one space, the space +is ignored, and the argument is considered to be related to the option. Thus, in +the invocation, @samp{gawk -F x}, the @samp{x} is treated as belonging to the +@option{-F} option, not as a separate non-option argument. +@end itemize + +@item +Once @command{gawk} finds a non-option argument, it stops looking for +options. Therefore, all following arguments are also non-option arguments, +even if they resemble recognized options. + +@item +If no @option{-e} or @option{-f} options are present, @command{gawk} +expects the program text to be in the first non-option argument. + +@item +All non-option arguments, except program text provided in the first +non-option argument, are placed in @code{ARGV} as explained in +@ref{ARGC and ARGV}, and are processed as described in @ref{Other Arguments}. +@c And I wrote: +Adjusting @code{ARGC} and @code{ARGV} +affects how @command{awk} processes input. + +@c ---------------------------------------- @item The three standard options for all versions of @command{awk} are @@ -5083,11 +5118,6 @@ they are taken as variable assignments to be performed at that point in processing the input. @item -All nonoption command-line arguments, excluding the program text, -are placed in the @code{ARGV} array. Adjusting @code{ARGC} and @code{ARGV} -affects how @command{awk} processes input. - -@item You can use a single minus sign (@samp{-}) to refer to standard input on the command line. @command{gawk} also lets you use the special @value{FN} @file{/dev/stdin}. diff --git a/doc/gawktexi.in b/doc/gawktexi.in index b7dc972b..44927575 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -4974,12 +4974,47 @@ $ @kbd{gawk -v LINENO=10 'BEGIN @{ print("hi" @}'} @section Summary @itemize @value{BULLET} + +@c From Neil R. Ormos @item -Use either -@samp{awk '@var{program}' @var{files}} -or -@samp{awk -f @var{program-file} @var{files}} -to run @command{awk}. +@command{gawk} parses arguments on the command line, left to right, to +determine if they should be treated as options or as non-option arguments. + +@item +@command{gawk} recognizes several options which control its operation, +as described in @ref{Options}. All options begin with @samp{-}. + +@item +Any argument that is not recognized as an option is treated as a +non-option argument, even if it begins with @samp{-}. + +@itemize @value{MINUS} +@item +However, when an option itself requires an argument, and the option is separated +from that argument on the command line by at least one space, the space +is ignored, and the argument is considered to be related to the option. Thus, in +the invocation, @samp{gawk -F x}, the @samp{x} is treated as belonging to the +@option{-F} option, not as a separate non-option argument. +@end itemize + +@item +Once @command{gawk} finds a non-option argument, it stops looking for +options. Therefore, all following arguments are also non-option arguments, +even if they resemble recognized options. + +@item +If no @option{-e} or @option{-f} options are present, @command{gawk} +expects the program text to be in the first non-option argument. + +@item +All non-option arguments, except program text provided in the first +non-option argument, are placed in @code{ARGV} as explained in +@ref{ARGC and ARGV}, and are processed as described in @ref{Other Arguments}. +@c And I wrote: +Adjusting @code{ARGC} and @code{ARGV} +affects how @command{awk} processes input. + +@c ---------------------------------------- @item The three standard options for all versions of @command{awk} are @@ -4993,11 +5028,6 @@ they are taken as variable assignments to be performed at that point in processing the input. @item -All nonoption command-line arguments, excluding the program text, -are placed in the @code{ARGV} array. Adjusting @code{ARGC} and @code{ARGV} -affects how @command{awk} processes input. - -@item You can use a single minus sign (@samp{-}) to refer to standard input on the command line. @command{gawk} also lets you use the special @value{FN} @file{/dev/stdin}. |