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 70a7147c..812bfd4d 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -27,6 +27,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 6a52baec..b0adffb7 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-1473348 -Node: Reference to Elements473476 -Node: Assigning Elements475940 -Node: Array Example476431 -Node: Scanning an Array478190 -Node: Controlling Scanning481214 -Ref: Controlling Scanning-Footnote-1486613 -Node: Numeric Array Subscripts486929 -Node: Uninitialized Subscripts489113 -Node: Delete490732 -Ref: Delete-Footnote-1493484 -Node: Multidimensional493541 -Node: Multiscanning496636 -Node: Arrays of Arrays498227 -Node: Arrays Summary502995 -Node: Functions505088 -Node: Built-in506126 -Node: Calling Built-in507204 -Node: Numeric Functions509200 -Ref: Numeric Functions-Footnote-1514033 -Ref: Numeric Functions-Footnote-2514390 -Ref: Numeric Functions-Footnote-3514438 -Node: String Functions514710 -Ref: String Functions-Footnote-1538218 -Ref: String Functions-Footnote-2538347 -Ref: String Functions-Footnote-3538595 -Node: Gory Details538682 -Ref: table-sub-escapes540473 -Ref: table-sub-proposed541992 -Ref: table-posix-sub543355 -Ref: table-gensub-escapes544896 -Ref: Gory Details-Footnote-1545719 -Node: I/O Functions545870 -Ref: I/O Functions-Footnote-1553091 -Node: Time Functions553239 -Ref: Time Functions-Footnote-1563744 -Ref: Time Functions-Footnote-2563812 -Ref: Time Functions-Footnote-3563970 -Ref: Time Functions-Footnote-4564081 -Ref: Time Functions-Footnote-5564193 -Ref: Time Functions-Footnote-6564420 -Node: Bitwise Functions564686 -Ref: table-bitwise-ops565280 -Ref: Bitwise Functions-Footnote-1569588 -Node: Type Functions569761 -Node: I18N Functions570917 -Node: User-defined572568 -Node: Definition Syntax573373 -Ref: Definition Syntax-Footnote-1579060 -Node: Function Example579131 -Ref: Function Example-Footnote-1582053 -Node: Function Caveats582075 -Node: Calling A Function582593 -Node: Variable Scope583551 -Node: Pass By Value/Reference586545 -Node: Return Statement590044 -Node: Dynamic Typing593023 -Node: Indirect Calls593953 -Ref: Indirect Calls-Footnote-1604204 -Node: Functions Summary604332 -Node: Library Functions607037 -Ref: Library Functions-Footnote-1610646 -Ref: Library Functions-Footnote-2610789 -Node: Library Names610960 -Ref: Library Names-Footnote-1614421 -Ref: Library Names-Footnote-2614644 -Node: General Functions614730 -Node: Strtonum Function615833 -Node: Assert Function618855 -Node: Round Function622181 -Node: Cliff Random Function623722 -Node: Ordinal Functions624738 -Ref: Ordinal Functions-Footnote-1627801 -Ref: Ordinal Functions-Footnote-2628053 -Node: Join Function628263 -Ref: Join Function-Footnote-1630033 -Node: Getlocaltime Function630233 -Node: Readfile Function633977 -Node: Shell Quoting635951 -Node: Data File Management637352 -Node: Filetrans Function637984 -Node: Rewind Function642081 -Node: File Checking643467 -Ref: File Checking-Footnote-1644801 -Node: Empty Files645002 -Node: Ignoring Assigns646981 -Node: Getopt Function648531 -Ref: Getopt Function-Footnote-1660001 -Node: Passwd Functions660201 -Ref: Passwd Functions-Footnote-1669042 -Node: Group Functions669130 -Ref: Group Functions-Footnote-1677029 -Node: Walking Arrays677236 -Node: Library Functions Summary680246 -Node: Library Exercises681652 -Node: Sample Programs682931 -Node: Running Examples683701 -Node: Clones684429 -Node: Cut Program685653 -Node: Egrep Program695374 -Ref: Egrep Program-Footnote-1702886 -Node: Id Program702996 -Node: Split Program706676 -Ref: Split Program-Footnote-1710135 -Node: Tee Program710264 -Node: Uniq Program713054 -Node: Wc Program720480 -Ref: Wc Program-Footnote-1724735 -Node: Miscellaneous Programs724829 -Node: Dupword Program726042 -Node: Alarm Program728072 -Node: Translate Program732927 -Ref: Translate Program-Footnote-1737492 -Node: Labels Program737762 -Ref: Labels Program-Footnote-1741113 -Node: Word Sorting741197 -Node: History Sorting745269 -Node: Extract Program747104 -Node: Simple Sed754635 -Node: Igawk Program757709 -Ref: Igawk Program-Footnote-1772040 -Ref: Igawk Program-Footnote-2772242 -Ref: Igawk Program-Footnote-3772364 -Node: Anagram Program772479 -Node: Signature Program775541 -Node: Programs Summary776788 -Node: Programs Exercises778003 -Ref: Programs Exercises-Footnote-1782132 -Node: Advanced Features782223 -Node: Nondecimal Data784213 -Node: Array Sorting785804 -Node: Controlling Array Traversal786504 -Ref: Controlling Array Traversal-Footnote-1794873 -Node: Array Sorting Functions794991 -Ref: Array Sorting Functions-Footnote-1798878 -Node: Two-way I/O799074 -Ref: Two-way I/O-Footnote-1804025 -Ref: Two-way I/O-Footnote-2804212 -Node: TCP/IP Networking804294 -Node: Profiling807201 -Node: Advanced Features Summary815472 -Node: Internationalization817408 -Node: I18N and L10N818888 -Node: Explaining gettext819575 -Ref: Explaining gettext-Footnote-1824598 -Ref: Explaining gettext-Footnote-2824783 -Node: Programmer i18n824948 -Ref: Programmer i18n-Footnote-1829804 -Node: Translator i18n829853 -Node: String Extraction830647 -Ref: String Extraction-Footnote-1831780 -Node: Printf Ordering831866 -Ref: Printf Ordering-Footnote-1834652 -Node: I18N Portability834716 -Ref: I18N Portability-Footnote-1837172 -Node: I18N Example837235 -Ref: I18N Example-Footnote-1840041 -Node: Gawk I18N840114 -Node: I18N Summary840759 -Node: Debugger842100 -Node: Debugging843122 -Node: Debugging Concepts843563 -Node: Debugging Terms845372 -Node: Awk Debugging847947 -Node: Sample Debugging Session848853 -Node: Debugger Invocation849387 -Node: Finding The Bug850773 -Node: List of Debugger Commands857251 -Node: Breakpoint Control858584 -Node: Debugger Execution Control862278 -Node: Viewing And Changing Data865640 -Node: Execution Stack869014 -Node: Debugger Info870651 -Node: Miscellaneous Debugger Commands874722 -Node: Readline Support879731 -Node: Limitations880627 -Node: Debugging Summary882736 -Node: Arbitrary Precision Arithmetic883909 -Node: Computer Arithmetic885325 -Ref: table-numeric-ranges888916 -Ref: Computer Arithmetic-Footnote-1889638 -Node: Math Definitions889695 -Ref: table-ieee-formats893009 -Ref: Math Definitions-Footnote-1893612 -Node: MPFR features893717 -Node: FP Math Caution895390 -Ref: FP Math Caution-Footnote-1896462 -Node: Inexactness of computations896831 -Node: Inexact representation897791 -Node: Comparing FP Values899151 -Node: Errors accumulate900233 -Node: Getting Accuracy901666 -Node: Try To Round904376 -Node: Setting precision905275 -Ref: table-predefined-precision-strings905972 -Node: Setting the rounding mode907802 -Ref: table-gawk-rounding-modes908176 -Ref: Setting the rounding mode-Footnote-1911584 -Node: Arbitrary Precision Integers911763 -Ref: Arbitrary Precision Integers-Footnote-1916680 -Node: POSIX Floating Point Problems916829 -Ref: POSIX Floating Point Problems-Footnote-1920711 -Node: Floating point summary920749 -Node: Dynamic Extensions922939 -Node: Extension Intro924492 -Node: Plugin License925758 -Node: Extension Mechanism Outline926555 -Ref: figure-load-extension926994 -Ref: figure-register-new-function928559 -Ref: figure-call-new-function929651 -Node: Extension API Description931714 -Node: Extension API Functions Introduction933248 -Node: General Data Types938107 -Ref: General Data Types-Footnote-1944062 -Node: Memory Allocation Functions944361 -Ref: Memory Allocation Functions-Footnote-1947206 -Node: Constructor Functions947305 -Node: Registration Functions949050 -Node: Extension Functions949735 -Node: Exit Callback Functions952034 -Node: Extension Version String953284 -Node: Input Parsers953947 -Node: Output Wrappers963832 -Node: Two-way processors968344 -Node: Printing Messages970608 -Ref: Printing Messages-Footnote-1971684 -Node: Updating 'ERRNO'971837 -Node: Requesting Values972578 -Ref: table-value-types-returned973317 -Node: Accessing Parameters974200 -Node: Symbol Table Access975436 -Node: Symbol table by name975948 -Node: Symbol table by cookie977969 -Ref: Symbol table by cookie-Footnote-1982118 -Node: Cached values982182 -Ref: Cached values-Footnote-1985683 -Node: Array Manipulation985774 -Ref: Array Manipulation-Footnote-1986865 -Node: Array Data Types986902 -Ref: Array Data Types-Footnote-1989560 -Node: Array Functions989652 -Node: Flattening Arrays993511 -Node: Creating Arrays1000419 -Node: Redirection API1005191 -Node: Extension API Variables1008022 -Node: Extension Versioning1008655 -Node: Extension API Informational Variables1010546 -Node: Extension API Boilerplate1011610 -Node: Finding Extensions1015424 -Node: Extension Example1015984 -Node: Internal File Description1016782 -Node: Internal File Ops1020862 -Ref: Internal File Ops-Footnote-11032624 -Node: Using Internal File Ops1032764 -Ref: Using Internal File Ops-Footnote-11035147 -Node: Extension Samples1035422 -Node: Extension Sample File Functions1036951 -Node: Extension Sample Fnmatch1044600 -Node: Extension Sample Fork1046087 -Node: Extension Sample Inplace1047305 -Node: Extension Sample Ord1049391 -Node: Extension Sample Readdir1050227 -Ref: table-readdir-file-types1051116 -Node: Extension Sample Revout1051921 -Node: Extension Sample Rev2way1052510 -Node: Extension Sample Read write array1053250 -Node: Extension Sample Readfile1055192 -Node: Extension Sample Time1056287 -Node: Extension Sample API Tests1057635 -Node: gawkextlib1058127 -Node: Extension summary1060574 -Node: Extension Exercises1064266 -Node: Language History1065763 -Node: V7/SVR3.11067419 -Node: SVR41069572 -Node: POSIX1071006 -Node: BTL1072386 -Node: POSIX/GNU1073116 -Node: Feature History1078955 -Node: Common Extensions1092946 -Node: Ranges and Locales1094229 -Ref: Ranges and Locales-Footnote-11098845 -Ref: Ranges and Locales-Footnote-21098872 -Ref: Ranges and Locales-Footnote-31099107 -Node: Contributors1099328 -Node: History summary1104897 -Node: Installation1106277 -Node: Gawk Distribution1107222 -Node: Getting1107706 -Node: Extracting1108529 -Node: Distribution contents1110167 -Node: Unix Installation1116263 -Node: Quick Installation1116945 -Node: Shell Startup Files1119359 -Node: Additional Configuration Options1120437 -Node: Configuration Philosophy1122242 -Node: Non-Unix Installation1124612 -Node: PC Installation1125070 -Node: PC Binary Installation1126390 -Node: PC Compiling1128242 -Ref: PC Compiling-Footnote-11131266 -Node: PC Testing1131375 -Node: PC Using1132555 -Node: Cygwin1136669 -Node: MSYS1137439 -Node: VMS Installation1137940 -Node: VMS Compilation1138731 -Ref: VMS Compilation-Footnote-11139961 -Node: VMS Dynamic Extensions1140019 -Node: VMS Installation Details1141704 -Node: VMS Running1143957 -Node: VMS GNV1146798 -Node: VMS Old Gawk1147533 -Node: Bugs1148004 -Node: Other Versions1152118 -Node: Installation summary1158592 -Node: Notes1159650 -Node: Compatibility Mode1160515 -Node: Additions1161297 -Node: Accessing The Source1162222 -Node: Adding Code1163658 -Node: New Ports1169813 -Node: Derived Files1174301 -Ref: Derived Files-Footnote-11179786 -Ref: Derived Files-Footnote-21179821 -Ref: Derived Files-Footnote-31180419 -Node: Future Extensions1180533 -Node: Implementation Limitations1181191 -Node: Extension Design1182374 -Node: Old Extension Problems1183528 -Ref: Old Extension Problems-Footnote-11185046 -Node: Extension New Mechanism Goals1185103 -Ref: Extension New Mechanism Goals-Footnote-11188467 -Node: Extension Other Design Decisions1188656 -Node: Extension Future Growth1190769 -Node: Old Extension Mechanism1191605 -Node: Notes summary1193368 -Node: Basic Concepts1194550 -Node: Basic High Level1195231 -Ref: figure-general-flow1195513 -Ref: figure-process-flow1196198 -Ref: Basic High Level-Footnote-11199499 -Node: Basic Data Typing1199684 -Node: Glossary1203012 -Node: Copying1234958 -Node: GNU Free Documentation License1272497 -Node: Index1297615 +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-1476577 +Node: Reference to Elements476705 +Node: Assigning Elements479169 +Node: Array Example479660 +Node: Scanning an Array481419 +Node: Controlling Scanning484443 +Ref: Controlling Scanning-Footnote-1489842 +Node: Numeric Array Subscripts490158 +Node: Uninitialized Subscripts492342 +Node: Delete493961 +Ref: Delete-Footnote-1496713 +Node: Multidimensional496770 +Node: Multiscanning499865 +Node: Arrays of Arrays501456 +Node: Arrays Summary506224 +Node: Functions508317 +Node: Built-in509355 +Node: Calling Built-in510433 +Node: Numeric Functions512429 +Ref: Numeric Functions-Footnote-1517262 +Ref: Numeric Functions-Footnote-2517619 +Ref: Numeric Functions-Footnote-3517667 +Node: String Functions517939 +Ref: String Functions-Footnote-1541447 +Ref: String Functions-Footnote-2541576 +Ref: String Functions-Footnote-3541824 +Node: Gory Details541911 +Ref: table-sub-escapes543702 +Ref: table-sub-proposed545221 +Ref: table-posix-sub546584 +Ref: table-gensub-escapes548125 +Ref: Gory Details-Footnote-1548948 +Node: I/O Functions549099 +Ref: I/O Functions-Footnote-1556320 +Node: Time Functions556468 +Ref: Time Functions-Footnote-1566973 +Ref: Time Functions-Footnote-2567041 +Ref: Time Functions-Footnote-3567199 +Ref: Time Functions-Footnote-4567310 +Ref: Time Functions-Footnote-5567422 +Ref: Time Functions-Footnote-6567649 +Node: Bitwise Functions567915 +Ref: table-bitwise-ops568509 +Ref: Bitwise Functions-Footnote-1572817 +Node: Type Functions572990 +Node: I18N Functions574852 +Node: User-defined576503 +Node: Definition Syntax577308 +Ref: Definition Syntax-Footnote-1582995 +Node: Function Example583066 +Ref: Function Example-Footnote-1585988 +Node: Function Caveats586010 +Node: Calling A Function586528 +Node: Variable Scope587486 +Node: Pass By Value/Reference590480 +Node: Return Statement593979 +Node: Dynamic Typing596958 +Node: Indirect Calls597888 +Ref: Indirect Calls-Footnote-1608139 +Node: Functions Summary608267 +Node: Library Functions610972 +Ref: Library Functions-Footnote-1614581 +Ref: Library Functions-Footnote-2614724 +Node: Library Names614895 +Ref: Library Names-Footnote-1618356 +Ref: Library Names-Footnote-2618579 +Node: General Functions618665 +Node: Strtonum Function619768 +Node: Assert Function622790 +Node: Round Function626116 +Node: Cliff Random Function627657 +Node: Ordinal Functions628673 +Ref: Ordinal Functions-Footnote-1631736 +Ref: Ordinal Functions-Footnote-2631988 +Node: Join Function632198 +Ref: Join Function-Footnote-1633968 +Node: Getlocaltime Function634168 +Node: Readfile Function637912 +Node: Shell Quoting639886 +Node: Data File Management641287 +Node: Filetrans Function641919 +Node: Rewind Function646016 +Node: File Checking647402 +Ref: File Checking-Footnote-1648736 +Node: Empty Files648937 +Node: Ignoring Assigns650916 +Node: Getopt Function652466 +Ref: Getopt Function-Footnote-1663936 +Node: Passwd Functions664136 +Ref: Passwd Functions-Footnote-1672977 +Node: Group Functions673065 +Ref: Group Functions-Footnote-1680964 +Node: Walking Arrays681171 +Node: Library Functions Summary684181 +Node: Library Exercises685587 +Node: Sample Programs686866 +Node: Running Examples687636 +Node: Clones688364 +Node: Cut Program689588 +Node: Egrep Program699309 +Ref: Egrep Program-Footnote-1706821 +Node: Id Program706931 +Node: Split Program710611 +Ref: Split Program-Footnote-1714070 +Node: Tee Program714199 +Node: Uniq Program716989 +Node: Wc Program724415 +Ref: Wc Program-Footnote-1728670 +Node: Miscellaneous Programs728764 +Node: Dupword Program729977 +Node: Alarm Program732007 +Node: Translate Program736862 +Ref: Translate Program-Footnote-1741427 +Node: Labels Program741697 +Ref: Labels Program-Footnote-1745048 +Node: Word Sorting745132 +Node: History Sorting749204 +Node: Extract Program751039 +Node: Simple Sed758570 +Node: Igawk Program761644 +Ref: Igawk Program-Footnote-1775975 +Ref: Igawk Program-Footnote-2776177 +Ref: Igawk Program-Footnote-3776299 +Node: Anagram Program776414 +Node: Signature Program779476 +Node: Programs Summary780723 +Node: Programs Exercises781938 +Ref: Programs Exercises-Footnote-1786067 +Node: Advanced Features786158 +Node: Nondecimal Data788148 +Node: Array Sorting789739 +Node: Controlling Array Traversal790439 +Ref: Controlling Array Traversal-Footnote-1798808 +Node: Array Sorting Functions798926 +Ref: Array Sorting Functions-Footnote-1802813 +Node: Two-way I/O803009 +Ref: Two-way I/O-Footnote-1807960 +Ref: Two-way I/O-Footnote-2808147 +Node: TCP/IP Networking808229 +Node: Profiling811136 +Node: Advanced Features Summary819407 +Node: Internationalization821343 +Node: I18N and L10N822823 +Node: Explaining gettext823510 +Ref: Explaining gettext-Footnote-1828533 +Ref: Explaining gettext-Footnote-2828718 +Node: Programmer i18n828883 +Ref: Programmer i18n-Footnote-1833739 +Node: Translator i18n833788 +Node: String Extraction834582 +Ref: String Extraction-Footnote-1835715 +Node: Printf Ordering835801 +Ref: Printf Ordering-Footnote-1838587 +Node: I18N Portability838651 +Ref: I18N Portability-Footnote-1841107 +Node: I18N Example841170 +Ref: I18N Example-Footnote-1843976 +Node: Gawk I18N844049 +Node: I18N Summary844694 +Node: Debugger846035 +Node: Debugging847057 +Node: Debugging Concepts847498 +Node: Debugging Terms849307 +Node: Awk Debugging851882 +Node: Sample Debugging Session852788 +Node: Debugger Invocation853322 +Node: Finding The Bug854708 +Node: List of Debugger Commands861186 +Node: Breakpoint Control862519 +Node: Debugger Execution Control866213 +Node: Viewing And Changing Data869575 +Node: Execution Stack872949 +Node: Debugger Info874586 +Node: Miscellaneous Debugger Commands878657 +Node: Readline Support883666 +Node: Limitations884562 +Node: Debugging Summary886671 +Node: Arbitrary Precision Arithmetic887844 +Node: Computer Arithmetic889260 +Ref: table-numeric-ranges892851 +Ref: Computer Arithmetic-Footnote-1893573 +Node: Math Definitions893630 +Ref: table-ieee-formats896944 +Ref: Math Definitions-Footnote-1897547 +Node: MPFR features897652 +Node: FP Math Caution899325 +Ref: FP Math Caution-Footnote-1900397 +Node: Inexactness of computations900766 +Node: Inexact representation901726 +Node: Comparing FP Values903086 +Node: Errors accumulate904168 +Node: Getting Accuracy905601 +Node: Try To Round908311 +Node: Setting precision909210 +Ref: table-predefined-precision-strings909907 +Node: Setting the rounding mode911737 +Ref: table-gawk-rounding-modes912111 +Ref: Setting the rounding mode-Footnote-1915519 +Node: Arbitrary Precision Integers915698 +Ref: Arbitrary Precision Integers-Footnote-1920615 +Node: POSIX Floating Point Problems920764 +Ref: POSIX Floating Point Problems-Footnote-1924646 +Node: Floating point summary924684 +Node: Dynamic Extensions926874 +Node: Extension Intro928427 +Node: Plugin License929693 +Node: Extension Mechanism Outline930490 +Ref: figure-load-extension930929 +Ref: figure-register-new-function932494 +Ref: figure-call-new-function933586 +Node: Extension API Description935649 +Node: Extension API Functions Introduction937183 +Node: General Data Types942042 +Ref: General Data Types-Footnote-1947997 +Node: Memory Allocation Functions948296 +Ref: Memory Allocation Functions-Footnote-1951141 +Node: Constructor Functions951240 +Node: Registration Functions952985 +Node: Extension Functions953670 +Node: Exit Callback Functions955969 +Node: Extension Version String957219 +Node: Input Parsers957882 +Node: Output Wrappers967767 +Node: Two-way processors972279 +Node: Printing Messages974543 +Ref: Printing Messages-Footnote-1975619 +Node: Updating 'ERRNO'975772 +Node: Requesting Values976513 +Ref: table-value-types-returned977252 +Node: Accessing Parameters978135 +Node: Symbol Table Access979371 +Node: Symbol table by name979883 +Node: Symbol table by cookie981904 +Ref: Symbol table by cookie-Footnote-1986053 +Node: Cached values986117 +Ref: Cached values-Footnote-1989618 +Node: Array Manipulation989709 +Ref: Array Manipulation-Footnote-1990800 +Node: Array Data Types990837 +Ref: Array Data Types-Footnote-1993495 +Node: Array Functions993587 +Node: Flattening Arrays997446 +Node: Creating Arrays1004354 +Node: Redirection API1009126 +Node: Extension API Variables1011957 +Node: Extension Versioning1012590 +Node: Extension API Informational Variables1014481 +Node: Extension API Boilerplate1015545 +Node: Finding Extensions1019359 +Node: Extension Example1019919 +Node: Internal File Description1020717 +Node: Internal File Ops1024797 +Ref: Internal File Ops-Footnote-11036559 +Node: Using Internal File Ops1036699 +Ref: Using Internal File Ops-Footnote-11039082 +Node: Extension Samples1039357 +Node: Extension Sample File Functions1040886 +Node: Extension Sample Fnmatch1048535 +Node: Extension Sample Fork1050022 +Node: Extension Sample Inplace1051240 +Node: Extension Sample Ord1053326 +Node: Extension Sample Readdir1054162 +Ref: table-readdir-file-types1055051 +Node: Extension Sample Revout1055856 +Node: Extension Sample Rev2way1056445 +Node: Extension Sample Read write array1057185 +Node: Extension Sample Readfile1059127 +Node: Extension Sample Time1060222 +Node: Extension Sample API Tests1061570 +Node: gawkextlib1062062 +Node: Extension summary1064509 +Node: Extension Exercises1068201 +Node: Language History1069698 +Node: V7/SVR3.11071354 +Node: SVR41073507 +Node: POSIX1074941 +Node: BTL1076321 +Node: POSIX/GNU1077051 +Node: Feature History1082890 +Node: Common Extensions1096881 +Node: Ranges and Locales1098164 +Ref: Ranges and Locales-Footnote-11102780 +Ref: Ranges and Locales-Footnote-21102807 +Ref: Ranges and Locales-Footnote-31103042 +Node: Contributors1103263 +Node: History summary1108832 +Node: Installation1110212 +Node: Gawk Distribution1111157 +Node: Getting1111641 +Node: Extracting1112464 +Node: Distribution contents1114102 +Node: Unix Installation1120198 +Node: Quick Installation1120880 +Node: Shell Startup Files1123294 +Node: Additional Configuration Options1124372 +Node: Configuration Philosophy1126177 +Node: Non-Unix Installation1128547 +Node: PC Installation1129005 +Node: PC Binary Installation1130325 +Node: PC Compiling1132177 +Ref: PC Compiling-Footnote-11135201 +Node: PC Testing1135310 +Node: PC Using1136490 +Node: Cygwin1140604 +Node: MSYS1141374 +Node: VMS Installation1141875 +Node: VMS Compilation1142666 +Ref: VMS Compilation-Footnote-11143896 +Node: VMS Dynamic Extensions1143954 +Node: VMS Installation Details1145639 +Node: VMS Running1147892 +Node: VMS GNV1150733 +Node: VMS Old Gawk1151468 +Node: Bugs1151939 +Node: Other Versions1156053 +Node: Installation summary1162527 +Node: Notes1163585 +Node: Compatibility Mode1164450 +Node: Additions1165232 +Node: Accessing The Source1166157 +Node: Adding Code1167593 +Node: New Ports1173748 +Node: Derived Files1178236 +Ref: Derived Files-Footnote-11183721 +Ref: Derived Files-Footnote-21183756 +Ref: Derived Files-Footnote-31184354 +Node: Future Extensions1184468 +Node: Implementation Limitations1185126 +Node: Extension Design1186309 +Node: Old Extension Problems1187463 +Ref: Old Extension Problems-Footnote-11188981 +Node: Extension New Mechanism Goals1189038 +Ref: Extension New Mechanism Goals-Footnote-11192402 +Node: Extension Other Design Decisions1192591 +Node: Extension Future Growth1194704 +Node: Old Extension Mechanism1195540 +Node: Notes summary1197303 +Node: Basic Concepts1198485 +Node: Basic High Level1199166 +Ref: figure-general-flow1199448 +Ref: figure-process-flow1200133 +Ref: Basic High Level-Footnote-11203434 +Node: Basic Data Typing1203619 +Node: Glossary1206947 +Node: Copying1238893 +Node: GNU Free Documentation License1276432 +Node: Index1301550 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 9d1d88f6..407ce198 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 @@ -19398,16 +19488,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 @@ -19425,6 +19540,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 c55557a2..5be9dede 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 @@ -18519,16 +18609,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 @@ -18546,6 +18661,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 |