diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 10 | ||||
| -rw-r--r-- | doc/gawk.info | 1235 | ||||
| -rw-r--r-- | doc/gawk.texi | 129 | ||||
| -rw-r--r-- | doc/gawktexi.in | 129 |
4 files changed, 931 insertions, 572 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 662b5b37..cb5b0cd2 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -11,6 +11,16 @@ * gawktexi.in (Bugs): Add that email should be in plain text and not in HTML. Sigh. +2015-05-11 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Add doc on conversions for strongly typed + regexp variables. + +2015-05-03 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Add initial documentation for strongly typed + regexps and for `typeof'. + 2015-04-29 Arnold D. Robbins <arnold@skeeve.com> * 4.1.2: Release tar ball made. diff --git a/doc/gawk.info b/doc/gawk.info index 11cbac55..6a2db963 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -175,6 +175,7 @@ in (a) below. A copy of the license is included in the section entitled * Computed Regexps:: Using Dynamic Regexps. * GNU Regexp Operators:: Operators specific to GNU software. * Case-sensitivity:: How to do case-insensitive matching. +* Strong Regexp Constants:: Strongly typed regexp constants. * Regexp Summary:: Regular expressions summary. * Records:: Controlling how data is split into records. @@ -3314,6 +3315,7 @@ you specify more complicated classes of strings. * Computed Regexps:: Using Dynamic Regexps. * GNU Regexp Operators:: Operators specific to GNU software. * Case-sensitivity:: How to do case-insensitive matching. +* Strong Regexp Constants:: Strongly typed regexp constants. * Regexp Summary:: Regular expressions summary. @@ -4016,7 +4018,7 @@ No options default. -File: gawk.info, Node: Case-sensitivity, Next: Regexp Summary, Prev: GNU Regexp Operators, Up: Regexp +File: gawk.info, Node: Case-sensitivity, Next: Strong Regexp Constants, Prev: GNU Regexp Operators, Up: Regexp 3.8 Case Sensitivity in Matching ================================ @@ -4090,10 +4092,77 @@ and we don't recommend it. that 'gawk' does the right thing. -File: gawk.info, Node: Regexp Summary, Prev: Case-sensitivity, Up: Regexp +File: gawk.info, Node: Strong Regexp Constants, Next: Regexp Summary, Prev: Case-sensitivity, Up: Regexp -3.9 Summary -=========== +3.9 Strongly Typed Regexp Constants +=================================== + +This minor node describes a 'gawk'-specific feature. + + Regexp constants ('/.../') hold a strange position in the 'awk' +language. In most contexts, they act like an expression: '$0 ~ /.../'. +In other contexts, they denote only a regexp to be matched. In no case +are they really a "first class citizen" of the language. That is, you +cannot define a scalar variable whose type is "regexp" in the same sense +that you can define a variable to be a number or a string: + + num = 42 Numeric variable + str = "hi" String variable + re = /foo/ Wrong! re is the result of $0 ~ /foo/ + + For a number of more advanced use cases (described later on in this +Info file), it would be nice to have regexp constants that are "strongly +typed"; in other words, that denote a regexp useful for matching, and +not an expression. + + 'gawk' provides this feature. A strongly typed regexp constant looks +almost like a regular regexp constant, except that it is preceded by an +'@' sign: + + re = @/foo/ Regexp variable + + Strongly typed regexp constants _cannot_ be used eveywhere that a +regular regexp constant can, because this would make the language even +more confusing. Instead, you may use them only in certain contexts: + + * On the righthand side of the '~' and '!~' operators: 'some_var ~ + @/foo/' (*note Regexp Usage::). + + * In the 'case' part of a 'switch' statement (*note Switch + Statement::). + + * As an argument to one of the built-in functions that accept regexp + constants: 'gensub()', 'gsub()', 'match()', 'patsplit()', + 'split()', and 'sub()' (*note String Functions::). + + * As a parameter in a call to a user-defined function (*note + User-defined::). + + * On the righthand side of an assignment to a variable: 'some_var = + @/foo/'. In this case, the type of 'some_var' is regexp. + Additionally, 'some_var' can be used with '~' and '!~', passed to + one of the built-in functions listed above, or passed as a + parameter to a user-defined function. + + You may use the 'typeof()' built-in function (*note Type Functions::) +to determine if a variable or function parameter is a regexp variable. + + The true power of this feature comes from the ability to create +variables that have regexp type. Such variables can be passed on to +user-defined functions, without the confusing aspects of computed +regular expressions created from strings or string constants. They may +also be passed through indirect function calls (*note Indirect Calls::) +onto the built-in functions that accept regexp constants. + + When used in numeric conversions, strongly typed regexp variables +convert to zero. When used in string conversions, they convert to the +string value of the original regexp text. + + +File: gawk.info, Node: Regexp Summary, Prev: Strong Regexp Constants, Up: Regexp + +3.10 Summary +============ * Regular expressions describe sets of strings to be matched. In 'awk', regular expression constants are written enclosed between @@ -4126,6 +4195,9 @@ File: gawk.info, Node: Regexp Summary, Prev: Case-sensitivity, Up: Regexp sensitivity of regexp matching. In other 'awk' versions, use 'tolower()' or 'toupper()'. + * Strongly typed regexp constants ('@/.../') enable certain advanced + use cases to be described later on in the Info file. + File: gawk.info, Node: Reading Files, Next: Printing, Prev: Regexp, Up: Top @@ -13438,14 +13510,33 @@ File: gawk.info, Node: Type Functions, Next: I18N Functions, Prev: Bitwise Fu 9.1.7 Getting Type Information ------------------------------ -'gawk' provides a single function that lets you distinguish an array -from a scalar variable. This is necessary for writing code that -traverses every element of an array of arrays (*note Arrays of -Arrays::). +'gawk' provides two functions that lets you distinguish the type of a +variable. This is necessary for writing code that traverses every +element of an array of arrays (*note Arrays of Arrays::), and in other +contexts. 'isarray(X)' Return a true value if X is an array. Otherwise, return false. +'typeof(X)' + Return one of the following strings, depending upon the type of X: + + '"array"' + X is an array. + + '"regexp"' + X is a strongly typed regexp (*note Strong Regexp + Constants::). + + '"scalar_n"' + X is a number. + + '"scalar_s"' + X is a string. + + '"untyped"' + X has not yet been given a type. + 'isarray()' is meant for use in two circumstances. The first is when traversing a multidimensional array: you can test if an element is itself an array or not. The second is inside the body of a user-defined @@ -13459,6 +13550,14 @@ parameter is an array or not. that has not been previously used to 'isarray()', 'gawk' ends up turning it into a scalar. + The 'typeof()' function is general; it allows you to determine if a +variable or function parameter is a scalar, an array, or a strongly +typed regexp. + + 'isarray()' is deprecated; you should use 'typeof()' instead. You +should replace any existing uses of 'isarray(var)' in your code with +'typeof(var) == "array"'. + File: gawk.info, Node: I18N Functions, Prev: Type Functions, Up: Built-in @@ -34743,6 +34842,8 @@ Index * trunc-mod operation: Arithmetic Ops. (line 66) * truth values: Truth Values. (line 6) * type conversion: Strings And Numbers. (line 21) +* type, of variable: Type Functions. (line 14) +* 'typeof': Type Functions. (line 14) * 'u' debugger command (alias for 'until'): Debugger Execution Control. (line 82) * unassigned array elements: Reference to Elements. @@ -34789,6 +34890,7 @@ Index * values, numeric: Basic Data Typing. (line 13) * values, string: Basic Data Typing. (line 13) * variable assignments and input files: Other Arguments. (line 26) +* variable type: Type Functions. (line 14) * variable typing: Typing and Comparison. (line 9) * variables: Other Features. (line 6) @@ -34889,563 +34991,564 @@ Index Tag Table: Node: Top1200 -Node: Foreword342435 -Node: Foreword446877 -Node: Preface48409 -Ref: Preface-Footnote-151281 -Ref: Preface-Footnote-251388 -Ref: Preface-Footnote-351622 -Node: History51764 -Node: Names54117 -Ref: Names-Footnote-155211 -Node: This Manual55358 -Ref: This Manual-Footnote-161840 -Node: Conventions61940 -Node: Manual History64295 -Ref: Manual History-Footnote-167291 -Ref: Manual History-Footnote-267332 -Node: How To Contribute67406 -Node: Acknowledgments68535 -Node: Getting Started73403 -Node: Running gawk75842 -Node: One-shot77032 -Node: Read Terminal78295 -Node: Long80327 -Node: Executable Scripts81840 -Ref: Executable Scripts-Footnote-184635 -Node: Comments84738 -Node: Quoting87222 -Node: DOS Quoting92740 -Node: Sample Data Files93415 -Node: Very Simple96010 -Node: Two Rules100912 -Node: More Complex102798 -Node: Statements/Lines105661 -Ref: Statements/Lines-Footnote-1110120 -Node: Other Features110385 -Node: When111322 -Ref: When-Footnote-1113076 -Node: Intro Summary113141 -Node: Invoking Gawk114025 -Node: Command Line115539 -Node: Options116337 -Ref: Options-Footnote-1132117 -Ref: Options-Footnote-2132347 -Node: Other Arguments132372 -Node: Naming Standard Input135319 -Node: Environment Variables136412 -Node: AWKPATH Variable136970 -Ref: AWKPATH Variable-Footnote-1140381 -Ref: AWKPATH Variable-Footnote-2140426 -Node: AWKLIBPATH Variable140687 -Node: Other Environment Variables141944 -Node: Exit Status145582 -Node: Include Files146259 -Node: Loading Shared Libraries149854 -Node: Obsolete151282 -Node: Undocumented151974 -Node: Invoking Summary152271 -Node: Regexp153931 -Node: Regexp Usage155385 -Node: Escape Sequences157422 -Node: Regexp Operators163655 -Ref: Regexp Operators-Footnote-1171072 -Ref: Regexp Operators-Footnote-2171219 -Node: Bracket Expressions171317 -Ref: table-char-classes173340 -Node: Leftmost Longest176286 -Node: Computed Regexps177589 -Node: GNU Regexp Operators181016 -Node: Case-sensitivity184695 -Ref: Case-sensitivity-Footnote-1187582 -Ref: Case-sensitivity-Footnote-2187817 -Node: Regexp Summary187925 -Node: Reading Files189391 -Node: Records191554 -Node: awk split records192287 -Node: gawk split records197219 -Ref: gawk split records-Footnote-1201763 -Node: Fields201800 -Ref: Fields-Footnote-1204580 -Node: Nonconstant Fields204666 -Ref: Nonconstant Fields-Footnote-1206902 -Node: Changing Fields207106 -Node: Field Separators213036 -Node: Default Field Splitting215734 -Node: Regexp Field Splitting216852 -Node: Single Character Fields220205 -Node: Command Line Field Separator221265 -Node: Full Line Fields224483 -Ref: Full Line Fields-Footnote-1226005 -Ref: Full Line Fields-Footnote-2226051 -Node: Field Splitting Summary226152 -Node: Constant Size228226 -Node: Splitting By Content232805 -Ref: Splitting By Content-Footnote-1236776 -Node: Multiple Line236939 -Ref: Multiple Line-Footnote-1242822 -Node: Getline243001 -Node: Plain Getline245468 -Node: Getline/Variable248107 -Node: Getline/File249256 -Node: Getline/Variable/File250642 -Ref: Getline/Variable/File-Footnote-1252246 -Node: Getline/Pipe252334 -Node: Getline/Variable/Pipe255039 -Node: Getline/Coprocess256172 -Node: Getline/Variable/Coprocess257437 -Node: Getline Notes258177 -Node: Getline Summary260972 -Ref: table-getline-variants261394 -Node: Read Timeout262142 -Ref: Read Timeout-Footnote-1266049 -Node: Retrying Input266107 -Node: Command-line directories267306 -Node: Input Summary268213 -Node: Input Exercises271385 -Node: Printing272113 -Node: Print273948 -Node: Print Examples275405 -Node: Output Separators278185 -Node: OFMT280202 -Node: Printf281558 -Node: Basic Printf282343 -Node: Control Letters283917 -Node: Format Modifiers287905 -Node: Printf Examples293920 -Node: Redirection296406 -Node: Special FD303249 -Ref: Special FD-Footnote-1306417 -Node: Special Files306491 -Node: Other Inherited Files307108 -Node: Special Network308109 -Node: Special Caveats308969 -Node: Close Files And Pipes309918 -Ref: Close Files And Pipes-Footnote-1317105 -Ref: Close Files And Pipes-Footnote-2317253 -Node: Nonfatal317404 -Node: Output Summary319729 -Node: Output Exercises320951 -Node: Expressions321630 -Node: Values322818 -Node: Constants323496 -Node: Scalar Constants324187 -Ref: Scalar Constants-Footnote-1325051 -Node: Nondecimal-numbers325301 -Node: Regexp Constants328315 -Node: Using Constant Regexps328841 -Node: Variables332004 -Node: Using Variables332661 -Node: Assignment Options334572 -Node: Conversion336446 -Node: Strings And Numbers336970 -Ref: Strings And Numbers-Footnote-1340034 -Node: Locale influences conversions340143 -Ref: table-locale-affects342901 -Node: All Operators343519 -Node: Arithmetic Ops344148 -Node: Concatenation346654 -Ref: Concatenation-Footnote-1349501 -Node: Assignment Ops349608 -Ref: table-assign-ops354600 -Node: Increment Ops355913 -Node: Truth Values and Conditions359373 -Node: Truth Values360447 -Node: Typing and Comparison361495 -Node: Variable Typing362315 -Node: Comparison Operators365939 -Ref: table-relational-ops366358 -Node: POSIX String Comparison369853 -Ref: POSIX String Comparison-Footnote-1370927 -Node: Boolean Ops371066 -Ref: Boolean Ops-Footnote-1375548 -Node: Conditional Exp375640 -Node: Function Calls377376 -Node: Precedence381256 -Node: Locales384915 -Node: Expressions Summary386547 -Node: Patterns and Actions389120 -Node: Pattern Overview390240 -Node: Regexp Patterns391917 -Node: Expression Patterns392459 -Node: Ranges396240 -Node: BEGIN/END399348 -Node: Using BEGIN/END400109 -Ref: Using BEGIN/END-Footnote-1402846 -Node: I/O And BEGIN/END402952 -Node: BEGINFILE/ENDFILE405268 -Node: Empty408175 -Node: Using Shell Variables408492 -Node: Action Overview410766 -Node: Statements413091 -Node: If Statement414939 -Node: While Statement416434 -Node: Do Statement418462 -Node: For Statement419610 -Node: Switch Statement422769 -Node: Break Statement425155 -Node: Continue Statement427247 -Node: Next Statement429074 -Node: Nextfile Statement431457 -Node: Exit Statement434109 -Node: Built-in Variables436514 -Node: User-modified437647 -Ref: User-modified-Footnote-1445274 -Node: Auto-set445336 -Ref: Auto-set-Footnote-1459585 -Ref: Auto-set-Footnote-2459791 -Node: ARGC and ARGV459847 -Node: Pattern Action Summary464066 -Node: Arrays466496 -Node: Array Basics467825 -Node: Array Intro468669 -Ref: figure-array-elements470644 -Ref: Array Intro-Footnote-1473356 -Node: Reference to Elements473484 -Node: Assigning Elements475948 -Node: Array Example476439 -Node: Scanning an Array478198 -Node: Controlling Scanning481222 -Ref: Controlling Scanning-Footnote-1486621 -Node: Numeric Array Subscripts486937 -Node: Uninitialized Subscripts489121 -Node: Delete490740 -Ref: Delete-Footnote-1493492 -Node: Multidimensional493549 -Node: Multiscanning496644 -Node: Arrays of Arrays498235 -Node: Arrays Summary503003 -Node: Functions505096 -Node: Built-in506134 -Node: Calling Built-in507212 -Node: Numeric Functions509208 -Ref: Numeric Functions-Footnote-1514041 -Ref: Numeric Functions-Footnote-2514398 -Ref: Numeric Functions-Footnote-3514446 -Node: String Functions514718 -Ref: String Functions-Footnote-1538226 -Ref: String Functions-Footnote-2538355 -Ref: String Functions-Footnote-3538603 -Node: Gory Details538690 -Ref: table-sub-escapes540481 -Ref: table-sub-proposed542000 -Ref: table-posix-sub543363 -Ref: table-gensub-escapes544904 -Ref: Gory Details-Footnote-1545727 -Node: I/O Functions545878 -Ref: I/O Functions-Footnote-1553099 -Node: Time Functions553247 -Ref: Time Functions-Footnote-1563752 -Ref: Time Functions-Footnote-2563820 -Ref: Time Functions-Footnote-3563978 -Ref: Time Functions-Footnote-4564089 -Ref: Time Functions-Footnote-5564201 -Ref: Time Functions-Footnote-6564428 -Node: Bitwise Functions564694 -Ref: table-bitwise-ops565288 -Ref: Bitwise Functions-Footnote-1569596 -Node: Type Functions569769 -Node: I18N Functions570925 -Node: User-defined572576 -Node: Definition Syntax573381 -Ref: Definition Syntax-Footnote-1579068 -Node: Function Example579139 -Ref: Function Example-Footnote-1582061 -Node: Function Caveats582083 -Node: Calling A Function582601 -Node: Variable Scope583559 -Node: Pass By Value/Reference586553 -Node: Return Statement590052 -Node: Dynamic Typing593031 -Node: Indirect Calls593961 -Ref: Indirect Calls-Footnote-1604212 -Node: Functions Summary604340 -Node: Library Functions607045 -Ref: Library Functions-Footnote-1610654 -Ref: Library Functions-Footnote-2610797 -Node: Library Names610968 -Ref: Library Names-Footnote-1614429 -Ref: Library Names-Footnote-2614652 -Node: General Functions614738 -Node: Strtonum Function615841 -Node: Assert Function618863 -Node: Round Function622189 -Node: Cliff Random Function623730 -Node: Ordinal Functions624746 -Ref: Ordinal Functions-Footnote-1627809 -Ref: Ordinal Functions-Footnote-2628061 -Node: Join Function628271 -Ref: Join Function-Footnote-1630041 -Node: Getlocaltime Function630241 -Node: Readfile Function633985 -Node: Shell Quoting635959 -Node: Data File Management637360 -Node: Filetrans Function637992 -Node: Rewind Function642089 -Node: File Checking643475 -Ref: File Checking-Footnote-1644809 -Node: Empty Files645010 -Node: Ignoring Assigns646989 -Node: Getopt Function648539 -Ref: Getopt Function-Footnote-1660009 -Node: Passwd Functions660209 -Ref: Passwd Functions-Footnote-1669050 -Node: Group Functions669138 -Ref: Group Functions-Footnote-1677037 -Node: Walking Arrays677244 -Node: Library Functions Summary680254 -Node: Library Exercises681660 -Node: Sample Programs682939 -Node: Running Examples683709 -Node: Clones684437 -Node: Cut Program685661 -Node: Egrep Program695382 -Ref: Egrep Program-Footnote-1702894 -Node: Id Program703004 -Node: Split Program706684 -Ref: Split Program-Footnote-1710143 -Node: Tee Program710272 -Node: Uniq Program713062 -Node: Wc Program720488 -Ref: Wc Program-Footnote-1724743 -Node: Miscellaneous Programs724837 -Node: Dupword Program726050 -Node: Alarm Program728080 -Node: Translate Program732935 -Ref: Translate Program-Footnote-1737500 -Node: Labels Program737770 -Ref: Labels Program-Footnote-1741121 -Node: Word Sorting741205 -Node: History Sorting745277 -Node: Extract Program747112 -Node: Simple Sed754643 -Node: Igawk Program757717 -Ref: Igawk Program-Footnote-1772048 -Ref: Igawk Program-Footnote-2772250 -Ref: Igawk Program-Footnote-3772372 -Node: Anagram Program772487 -Node: Signature Program775549 -Node: Programs Summary776796 -Node: Programs Exercises778011 -Ref: Programs Exercises-Footnote-1782140 -Node: Advanced Features782231 -Node: Nondecimal Data784221 -Node: Array Sorting785812 -Node: Controlling Array Traversal786512 -Ref: Controlling Array Traversal-Footnote-1794881 -Node: Array Sorting Functions794999 -Ref: Array Sorting Functions-Footnote-1798886 -Node: Two-way I/O799082 -Ref: Two-way I/O-Footnote-1804033 -Ref: Two-way I/O-Footnote-2804220 -Node: TCP/IP Networking804302 -Node: Profiling807209 -Node: Advanced Features Summary815480 -Node: Internationalization817416 -Node: I18N and L10N818896 -Node: Explaining gettext819583 -Ref: Explaining gettext-Footnote-1824606 -Ref: Explaining gettext-Footnote-2824791 -Node: Programmer i18n824956 -Ref: Programmer i18n-Footnote-1829812 -Node: Translator i18n829861 -Node: String Extraction830655 -Ref: String Extraction-Footnote-1831788 -Node: Printf Ordering831874 -Ref: Printf Ordering-Footnote-1834660 -Node: I18N Portability834724 -Ref: I18N Portability-Footnote-1837180 -Node: I18N Example837243 -Ref: I18N Example-Footnote-1840049 -Node: Gawk I18N840122 -Node: I18N Summary840767 -Node: Debugger842108 -Node: Debugging843130 -Node: Debugging Concepts843571 -Node: Debugging Terms845380 -Node: Awk Debugging847955 -Node: Sample Debugging Session848861 -Node: Debugger Invocation849395 -Node: Finding The Bug850781 -Node: List of Debugger Commands857259 -Node: Breakpoint Control858592 -Node: Debugger Execution Control862286 -Node: Viewing And Changing Data865648 -Node: Execution Stack869022 -Node: Debugger Info870659 -Node: Miscellaneous Debugger Commands874730 -Node: Readline Support879739 -Node: Limitations880635 -Node: Debugging Summary882744 -Node: Arbitrary Precision Arithmetic883917 -Node: Computer Arithmetic885333 -Ref: table-numeric-ranges888924 -Ref: Computer Arithmetic-Footnote-1889646 -Node: Math Definitions889703 -Ref: table-ieee-formats893017 -Ref: Math Definitions-Footnote-1893620 -Node: MPFR features893725 -Node: FP Math Caution895398 -Ref: FP Math Caution-Footnote-1896470 -Node: Inexactness of computations896839 -Node: Inexact representation897799 -Node: Comparing FP Values899159 -Node: Errors accumulate900241 -Node: Getting Accuracy901674 -Node: Try To Round904384 -Node: Setting precision905283 -Ref: table-predefined-precision-strings905980 -Node: Setting the rounding mode907810 -Ref: table-gawk-rounding-modes908184 -Ref: Setting the rounding mode-Footnote-1911592 -Node: Arbitrary Precision Integers911771 -Ref: Arbitrary Precision Integers-Footnote-1916688 -Node: POSIX Floating Point Problems916837 -Ref: POSIX Floating Point Problems-Footnote-1920719 -Node: Floating point summary920757 -Node: Dynamic Extensions922947 -Node: Extension Intro924500 -Node: Plugin License925766 -Node: Extension Mechanism Outline926563 -Ref: figure-load-extension927002 -Ref: figure-register-new-function928567 -Ref: figure-call-new-function929659 -Node: Extension API Description931722 -Node: Extension API Functions Introduction933256 -Node: General Data Types938115 -Ref: General Data Types-Footnote-1944070 -Node: Memory Allocation Functions944369 -Ref: Memory Allocation Functions-Footnote-1947214 -Node: Constructor Functions947313 -Node: Registration Functions949058 -Node: Extension Functions949743 -Node: Exit Callback Functions952042 -Node: Extension Version String953292 -Node: Input Parsers953955 -Node: Output Wrappers963840 -Node: Two-way processors968352 -Node: Printing Messages970616 -Ref: Printing Messages-Footnote-1971692 -Node: Updating 'ERRNO'971845 -Node: Requesting Values972586 -Ref: table-value-types-returned973325 -Node: Accessing Parameters974208 -Node: Symbol Table Access975444 -Node: Symbol table by name975956 -Node: Symbol table by cookie977977 -Ref: Symbol table by cookie-Footnote-1982126 -Node: Cached values982190 -Ref: Cached values-Footnote-1985691 -Node: Array Manipulation985782 -Ref: Array Manipulation-Footnote-1986873 -Node: Array Data Types986910 -Ref: Array Data Types-Footnote-1989568 -Node: Array Functions989660 -Node: Flattening Arrays993519 -Node: Creating Arrays1000427 -Node: Redirection API1005199 -Node: Extension API Variables1008030 -Node: Extension Versioning1008663 -Node: Extension API Informational Variables1010554 -Node: Extension API Boilerplate1011618 -Node: Finding Extensions1015432 -Node: Extension Example1015992 -Node: Internal File Description1016790 -Node: Internal File Ops1020870 -Ref: Internal File Ops-Footnote-11032632 -Node: Using Internal File Ops1032772 -Ref: Using Internal File Ops-Footnote-11035155 -Node: Extension Samples1035430 -Node: Extension Sample File Functions1036959 -Node: Extension Sample Fnmatch1044608 -Node: Extension Sample Fork1046095 -Node: Extension Sample Inplace1047313 -Node: Extension Sample Ord1049399 -Node: Extension Sample Readdir1050235 -Ref: table-readdir-file-types1051124 -Node: Extension Sample Revout1051929 -Node: Extension Sample Rev2way1052518 -Node: Extension Sample Read write array1053258 -Node: Extension Sample Readfile1055200 -Node: Extension Sample Time1056295 -Node: Extension Sample API Tests1057643 -Node: gawkextlib1058135 -Node: Extension summary1060582 -Node: Extension Exercises1064274 -Node: Language History1065771 -Node: V7/SVR3.11067427 -Node: SVR41069580 -Node: POSIX1071014 -Node: BTL1072394 -Node: POSIX/GNU1073124 -Node: Feature History1078963 -Node: Common Extensions1092954 -Node: Ranges and Locales1094237 -Ref: Ranges and Locales-Footnote-11098853 -Ref: Ranges and Locales-Footnote-21098880 -Ref: Ranges and Locales-Footnote-31099115 -Node: Contributors1099336 -Node: History summary1104905 -Node: Installation1106285 -Node: Gawk Distribution1107230 -Node: Getting1107714 -Node: Extracting1108537 -Node: Distribution contents1110175 -Node: Unix Installation1116271 -Node: Quick Installation1116953 -Node: Shell Startup Files1119367 -Node: Additional Configuration Options1120445 -Node: Configuration Philosophy1122250 -Node: Non-Unix Installation1124620 -Node: PC Installation1125078 -Node: PC Binary Installation1126398 -Node: PC Compiling1128250 -Ref: PC Compiling-Footnote-11131274 -Node: PC Testing1131383 -Node: PC Using1132563 -Node: Cygwin1136677 -Node: MSYS1137447 -Node: VMS Installation1137948 -Node: VMS Compilation1138739 -Ref: VMS Compilation-Footnote-11139969 -Node: VMS Dynamic Extensions1140027 -Node: VMS Installation Details1141712 -Node: VMS Running1143965 -Node: VMS GNV1146806 -Node: VMS Old Gawk1147541 -Node: Bugs1148012 -Node: Other Versions1152126 -Node: Installation summary1158600 -Node: Notes1159658 -Node: Compatibility Mode1160523 -Node: Additions1161305 -Node: Accessing The Source1162230 -Node: Adding Code1163666 -Node: New Ports1169821 -Node: Derived Files1174309 -Ref: Derived Files-Footnote-11179794 -Ref: Derived Files-Footnote-21179829 -Ref: Derived Files-Footnote-31180427 -Node: Future Extensions1180541 -Node: Implementation Limitations1181199 -Node: Extension Design1182382 -Node: Old Extension Problems1183536 -Ref: Old Extension Problems-Footnote-11185054 -Node: Extension New Mechanism Goals1185111 -Ref: Extension New Mechanism Goals-Footnote-11188475 -Node: Extension Other Design Decisions1188664 -Node: Extension Future Growth1190777 -Node: Old Extension Mechanism1191613 -Node: Notes summary1193376 -Node: Basic Concepts1194558 -Node: Basic High Level1195239 -Ref: figure-general-flow1195521 -Ref: figure-process-flow1196206 -Ref: Basic High Level-Footnote-11199507 -Node: Basic Data Typing1199692 -Node: Glossary1203020 -Node: Copying1234966 -Node: GNU Free Documentation License1272505 -Node: Index1297623 +Node: Foreword342508 +Node: Foreword446950 +Node: Preface48482 +Ref: Preface-Footnote-151354 +Ref: Preface-Footnote-251461 +Ref: Preface-Footnote-351695 +Node: History51837 +Node: Names54190 +Ref: Names-Footnote-155284 +Node: This Manual55431 +Ref: This Manual-Footnote-161913 +Node: Conventions62013 +Node: Manual History64368 +Ref: Manual History-Footnote-167364 +Ref: Manual History-Footnote-267405 +Node: How To Contribute67479 +Node: Acknowledgments68608 +Node: Getting Started73476 +Node: Running gawk75915 +Node: One-shot77105 +Node: Read Terminal78368 +Node: Long80400 +Node: Executable Scripts81913 +Ref: Executable Scripts-Footnote-184708 +Node: Comments84811 +Node: Quoting87295 +Node: DOS Quoting92813 +Node: Sample Data Files93488 +Node: Very Simple96083 +Node: Two Rules100985 +Node: More Complex102871 +Node: Statements/Lines105734 +Ref: Statements/Lines-Footnote-1110193 +Node: Other Features110458 +Node: When111395 +Ref: When-Footnote-1113149 +Node: Intro Summary113214 +Node: Invoking Gawk114098 +Node: Command Line115612 +Node: Options116410 +Ref: Options-Footnote-1132190 +Ref: Options-Footnote-2132420 +Node: Other Arguments132445 +Node: Naming Standard Input135392 +Node: Environment Variables136485 +Node: AWKPATH Variable137043 +Ref: AWKPATH Variable-Footnote-1140454 +Ref: AWKPATH Variable-Footnote-2140499 +Node: AWKLIBPATH Variable140760 +Node: Other Environment Variables142017 +Node: Exit Status145655 +Node: Include Files146332 +Node: Loading Shared Libraries149927 +Node: Obsolete151355 +Node: Undocumented152047 +Node: Invoking Summary152344 +Node: Regexp154004 +Node: Regexp Usage155523 +Node: Escape Sequences157560 +Node: Regexp Operators163793 +Ref: Regexp Operators-Footnote-1171210 +Ref: Regexp Operators-Footnote-2171357 +Node: Bracket Expressions171455 +Ref: table-char-classes173478 +Node: Leftmost Longest176424 +Node: Computed Regexps177727 +Node: GNU Regexp Operators181154 +Node: Case-sensitivity184833 +Ref: Case-sensitivity-Footnote-1187729 +Ref: Case-sensitivity-Footnote-2187964 +Node: Strong Regexp Constants188072 +Node: Regexp Summary191014 +Node: Reading Files192620 +Node: Records194783 +Node: awk split records195516 +Node: gawk split records200448 +Ref: gawk split records-Footnote-1204992 +Node: Fields205029 +Ref: Fields-Footnote-1207809 +Node: Nonconstant Fields207895 +Ref: Nonconstant Fields-Footnote-1210131 +Node: Changing Fields210335 +Node: Field Separators216265 +Node: Default Field Splitting218963 +Node: Regexp Field Splitting220081 +Node: Single Character Fields223434 +Node: Command Line Field Separator224494 +Node: Full Line Fields227712 +Ref: Full Line Fields-Footnote-1229234 +Ref: Full Line Fields-Footnote-2229280 +Node: Field Splitting Summary229381 +Node: Constant Size231455 +Node: Splitting By Content236034 +Ref: Splitting By Content-Footnote-1240005 +Node: Multiple Line240168 +Ref: Multiple Line-Footnote-1246051 +Node: Getline246230 +Node: Plain Getline248697 +Node: Getline/Variable251336 +Node: Getline/File252485 +Node: Getline/Variable/File253871 +Ref: Getline/Variable/File-Footnote-1255475 +Node: Getline/Pipe255563 +Node: Getline/Variable/Pipe258268 +Node: Getline/Coprocess259401 +Node: Getline/Variable/Coprocess260666 +Node: Getline Notes261406 +Node: Getline Summary264201 +Ref: table-getline-variants264623 +Node: Read Timeout265371 +Ref: Read Timeout-Footnote-1269278 +Node: Retrying Input269336 +Node: Command-line directories270535 +Node: Input Summary271442 +Node: Input Exercises274614 +Node: Printing275342 +Node: Print277177 +Node: Print Examples278634 +Node: Output Separators281414 +Node: OFMT283431 +Node: Printf284787 +Node: Basic Printf285572 +Node: Control Letters287146 +Node: Format Modifiers291134 +Node: Printf Examples297149 +Node: Redirection299635 +Node: Special FD306478 +Ref: Special FD-Footnote-1309646 +Node: Special Files309720 +Node: Other Inherited Files310337 +Node: Special Network311338 +Node: Special Caveats312198 +Node: Close Files And Pipes313147 +Ref: Close Files And Pipes-Footnote-1320334 +Ref: Close Files And Pipes-Footnote-2320482 +Node: Nonfatal320633 +Node: Output Summary322958 +Node: Output Exercises324180 +Node: Expressions324859 +Node: Values326047 +Node: Constants326725 +Node: Scalar Constants327416 +Ref: Scalar Constants-Footnote-1328280 +Node: Nondecimal-numbers328530 +Node: Regexp Constants331544 +Node: Using Constant Regexps332070 +Node: Variables335233 +Node: Using Variables335890 +Node: Assignment Options337801 +Node: Conversion339675 +Node: Strings And Numbers340199 +Ref: Strings And Numbers-Footnote-1343263 +Node: Locale influences conversions343372 +Ref: table-locale-affects346130 +Node: All Operators346748 +Node: Arithmetic Ops347377 +Node: Concatenation349883 +Ref: Concatenation-Footnote-1352730 +Node: Assignment Ops352837 +Ref: table-assign-ops357829 +Node: Increment Ops359142 +Node: Truth Values and Conditions362602 +Node: Truth Values363676 +Node: Typing and Comparison364724 +Node: Variable Typing365544 +Node: Comparison Operators369168 +Ref: table-relational-ops369587 +Node: POSIX String Comparison373082 +Ref: POSIX String Comparison-Footnote-1374156 +Node: Boolean Ops374295 +Ref: Boolean Ops-Footnote-1378777 +Node: Conditional Exp378869 +Node: Function Calls380605 +Node: Precedence384485 +Node: Locales388144 +Node: Expressions Summary389776 +Node: Patterns and Actions392349 +Node: Pattern Overview393469 +Node: Regexp Patterns395146 +Node: Expression Patterns395688 +Node: Ranges399469 +Node: BEGIN/END402577 +Node: Using BEGIN/END403338 +Ref: Using BEGIN/END-Footnote-1406075 +Node: I/O And BEGIN/END406181 +Node: BEGINFILE/ENDFILE408497 +Node: Empty411404 +Node: Using Shell Variables411721 +Node: Action Overview413995 +Node: Statements416320 +Node: If Statement418168 +Node: While Statement419663 +Node: Do Statement421691 +Node: For Statement422839 +Node: Switch Statement425998 +Node: Break Statement428384 +Node: Continue Statement430476 +Node: Next Statement432303 +Node: Nextfile Statement434686 +Node: Exit Statement437338 +Node: Built-in Variables439743 +Node: User-modified440876 +Ref: User-modified-Footnote-1448503 +Node: Auto-set448565 +Ref: Auto-set-Footnote-1462814 +Ref: Auto-set-Footnote-2463020 +Node: ARGC and ARGV463076 +Node: Pattern Action Summary467295 +Node: Arrays469725 +Node: Array Basics471054 +Node: Array Intro471898 +Ref: figure-array-elements473873 +Ref: Array Intro-Footnote-1476585 +Node: Reference to Elements476713 +Node: Assigning Elements479177 +Node: Array Example479668 +Node: Scanning an Array481427 +Node: Controlling Scanning484451 +Ref: Controlling Scanning-Footnote-1489850 +Node: Numeric Array Subscripts490166 +Node: Uninitialized Subscripts492350 +Node: Delete493969 +Ref: Delete-Footnote-1496721 +Node: Multidimensional496778 +Node: Multiscanning499873 +Node: Arrays of Arrays501464 +Node: Arrays Summary506232 +Node: Functions508325 +Node: Built-in509363 +Node: Calling Built-in510441 +Node: Numeric Functions512437 +Ref: Numeric Functions-Footnote-1517270 +Ref: Numeric Functions-Footnote-2517627 +Ref: Numeric Functions-Footnote-3517675 +Node: String Functions517947 +Ref: String Functions-Footnote-1541455 +Ref: String Functions-Footnote-2541584 +Ref: String Functions-Footnote-3541832 +Node: Gory Details541919 +Ref: table-sub-escapes543710 +Ref: table-sub-proposed545229 +Ref: table-posix-sub546592 +Ref: table-gensub-escapes548133 +Ref: Gory Details-Footnote-1548956 +Node: I/O Functions549107 +Ref: I/O Functions-Footnote-1556328 +Node: Time Functions556476 +Ref: Time Functions-Footnote-1566981 +Ref: Time Functions-Footnote-2567049 +Ref: Time Functions-Footnote-3567207 +Ref: Time Functions-Footnote-4567318 +Ref: Time Functions-Footnote-5567430 +Ref: Time Functions-Footnote-6567657 +Node: Bitwise Functions567923 +Ref: table-bitwise-ops568517 +Ref: Bitwise Functions-Footnote-1572825 +Node: Type Functions572998 +Node: I18N Functions574860 +Node: User-defined576511 +Node: Definition Syntax577316 +Ref: Definition Syntax-Footnote-1583003 +Node: Function Example583074 +Ref: Function Example-Footnote-1585996 +Node: Function Caveats586018 +Node: Calling A Function586536 +Node: Variable Scope587494 +Node: Pass By Value/Reference590488 +Node: Return Statement593987 +Node: Dynamic Typing596966 +Node: Indirect Calls597896 +Ref: Indirect Calls-Footnote-1608147 +Node: Functions Summary608275 +Node: Library Functions610980 +Ref: Library Functions-Footnote-1614589 +Ref: Library Functions-Footnote-2614732 +Node: Library Names614903 +Ref: Library Names-Footnote-1618364 +Ref: Library Names-Footnote-2618587 +Node: General Functions618673 +Node: Strtonum Function619776 +Node: Assert Function622798 +Node: Round Function626124 +Node: Cliff Random Function627665 +Node: Ordinal Functions628681 +Ref: Ordinal Functions-Footnote-1631744 +Ref: Ordinal Functions-Footnote-2631996 +Node: Join Function632206 +Ref: Join Function-Footnote-1633976 +Node: Getlocaltime Function634176 +Node: Readfile Function637920 +Node: Shell Quoting639894 +Node: Data File Management641295 +Node: Filetrans Function641927 +Node: Rewind Function646024 +Node: File Checking647410 +Ref: File Checking-Footnote-1648744 +Node: Empty Files648945 +Node: Ignoring Assigns650924 +Node: Getopt Function652474 +Ref: Getopt Function-Footnote-1663944 +Node: Passwd Functions664144 +Ref: Passwd Functions-Footnote-1672985 +Node: Group Functions673073 +Ref: Group Functions-Footnote-1680972 +Node: Walking Arrays681179 +Node: Library Functions Summary684189 +Node: Library Exercises685595 +Node: Sample Programs686874 +Node: Running Examples687644 +Node: Clones688372 +Node: Cut Program689596 +Node: Egrep Program699317 +Ref: Egrep Program-Footnote-1706829 +Node: Id Program706939 +Node: Split Program710619 +Ref: Split Program-Footnote-1714078 +Node: Tee Program714207 +Node: Uniq Program716997 +Node: Wc Program724423 +Ref: Wc Program-Footnote-1728678 +Node: Miscellaneous Programs728772 +Node: Dupword Program729985 +Node: Alarm Program732015 +Node: Translate Program736870 +Ref: Translate Program-Footnote-1741435 +Node: Labels Program741705 +Ref: Labels Program-Footnote-1745056 +Node: Word Sorting745140 +Node: History Sorting749212 +Node: Extract Program751047 +Node: Simple Sed758578 +Node: Igawk Program761652 +Ref: Igawk Program-Footnote-1775983 +Ref: Igawk Program-Footnote-2776185 +Ref: Igawk Program-Footnote-3776307 +Node: Anagram Program776422 +Node: Signature Program779484 +Node: Programs Summary780731 +Node: Programs Exercises781946 +Ref: Programs Exercises-Footnote-1786075 +Node: Advanced Features786166 +Node: Nondecimal Data788156 +Node: Array Sorting789747 +Node: Controlling Array Traversal790447 +Ref: Controlling Array Traversal-Footnote-1798816 +Node: Array Sorting Functions798934 +Ref: Array Sorting Functions-Footnote-1802821 +Node: Two-way I/O803017 +Ref: Two-way I/O-Footnote-1807968 +Ref: Two-way I/O-Footnote-2808155 +Node: TCP/IP Networking808237 +Node: Profiling811144 +Node: Advanced Features Summary819415 +Node: Internationalization821351 +Node: I18N and L10N822831 +Node: Explaining gettext823518 +Ref: Explaining gettext-Footnote-1828541 +Ref: Explaining gettext-Footnote-2828726 +Node: Programmer i18n828891 +Ref: Programmer i18n-Footnote-1833747 +Node: Translator i18n833796 +Node: String Extraction834590 +Ref: String Extraction-Footnote-1835723 +Node: Printf Ordering835809 +Ref: Printf Ordering-Footnote-1838595 +Node: I18N Portability838659 +Ref: I18N Portability-Footnote-1841115 +Node: I18N Example841178 +Ref: I18N Example-Footnote-1843984 +Node: Gawk I18N844057 +Node: I18N Summary844702 +Node: Debugger846043 +Node: Debugging847065 +Node: Debugging Concepts847506 +Node: Debugging Terms849315 +Node: Awk Debugging851890 +Node: Sample Debugging Session852796 +Node: Debugger Invocation853330 +Node: Finding The Bug854716 +Node: List of Debugger Commands861194 +Node: Breakpoint Control862527 +Node: Debugger Execution Control866221 +Node: Viewing And Changing Data869583 +Node: Execution Stack872957 +Node: Debugger Info874594 +Node: Miscellaneous Debugger Commands878665 +Node: Readline Support883674 +Node: Limitations884570 +Node: Debugging Summary886679 +Node: Arbitrary Precision Arithmetic887852 +Node: Computer Arithmetic889268 +Ref: table-numeric-ranges892859 +Ref: Computer Arithmetic-Footnote-1893581 +Node: Math Definitions893638 +Ref: table-ieee-formats896952 +Ref: Math Definitions-Footnote-1897555 +Node: MPFR features897660 +Node: FP Math Caution899333 +Ref: FP Math Caution-Footnote-1900405 +Node: Inexactness of computations900774 +Node: Inexact representation901734 +Node: Comparing FP Values903094 +Node: Errors accumulate904176 +Node: Getting Accuracy905609 +Node: Try To Round908319 +Node: Setting precision909218 +Ref: table-predefined-precision-strings909915 +Node: Setting the rounding mode911745 +Ref: table-gawk-rounding-modes912119 +Ref: Setting the rounding mode-Footnote-1915527 +Node: Arbitrary Precision Integers915706 +Ref: Arbitrary Precision Integers-Footnote-1920623 +Node: POSIX Floating Point Problems920772 +Ref: POSIX Floating Point Problems-Footnote-1924654 +Node: Floating point summary924692 +Node: Dynamic Extensions926882 +Node: Extension Intro928435 +Node: Plugin License929701 +Node: Extension Mechanism Outline930498 +Ref: figure-load-extension930937 +Ref: figure-register-new-function932502 +Ref: figure-call-new-function933594 +Node: Extension API Description935657 +Node: Extension API Functions Introduction937191 +Node: General Data Types942050 +Ref: General Data Types-Footnote-1948005 +Node: Memory Allocation Functions948304 +Ref: Memory Allocation Functions-Footnote-1951149 +Node: Constructor Functions951248 +Node: Registration Functions952993 +Node: Extension Functions953678 +Node: Exit Callback Functions955977 +Node: Extension Version String957227 +Node: Input Parsers957890 +Node: Output Wrappers967775 +Node: Two-way processors972287 +Node: Printing Messages974551 +Ref: Printing Messages-Footnote-1975627 +Node: Updating 'ERRNO'975780 +Node: Requesting Values976521 +Ref: table-value-types-returned977260 +Node: Accessing Parameters978143 +Node: Symbol Table Access979379 +Node: Symbol table by name979891 +Node: Symbol table by cookie981912 +Ref: Symbol table by cookie-Footnote-1986061 +Node: Cached values986125 +Ref: Cached values-Footnote-1989626 +Node: Array Manipulation989717 +Ref: Array Manipulation-Footnote-1990808 +Node: Array Data Types990845 +Ref: Array Data Types-Footnote-1993503 +Node: Array Functions993595 +Node: Flattening Arrays997454 +Node: Creating Arrays1004362 +Node: Redirection API1009134 +Node: Extension API Variables1011965 +Node: Extension Versioning1012598 +Node: Extension API Informational Variables1014489 +Node: Extension API Boilerplate1015553 +Node: Finding Extensions1019367 +Node: Extension Example1019927 +Node: Internal File Description1020725 +Node: Internal File Ops1024805 +Ref: Internal File Ops-Footnote-11036567 +Node: Using Internal File Ops1036707 +Ref: Using Internal File Ops-Footnote-11039090 +Node: Extension Samples1039365 +Node: Extension Sample File Functions1040894 +Node: Extension Sample Fnmatch1048543 +Node: Extension Sample Fork1050030 +Node: Extension Sample Inplace1051248 +Node: Extension Sample Ord1053334 +Node: Extension Sample Readdir1054170 +Ref: table-readdir-file-types1055059 +Node: Extension Sample Revout1055864 +Node: Extension Sample Rev2way1056453 +Node: Extension Sample Read write array1057193 +Node: Extension Sample Readfile1059135 +Node: Extension Sample Time1060230 +Node: Extension Sample API Tests1061578 +Node: gawkextlib1062070 +Node: Extension summary1064517 +Node: Extension Exercises1068209 +Node: Language History1069706 +Node: V7/SVR3.11071362 +Node: SVR41073515 +Node: POSIX1074949 +Node: BTL1076329 +Node: POSIX/GNU1077059 +Node: Feature History1082898 +Node: Common Extensions1096889 +Node: Ranges and Locales1098172 +Ref: Ranges and Locales-Footnote-11102788 +Ref: Ranges and Locales-Footnote-21102815 +Ref: Ranges and Locales-Footnote-31103050 +Node: Contributors1103271 +Node: History summary1108840 +Node: Installation1110220 +Node: Gawk Distribution1111165 +Node: Getting1111649 +Node: Extracting1112472 +Node: Distribution contents1114110 +Node: Unix Installation1120206 +Node: Quick Installation1120888 +Node: Shell Startup Files1123302 +Node: Additional Configuration Options1124380 +Node: Configuration Philosophy1126185 +Node: Non-Unix Installation1128555 +Node: PC Installation1129013 +Node: PC Binary Installation1130333 +Node: PC Compiling1132185 +Ref: PC Compiling-Footnote-11135209 +Node: PC Testing1135318 +Node: PC Using1136498 +Node: Cygwin1140612 +Node: MSYS1141382 +Node: VMS Installation1141883 +Node: VMS Compilation1142674 +Ref: VMS Compilation-Footnote-11143904 +Node: VMS Dynamic Extensions1143962 +Node: VMS Installation Details1145647 +Node: VMS Running1147900 +Node: VMS GNV1150741 +Node: VMS Old Gawk1151476 +Node: Bugs1151947 +Node: Other Versions1156061 +Node: Installation summary1162535 +Node: Notes1163593 +Node: Compatibility Mode1164458 +Node: Additions1165240 +Node: Accessing The Source1166165 +Node: Adding Code1167601 +Node: New Ports1173756 +Node: Derived Files1178244 +Ref: Derived Files-Footnote-11183729 +Ref: Derived Files-Footnote-21183764 +Ref: Derived Files-Footnote-31184362 +Node: Future Extensions1184476 +Node: Implementation Limitations1185134 +Node: Extension Design1186317 +Node: Old Extension Problems1187471 +Ref: Old Extension Problems-Footnote-11188989 +Node: Extension New Mechanism Goals1189046 +Ref: Extension New Mechanism Goals-Footnote-11192410 +Node: Extension Other Design Decisions1192599 +Node: Extension Future Growth1194712 +Node: Old Extension Mechanism1195548 +Node: Notes summary1197311 +Node: Basic Concepts1198493 +Node: Basic High Level1199174 +Ref: figure-general-flow1199456 +Ref: figure-process-flow1200141 +Ref: Basic High Level-Footnote-11203442 +Node: Basic Data Typing1203627 +Node: Glossary1206955 +Node: Copying1238901 +Node: GNU Free Documentation License1276440 +Node: Index1301558 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 55a8fc0e..825c97b0 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -562,6 +562,7 @@ particular records in a file and perform operations upon them. * Computed Regexps:: Using Dynamic Regexps. * GNU Regexp Operators:: Operators specific to GNU software. * Case-sensitivity:: How to do case-insensitive matching. +* Strong Regexp Constants:: Strongly typed regexp constants. * Regexp Summary:: Regular expressions summary. * Records:: Controlling how data is split into records. @@ -5018,6 +5019,7 @@ regular expressions work, we present more complicated instances. * Computed Regexps:: Using Dynamic Regexps. * GNU Regexp Operators:: Operators specific to GNU software. * Case-sensitivity:: How to do case-insensitive matching. +* Strong Regexp Constants:: Strongly typed regexp constants. * Regexp Summary:: Regular expressions summary. @end menu @@ -6265,6 +6267,89 @@ The value of @code{IGNORECASE} has no effect if @command{gawk} is in compatibility mode (@pxref{Options}). Case is always significant in compatibility mode. +@node Strong Regexp Constants +@section Strongly Typed Regexp Constants + +This @value{SECTION} describes a @command{gawk}-specific feature. + +Regexp constants (@code{/@dots{}/}) hold a strange position in the +@command{awk} language. In most contexts, they act like an expression: +@samp{$0 ~ /@dots{}/}. In other contexts, they denote only a regexp to +be matched. In no case are they really a ``first class citizen'' of the +language. That is, you cannot define a scalar variable whose type is +``regexp'' in the same sense that you can define a variable to be a +number or a string: + +@example +num = 42 @ii{Numeric variable} +str = "hi" @ii{String variable} +re = /foo/ @ii{Wrong!} re @ii{is the result of} $0 ~ /foo/ +@end example + +For a number of more advanced use cases (described later on in this +@value{DOCUMENT}), it would be nice to have regexp constants that +are @dfn{strongly typed}; in other words, that denote a regexp useful +for matching, and not an expression. + +@command{gawk} provides this feature. A strongly typed regexp constant +looks almost like a regular regexp constant, except that it is preceded +by an @samp{@@} sign: + +@example +re = @@/foo/ @ii{Regexp variable} +@end example + +Strongly typed regexp constants @emph{cannot} be used eveywhere that a +regular regexp constant can, because this would make the language even more +confusing. Instead, you may use them only in certain contexts: + +@itemize @bullet +@item +On the righthand side of the @samp{~} and @samp{!~} operators: @samp{some_var ~ @@/foo/} +(@pxref{Regexp Usage}). + +@item +In the @code{case} part of a @code{switch} statement +(@pxref{Switch Statement}). + +@item +As an argument to one of the built-in functions that accept regexp constants: +@code{gensub()}, +@code{gsub()}, +@code{match()}, +@code{patsplit()}, +@code{split()}, +and +@code{sub()} +(@pxref{String Functions}). + +@item +As a parameter in a call to a user-defined function +(@pxref{User-defined}). + +@item +On the righthand side of an assignment to a variable: @samp{some_var = @@/foo/}. +In this case, the type of @code{some_var} is regexp. Additionally, @code{some_var} +can be used with @samp{~} and @samp{!~}, passed to one of the built-in functions +listed above, or passed as a parameter to a user-defined function. +@end itemize + +You may use the @code{typeof()} built-in function +(@pxref{Type Functions}) +to determine if a variable or function parameter is +a regexp variable. + +The true power of this feature comes from the ability to create variables that +have regexp type. Such variables can be passed on to user-defined functions, +without the confusing aspects of computed regular expressions created from +strings or string constants. They may also be passed through indirect function +calls (@pxref{Indirect Calls}) +onto the built-in functions that accept regexp constants. + +When used in numeric conversions, strongly typed regexp variables convert +to zero. When used in string conversions, they convert to the string +value of the original regexp text. + @node Regexp Summary @section Summary @@ -6308,6 +6393,11 @@ treated as regular expressions). case sensitivity of regexp matching. In other @command{awk} versions, use @code{tolower()} or @code{toupper()}. +@item +Strongly typed regexp constants (@code{@@/.../}) enable +certain advanced use cases to be described later on in the +@value{DOCUMENT}. + @end itemize @@ -19403,16 +19493,41 @@ results of the @code{compl()}, @code{lshift()}, and @code{rshift()} functions. @node Type Functions @subsection Getting Type Information -@command{gawk} provides a single function that lets you distinguish -an array from a scalar variable. This is necessary for writing code +@command{gawk} provides two functions that lets you distinguish +the type of a variable. +This is necessary for writing code that traverses every element of an array of arrays -(@pxref{Arrays of Arrays}). +(@pxref{Arrays of Arrays}), and in other contexts. @table @code @cindexgawkfunc{isarray} @cindex scalar or array @item isarray(@var{x}) Return a true value if @var{x} is an array. Otherwise, return false. + +@cindexgawkfunc{typeof} +@cindex variable type +@cindex type, of variable +@item typeof(@var{x}) +Return one of the following strings, depending upon the type of @var{x}: + +@c nested table +@table @code +@item "array" +@var{x} is an array. + +@item "regexp" +@var{x} is a strongly typed regexp (@pxref{Strong Regexp Constants}). + +@item "scalar_n" +@var{x} is a number. + +@item "scalar_s" +@var{x} is a string. + +@item "untyped" +@var{x} has not yet been given a type. +@end table @end table @code{isarray()} is meant for use in two circumstances. The first is when @@ -19430,6 +19545,14 @@ that has not been previously used to @code{isarray()}, @command{gawk} ends up turning it into a scalar. @end quotation +The @code{typeof()} function is general; it allows you to determine +if a variable or function parameter is a scalar, an array, or a strongly +typed regexp. + +@code{isarray()} is deprecated; you should use @code{typeof()} instead. +You should replace any existing uses of @samp{isarray(var)} in your +code with @samp{typeof(var) == "array"}. + @node I18N Functions @subsection String-Translation Functions @cindex @command{gawk}, string-translation functions diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 903152d9..a8af903e 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -557,6 +557,7 @@ particular records in a file and perform operations upon them. * Computed Regexps:: Using Dynamic Regexps. * GNU Regexp Operators:: Operators specific to GNU software. * Case-sensitivity:: How to do case-insensitive matching. +* Strong Regexp Constants:: Strongly typed regexp constants. * Regexp Summary:: Regular expressions summary. * Records:: Controlling how data is split into records. @@ -4929,6 +4930,7 @@ regular expressions work, we present more complicated instances. * Computed Regexps:: Using Dynamic Regexps. * GNU Regexp Operators:: Operators specific to GNU software. * Case-sensitivity:: How to do case-insensitive matching. +* Strong Regexp Constants:: Strongly typed regexp constants. * Regexp Summary:: Regular expressions summary. @end menu @@ -6049,6 +6051,89 @@ The value of @code{IGNORECASE} has no effect if @command{gawk} is in compatibility mode (@pxref{Options}). Case is always significant in compatibility mode. +@node Strong Regexp Constants +@section Strongly Typed Regexp Constants + +This @value{SECTION} describes a @command{gawk}-specific feature. + +Regexp constants (@code{/@dots{}/}) hold a strange position in the +@command{awk} language. In most contexts, they act like an expression: +@samp{$0 ~ /@dots{}/}. In other contexts, they denote only a regexp to +be matched. In no case are they really a ``first class citizen'' of the +language. That is, you cannot define a scalar variable whose type is +``regexp'' in the same sense that you can define a variable to be a +number or a string: + +@example +num = 42 @ii{Numeric variable} +str = "hi" @ii{String variable} +re = /foo/ @ii{Wrong!} re @ii{is the result of} $0 ~ /foo/ +@end example + +For a number of more advanced use cases (described later on in this +@value{DOCUMENT}), it would be nice to have regexp constants that +are @dfn{strongly typed}; in other words, that denote a regexp useful +for matching, and not an expression. + +@command{gawk} provides this feature. A strongly typed regexp constant +looks almost like a regular regexp constant, except that it is preceded +by an @samp{@@} sign: + +@example +re = @@/foo/ @ii{Regexp variable} +@end example + +Strongly typed regexp constants @emph{cannot} be used eveywhere that a +regular regexp constant can, because this would make the language even more +confusing. Instead, you may use them only in certain contexts: + +@itemize @bullet +@item +On the righthand side of the @samp{~} and @samp{!~} operators: @samp{some_var ~ @@/foo/} +(@pxref{Regexp Usage}). + +@item +In the @code{case} part of a @code{switch} statement +(@pxref{Switch Statement}). + +@item +As an argument to one of the built-in functions that accept regexp constants: +@code{gensub()}, +@code{gsub()}, +@code{match()}, +@code{patsplit()}, +@code{split()}, +and +@code{sub()} +(@pxref{String Functions}). + +@item +As a parameter in a call to a user-defined function +(@pxref{User-defined}). + +@item +On the righthand side of an assignment to a variable: @samp{some_var = @@/foo/}. +In this case, the type of @code{some_var} is regexp. Additionally, @code{some_var} +can be used with @samp{~} and @samp{!~}, passed to one of the built-in functions +listed above, or passed as a parameter to a user-defined function. +@end itemize + +You may use the @code{typeof()} built-in function +(@pxref{Type Functions}) +to determine if a variable or function parameter is +a regexp variable. + +The true power of this feature comes from the ability to create variables that +have regexp type. Such variables can be passed on to user-defined functions, +without the confusing aspects of computed regular expressions created from +strings or string constants. They may also be passed through indirect function +calls (@pxref{Indirect Calls}) +onto the built-in functions that accept regexp constants. + +When used in numeric conversions, strongly typed regexp variables convert +to zero. When used in string conversions, they convert to the string +value of the original regexp text. + @node Regexp Summary @section Summary @@ -6092,6 +6177,11 @@ treated as regular expressions). case sensitivity of regexp matching. In other @command{awk} versions, use @code{tolower()} or @code{toupper()}. +@item +Strongly typed regexp constants (@code{@@/.../}) enable +certain advanced use cases to be described later on in the +@value{DOCUMENT}. + @end itemize @@ -18524,16 +18614,41 @@ results of the @code{compl()}, @code{lshift()}, and @code{rshift()} functions. @node Type Functions @subsection Getting Type Information -@command{gawk} provides a single function that lets you distinguish -an array from a scalar variable. This is necessary for writing code +@command{gawk} provides two functions that lets you distinguish +the type of a variable. +This is necessary for writing code that traverses every element of an array of arrays -(@pxref{Arrays of Arrays}). +(@pxref{Arrays of Arrays}), and in other contexts. @table @code @cindexgawkfunc{isarray} @cindex scalar or array @item isarray(@var{x}) Return a true value if @var{x} is an array. Otherwise, return false. + +@cindexgawkfunc{typeof} +@cindex variable type +@cindex type, of variable +@item typeof(@var{x}) +Return one of the following strings, depending upon the type of @var{x}: + +@c nested table +@table @code +@item "array" +@var{x} is an array. + +@item "regexp" +@var{x} is a strongly typed regexp (@pxref{Strong Regexp Constants}). + +@item "scalar_n" +@var{x} is a number. + +@item "scalar_s" +@var{x} is a string. + +@item "untyped" +@var{x} has not yet been given a type. +@end table @end table @code{isarray()} is meant for use in two circumstances. The first is when @@ -18551,6 +18666,14 @@ that has not been previously used to @code{isarray()}, @command{gawk} ends up turning it into a scalar. @end quotation +The @code{typeof()} function is general; it allows you to determine +if a variable or function parameter is a scalar, an array, or a strongly +typed regexp. + +@code{isarray()} is deprecated; you should use @code{typeof()} instead. +You should replace any existing uses of @samp{isarray(var)} in your +code with @samp{typeof(var) == "array"}. + @node I18N Functions @subsection String-Translation Functions @cindex @command{gawk}, string-translation functions |