diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/gawk.1 | 1 | ||||
| -rw-r--r-- | doc/gawk.info | 1046 | ||||
| -rw-r--r-- | doc/gawk.texi | 75 | ||||
| -rw-r--r-- | doc/gawktexi.in | 75 |
5 files changed, 706 insertions, 497 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 305fc8e4..1ac2a958 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -42,6 +42,12 @@ 2016-08-03 Arnold D. Robbins <arnold@skeeve.com> + Restored doc on typed regexes. + + * gawk.1, gawktexi.in: Updated. + +2016-08-03 Arnold D. Robbins <arnold@skeeve.com> + Remove typed regexes until they can be done properly. * gawk.1, gawktexi.in: Updated. @@ -3230,6 +3230,7 @@ Return a string indicating the type of The string will be one of \fB"array"\fP, \fB"number"\fP, +\fB"regexp"\fP, \fB"string"\fP, \fB"strnum"\fP, or diff --git a/doc/gawk.info b/doc/gawk.info index 1faa775c..afd4972f 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -4134,6 +4134,54 @@ that you can define a variable to be a number or a string: 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 @@ -4171,6 +4219,9 @@ File: gawk.info, Node: Regexp Summary, Prev: Strong Regexp Constants, Up: Reg 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 @@ -13565,6 +13616,10 @@ contexts. '"array"' X is an array. + '"regexp"' + X is a strongly typed regexp (*note Strong Regexp + Constants::). + '"number"' X is a number. @@ -13611,7 +13666,8 @@ parameter is an array or not. 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. +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 @@ -35235,499 +35291,499 @@ Node: Case-sensitivity185954 Ref: Case-sensitivity-Footnote-1188850 Ref: Case-sensitivity-Footnote-2189085 Node: Strong Regexp Constants189193 -Node: Regexp Summary189982 -Node: Reading Files191457 -Node: Records193620 -Node: awk split records194353 -Node: gawk split records199284 -Ref: gawk split records-Footnote-1203824 -Node: Fields203861 -Node: Nonconstant Fields206602 -Ref: Nonconstant Fields-Footnote-1208838 -Node: Changing Fields209042 -Node: Field Separators214970 -Node: Default Field Splitting217668 -Node: Regexp Field Splitting218786 -Node: Single Character Fields222139 -Node: Command Line Field Separator223199 -Node: Full Line Fields226417 -Ref: Full Line Fields-Footnote-1227939 -Ref: Full Line Fields-Footnote-2227985 -Node: Field Splitting Summary228086 -Node: Constant Size230160 -Node: Splitting By Content234738 -Ref: Splitting By Content-Footnote-1238709 -Node: Multiple Line238872 -Ref: Multiple Line-Footnote-1244754 -Node: Getline244933 -Node: Plain Getline247400 -Node: Getline/Variable250039 -Node: Getline/File251188 -Node: Getline/Variable/File252574 -Ref: Getline/Variable/File-Footnote-1254177 -Node: Getline/Pipe254265 -Node: Getline/Variable/Pipe256970 -Node: Getline/Coprocess258103 -Node: Getline/Variable/Coprocess259368 -Node: Getline Notes260108 -Node: Getline Summary262903 -Ref: table-getline-variants263325 -Node: Read Timeout264073 -Ref: Read Timeout-Footnote-1267979 -Node: Retrying Input268037 -Node: Command-line directories269236 -Node: Input Summary270142 -Node: Input Exercises273314 -Node: Printing274042 -Node: Print275876 -Node: Print Examples277333 -Node: Output Separators280113 -Node: OFMT282130 -Node: Printf283486 -Node: Basic Printf284271 -Node: Control Letters285845 -Node: Format Modifiers289833 -Node: Printf Examples295848 -Node: Redirection298334 -Node: Special FD305175 -Ref: Special FD-Footnote-1308343 -Node: Special Files308417 -Node: Other Inherited Files309034 -Node: Special Network310035 -Node: Special Caveats310895 -Node: Close Files And Pipes311844 -Ref: table-close-pipe-return-values318751 -Ref: Close Files And Pipes-Footnote-1319534 -Ref: Close Files And Pipes-Footnote-2319682 -Node: Nonfatal319834 -Node: Output Summary322159 -Node: Output Exercises323381 -Node: Expressions324060 -Node: Values325248 -Node: Constants325926 -Node: Scalar Constants326617 -Ref: Scalar Constants-Footnote-1327481 -Node: Nondecimal-numbers327731 -Node: Regexp Constants330744 -Node: Using Constant Regexps331270 -Node: Variables334433 -Node: Using Variables335090 -Node: Assignment Options337000 -Node: Conversion338873 -Node: Strings And Numbers339397 -Ref: Strings And Numbers-Footnote-1342460 -Node: Locale influences conversions342569 -Ref: table-locale-affects345327 -Node: All Operators345945 -Node: Arithmetic Ops346574 -Node: Concatenation349080 -Ref: Concatenation-Footnote-1351927 -Node: Assignment Ops352034 -Ref: table-assign-ops357025 -Node: Increment Ops358338 -Node: Truth Values and Conditions361798 -Node: Truth Values362872 -Node: Typing and Comparison363920 -Node: Variable Typing364740 -Node: Comparison Operators368364 -Ref: table-relational-ops368783 -Node: POSIX String Comparison372278 -Ref: POSIX String Comparison-Footnote-1373973 -Ref: POSIX String Comparison-Footnote-2374112 -Node: Boolean Ops374196 -Ref: Boolean Ops-Footnote-1378678 -Node: Conditional Exp378770 -Node: Function Calls380506 -Node: Precedence384383 -Node: Locales388042 -Node: Expressions Summary389674 -Node: Patterns and Actions392247 -Node: Pattern Overview393367 -Node: Regexp Patterns395044 -Node: Expression Patterns395586 -Node: Ranges399367 -Node: BEGIN/END402475 -Node: Using BEGIN/END403236 -Ref: Using BEGIN/END-Footnote-1405972 -Node: I/O And BEGIN/END406078 -Node: BEGINFILE/ENDFILE408392 -Node: Empty411299 -Node: Using Shell Variables411616 -Node: Action Overview413890 -Node: Statements416215 -Node: If Statement418063 -Node: While Statement419558 -Node: Do Statement421586 -Node: For Statement422734 -Node: Switch Statement425892 -Node: Break Statement428278 -Node: Continue Statement430370 -Node: Next Statement432197 -Node: Nextfile Statement434580 -Node: Exit Statement437232 -Node: Built-in Variables439635 -Node: User-modified440768 -Node: Auto-set448354 -Ref: Auto-set-Footnote-1463007 -Ref: Auto-set-Footnote-2463213 -Node: ARGC and ARGV463269 -Node: Pattern Action Summary467482 -Node: Arrays469912 -Node: Array Basics471241 -Node: Array Intro472085 -Ref: figure-array-elements474060 -Ref: Array Intro-Footnote-1476764 -Node: Reference to Elements476892 -Node: Assigning Elements479356 -Node: Array Example479847 -Node: Scanning an Array481606 -Node: Controlling Scanning484628 -Ref: Controlling Scanning-Footnote-1490027 -Node: Numeric Array Subscripts490343 -Node: Uninitialized Subscripts492527 -Node: Delete494146 -Ref: Delete-Footnote-1496898 -Node: Multidimensional496955 -Node: Multiscanning500050 -Node: Arrays of Arrays501641 -Node: Arrays Summary506408 -Node: Functions508501 -Node: Built-in509539 -Node: Calling Built-in510620 -Node: Numeric Functions512616 -Ref: Numeric Functions-Footnote-1517449 -Ref: Numeric Functions-Footnote-2517806 -Ref: Numeric Functions-Footnote-3517854 -Node: String Functions518126 -Ref: String Functions-Footnote-1541630 -Ref: String Functions-Footnote-2541758 -Ref: String Functions-Footnote-3542006 -Node: Gory Details542093 -Ref: table-sub-escapes543884 -Ref: table-sub-proposed545403 -Ref: table-posix-sub546766 -Ref: table-gensub-escapes548307 -Ref: Gory Details-Footnote-1549130 -Node: I/O Functions549284 -Ref: table-system-return-values555866 -Ref: I/O Functions-Footnote-1557846 -Ref: I/O Functions-Footnote-2557994 -Node: Time Functions558114 -Ref: Time Functions-Footnote-1568636 -Ref: Time Functions-Footnote-2568704 -Ref: Time Functions-Footnote-3568862 -Ref: Time Functions-Footnote-4568973 -Ref: Time Functions-Footnote-5569085 -Ref: Time Functions-Footnote-6569312 -Node: Bitwise Functions569578 -Ref: table-bitwise-ops570172 -Ref: Bitwise Functions-Footnote-1574510 -Node: Type Functions574683 -Node: I18N Functions577215 -Node: User-defined578866 -Node: Definition Syntax579671 -Ref: Definition Syntax-Footnote-1585358 -Node: Function Example585429 -Ref: Function Example-Footnote-1588351 -Node: Function Caveats588373 -Node: Calling A Function588891 -Node: Variable Scope589849 -Node: Pass By Value/Reference592843 -Node: Return Statement596342 -Node: Dynamic Typing599321 -Node: Indirect Calls600251 -Ref: Indirect Calls-Footnote-1610502 -Node: Functions Summary610630 -Node: Library Functions613335 -Ref: Library Functions-Footnote-1616942 -Ref: Library Functions-Footnote-2617085 -Node: Library Names617256 -Ref: Library Names-Footnote-1620716 -Ref: Library Names-Footnote-2620939 -Node: General Functions621025 -Node: Strtonum Function622128 -Node: Assert Function625150 -Node: Round Function628476 -Node: Cliff Random Function630017 -Node: Ordinal Functions631033 -Ref: Ordinal Functions-Footnote-1634096 -Ref: Ordinal Functions-Footnote-2634348 -Node: Join Function634558 -Ref: Join Function-Footnote-1636328 -Node: Getlocaltime Function636528 -Node: Readfile Function640270 -Node: Shell Quoting642242 -Node: Data File Management643643 -Node: Filetrans Function644275 -Node: Rewind Function648371 -Node: File Checking650277 -Ref: File Checking-Footnote-1651611 -Node: Empty Files651812 -Node: Ignoring Assigns653791 -Node: Getopt Function655341 -Ref: Getopt Function-Footnote-1666810 -Node: Passwd Functions667010 -Ref: Passwd Functions-Footnote-1675849 -Node: Group Functions675937 -Ref: Group Functions-Footnote-1683835 -Node: Walking Arrays684042 -Node: Library Functions Summary687050 -Node: Library Exercises688456 -Node: Sample Programs688921 -Node: Running Examples689691 -Node: Clones690419 -Node: Cut Program691643 -Node: Egrep Program701572 -Ref: Egrep Program-Footnote-1709084 -Node: Id Program709194 -Node: Split Program712874 -Ref: Split Program-Footnote-1716333 -Node: Tee Program716462 -Node: Uniq Program719252 -Node: Wc Program726678 -Ref: Wc Program-Footnote-1730933 -Node: Miscellaneous Programs731027 -Node: Dupword Program732240 -Node: Alarm Program734270 -Node: Translate Program739125 -Ref: Translate Program-Footnote-1743690 -Node: Labels Program743960 -Ref: Labels Program-Footnote-1747311 -Node: Word Sorting747395 -Node: History Sorting751467 -Node: Extract Program753302 -Node: Simple Sed760831 -Node: Igawk Program763905 -Ref: Igawk Program-Footnote-1778236 -Ref: Igawk Program-Footnote-2778438 -Ref: Igawk Program-Footnote-3778560 -Node: Anagram Program778675 -Node: Signature Program781737 -Node: Programs Summary782984 -Node: Programs Exercises784198 -Ref: Programs Exercises-Footnote-1788327 -Node: Advanced Features788418 -Node: Nondecimal Data790408 -Node: Array Sorting791999 -Node: Controlling Array Traversal792699 -Ref: Controlling Array Traversal-Footnote-1801066 -Node: Array Sorting Functions801184 -Ref: Array Sorting Functions-Footnote-1806275 -Node: Two-way I/O806471 -Ref: Two-way I/O-Footnote-1813021 -Ref: Two-way I/O-Footnote-2813208 -Node: TCP/IP Networking813290 -Node: Profiling816408 -Ref: Profiling-Footnote-1824901 -Node: Advanced Features Summary825224 -Node: Internationalization827068 -Node: I18N and L10N828548 -Node: Explaining gettext829235 -Ref: Explaining gettext-Footnote-1835127 -Ref: Explaining gettext-Footnote-2835312 -Node: Programmer i18n835477 -Ref: Programmer i18n-Footnote-1840332 -Node: Translator i18n840381 -Node: String Extraction841175 -Ref: String Extraction-Footnote-1842307 -Node: Printf Ordering842393 -Ref: Printf Ordering-Footnote-1845179 -Node: I18N Portability845243 -Ref: I18N Portability-Footnote-1847699 -Node: I18N Example847762 -Ref: I18N Example-Footnote-1850568 -Node: Gawk I18N850641 -Node: I18N Summary851286 -Node: Debugger852627 -Node: Debugging853649 -Node: Debugging Concepts854090 -Node: Debugging Terms855899 -Node: Awk Debugging858474 -Node: Sample Debugging Session859380 -Node: Debugger Invocation859914 -Node: Finding The Bug861300 -Node: List of Debugger Commands867778 -Node: Breakpoint Control869111 -Node: Debugger Execution Control872805 -Node: Viewing And Changing Data876167 -Node: Execution Stack879541 -Node: Debugger Info881178 -Node: Miscellaneous Debugger Commands885249 -Node: Readline Support890337 -Node: Limitations891233 -Ref: Limitations-Footnote-1895464 -Node: Debugging Summary895515 -Node: Arbitrary Precision Arithmetic896794 -Node: Computer Arithmetic898210 -Ref: table-numeric-ranges901801 -Ref: Computer Arithmetic-Footnote-1902523 -Node: Math Definitions902580 -Ref: table-ieee-formats905894 -Ref: Math Definitions-Footnote-1906497 -Node: MPFR features906602 -Node: FP Math Caution908319 -Ref: FP Math Caution-Footnote-1909391 -Node: Inexactness of computations909760 -Node: Inexact representation910720 -Node: Comparing FP Values912080 -Node: Errors accumulate913162 -Node: Getting Accuracy914595 -Node: Try To Round917305 -Node: Setting precision918204 -Ref: table-predefined-precision-strings918901 -Node: Setting the rounding mode920731 -Ref: table-gawk-rounding-modes921105 -Ref: Setting the rounding mode-Footnote-1924513 -Node: Arbitrary Precision Integers924692 -Ref: Arbitrary Precision Integers-Footnote-1929609 -Node: POSIX Floating Point Problems929758 -Ref: POSIX Floating Point Problems-Footnote-1933640 -Node: Floating point summary933678 -Node: Dynamic Extensions935868 -Node: Extension Intro937421 -Node: Plugin License938687 -Node: Extension Mechanism Outline939484 -Ref: figure-load-extension939923 -Ref: figure-register-new-function941488 -Ref: figure-call-new-function942580 -Node: Extension API Description944642 -Node: Extension API Functions Introduction946174 -Node: General Data Types951033 -Ref: General Data Types-Footnote-1956988 -Node: Memory Allocation Functions957287 -Ref: Memory Allocation Functions-Footnote-1960132 -Node: Constructor Functions960231 -Node: Registration Functions961976 -Node: Extension Functions962661 -Node: Exit Callback Functions965284 -Node: Extension Version String966534 -Node: Input Parsers967197 -Node: Output Wrappers977079 -Node: Two-way processors981591 -Node: Printing Messages983856 -Ref: Printing Messages-Footnote-1985027 -Node: Updating ERRNO985180 -Node: Requesting Values985919 -Ref: table-value-types-returned986656 -Node: Accessing Parameters987539 -Node: Symbol Table Access988774 -Node: Symbol table by name989286 -Node: Symbol table by cookie991307 -Ref: Symbol table by cookie-Footnote-1995459 -Node: Cached values995523 -Ref: Cached values-Footnote-1999030 -Node: Array Manipulation999121 -Ref: Array Manipulation-Footnote-11000212 -Node: Array Data Types1000249 -Ref: Array Data Types-Footnote-11002907 -Node: Array Functions1002999 -Node: Flattening Arrays1006857 -Node: Creating Arrays1013765 -Node: Redirection API1018534 -Node: Extension API Variables1021365 -Node: Extension Versioning1021998 -Ref: gawk-api-version1022435 -Node: Extension API Informational Variables1024191 -Node: Extension API Boilerplate1025255 -Node: Finding Extensions1029069 -Node: Extension Example1029628 -Node: Internal File Description1030426 -Node: Internal File Ops1034506 -Ref: Internal File Ops-Footnote-11046268 -Node: Using Internal File Ops1046408 -Ref: Using Internal File Ops-Footnote-11048791 -Node: Extension Samples1049065 -Node: Extension Sample File Functions1050594 -Node: Extension Sample Fnmatch1058243 -Node: Extension Sample Fork1059730 -Node: Extension Sample Inplace1060948 -Node: Extension Sample Ord1064158 -Node: Extension Sample Readdir1064994 -Ref: table-readdir-file-types1065883 -Node: Extension Sample Revout1066688 -Node: Extension Sample Rev2way1067277 -Node: Extension Sample Read write array1068017 -Node: Extension Sample Readfile1069959 -Node: Extension Sample Time1071054 -Node: Extension Sample API Tests1072402 -Node: gawkextlib1072894 -Node: Extension summary1075341 -Node: Extension Exercises1079043 -Node: Language History1080541 -Node: V7/SVR3.11082197 -Node: SVR41084349 -Node: POSIX1085783 -Node: BTL1087162 -Node: POSIX/GNU1087891 -Node: Feature History1093753 -Node: Common Extensions1108123 -Node: Ranges and Locales1109406 -Ref: Ranges and Locales-Footnote-11114022 -Ref: Ranges and Locales-Footnote-21114049 -Ref: Ranges and Locales-Footnote-31114284 -Node: Contributors1114505 -Node: History summary1120065 -Node: Installation1121445 -Node: Gawk Distribution1122389 -Node: Getting1122873 -Node: Extracting1123834 -Node: Distribution contents1125472 -Node: Unix Installation1131557 -Node: Quick Installation1132239 -Node: Shell Startup Files1134653 -Node: Additional Configuration Options1135731 -Node: Configuration Philosophy1137536 -Node: Non-Unix Installation1139905 -Node: PC Installation1140365 -Node: PC Binary Installation1141203 -Node: PC Compiling1141638 -Node: PC Using1142755 -Node: Cygwin1145800 -Node: MSYS1146570 -Node: VMS Installation1147071 -Node: VMS Compilation1147862 -Ref: VMS Compilation-Footnote-11149091 -Node: VMS Dynamic Extensions1149149 -Node: VMS Installation Details1150834 -Node: VMS Running1153087 -Node: VMS GNV1157366 -Node: VMS Old Gawk1158101 -Node: Bugs1158572 -Node: Bug address1159235 -Node: Usenet1161632 -Node: Maintainers1162407 -Node: Other Versions1163783 -Node: Installation summary1170367 -Node: Notes1171402 -Node: Compatibility Mode1172267 -Node: Additions1173049 -Node: Accessing The Source1173974 -Node: Adding Code1175409 -Node: New Ports1181628 -Node: Derived Files1186116 -Ref: Derived Files-Footnote-11191601 -Ref: Derived Files-Footnote-21191636 -Ref: Derived Files-Footnote-31192234 -Node: Future Extensions1192348 -Node: Implementation Limitations1193006 -Node: Extension Design1194189 -Node: Old Extension Problems1195343 -Ref: Old Extension Problems-Footnote-11196861 -Node: Extension New Mechanism Goals1196918 -Ref: Extension New Mechanism Goals-Footnote-11200282 -Node: Extension Other Design Decisions1200471 -Node: Extension Future Growth1202584 -Node: Old Extension Mechanism1203420 -Node: Notes summary1205183 -Node: Basic Concepts1206365 -Node: Basic High Level1207046 -Ref: figure-general-flow1207328 -Ref: figure-process-flow1208013 -Ref: Basic High Level-Footnote-11211314 -Node: Basic Data Typing1211499 -Node: Glossary1214827 -Node: Copying1246774 -Node: GNU Free Documentation License1284313 -Node: Index1309431 +Node: Regexp Summary192135 +Node: Reading Files193741 +Node: Records195904 +Node: awk split records196637 +Node: gawk split records201568 +Ref: gawk split records-Footnote-1206108 +Node: Fields206145 +Node: Nonconstant Fields208886 +Ref: Nonconstant Fields-Footnote-1211122 +Node: Changing Fields211326 +Node: Field Separators217254 +Node: Default Field Splitting219952 +Node: Regexp Field Splitting221070 +Node: Single Character Fields224423 +Node: Command Line Field Separator225483 +Node: Full Line Fields228701 +Ref: Full Line Fields-Footnote-1230223 +Ref: Full Line Fields-Footnote-2230269 +Node: Field Splitting Summary230370 +Node: Constant Size232444 +Node: Splitting By Content237022 +Ref: Splitting By Content-Footnote-1240993 +Node: Multiple Line241156 +Ref: Multiple Line-Footnote-1247038 +Node: Getline247217 +Node: Plain Getline249684 +Node: Getline/Variable252323 +Node: Getline/File253472 +Node: Getline/Variable/File254858 +Ref: Getline/Variable/File-Footnote-1256461 +Node: Getline/Pipe256549 +Node: Getline/Variable/Pipe259254 +Node: Getline/Coprocess260387 +Node: Getline/Variable/Coprocess261652 +Node: Getline Notes262392 +Node: Getline Summary265187 +Ref: table-getline-variants265609 +Node: Read Timeout266357 +Ref: Read Timeout-Footnote-1270263 +Node: Retrying Input270321 +Node: Command-line directories271520 +Node: Input Summary272426 +Node: Input Exercises275598 +Node: Printing276326 +Node: Print278160 +Node: Print Examples279617 +Node: Output Separators282397 +Node: OFMT284414 +Node: Printf285770 +Node: Basic Printf286555 +Node: Control Letters288129 +Node: Format Modifiers292117 +Node: Printf Examples298132 +Node: Redirection300618 +Node: Special FD307459 +Ref: Special FD-Footnote-1310627 +Node: Special Files310701 +Node: Other Inherited Files311318 +Node: Special Network312319 +Node: Special Caveats313179 +Node: Close Files And Pipes314128 +Ref: table-close-pipe-return-values321035 +Ref: Close Files And Pipes-Footnote-1321818 +Ref: Close Files And Pipes-Footnote-2321966 +Node: Nonfatal322118 +Node: Output Summary324443 +Node: Output Exercises325665 +Node: Expressions326344 +Node: Values327532 +Node: Constants328210 +Node: Scalar Constants328901 +Ref: Scalar Constants-Footnote-1329765 +Node: Nondecimal-numbers330015 +Node: Regexp Constants333028 +Node: Using Constant Regexps333554 +Node: Variables336717 +Node: Using Variables337374 +Node: Assignment Options339284 +Node: Conversion341157 +Node: Strings And Numbers341681 +Ref: Strings And Numbers-Footnote-1344744 +Node: Locale influences conversions344853 +Ref: table-locale-affects347611 +Node: All Operators348229 +Node: Arithmetic Ops348858 +Node: Concatenation351364 +Ref: Concatenation-Footnote-1354211 +Node: Assignment Ops354318 +Ref: table-assign-ops359309 +Node: Increment Ops360622 +Node: Truth Values and Conditions364082 +Node: Truth Values365156 +Node: Typing and Comparison366204 +Node: Variable Typing367024 +Node: Comparison Operators370648 +Ref: table-relational-ops371067 +Node: POSIX String Comparison374562 +Ref: POSIX String Comparison-Footnote-1376257 +Ref: POSIX String Comparison-Footnote-2376396 +Node: Boolean Ops376480 +Ref: Boolean Ops-Footnote-1380962 +Node: Conditional Exp381054 +Node: Function Calls382790 +Node: Precedence386667 +Node: Locales390326 +Node: Expressions Summary391958 +Node: Patterns and Actions394531 +Node: Pattern Overview395651 +Node: Regexp Patterns397328 +Node: Expression Patterns397870 +Node: Ranges401651 +Node: BEGIN/END404759 +Node: Using BEGIN/END405520 +Ref: Using BEGIN/END-Footnote-1408256 +Node: I/O And BEGIN/END408362 +Node: BEGINFILE/ENDFILE410676 +Node: Empty413583 +Node: Using Shell Variables413900 +Node: Action Overview416174 +Node: Statements418499 +Node: If Statement420347 +Node: While Statement421842 +Node: Do Statement423870 +Node: For Statement425018 +Node: Switch Statement428176 +Node: Break Statement430562 +Node: Continue Statement432654 +Node: Next Statement434481 +Node: Nextfile Statement436864 +Node: Exit Statement439516 +Node: Built-in Variables441919 +Node: User-modified443052 +Node: Auto-set450638 +Ref: Auto-set-Footnote-1465291 +Ref: Auto-set-Footnote-2465497 +Node: ARGC and ARGV465553 +Node: Pattern Action Summary469766 +Node: Arrays472196 +Node: Array Basics473525 +Node: Array Intro474369 +Ref: figure-array-elements476344 +Ref: Array Intro-Footnote-1479048 +Node: Reference to Elements479176 +Node: Assigning Elements481640 +Node: Array Example482131 +Node: Scanning an Array483890 +Node: Controlling Scanning486912 +Ref: Controlling Scanning-Footnote-1492311 +Node: Numeric Array Subscripts492627 +Node: Uninitialized Subscripts494811 +Node: Delete496430 +Ref: Delete-Footnote-1499182 +Node: Multidimensional499239 +Node: Multiscanning502334 +Node: Arrays of Arrays503925 +Node: Arrays Summary508692 +Node: Functions510785 +Node: Built-in511823 +Node: Calling Built-in512904 +Node: Numeric Functions514900 +Ref: Numeric Functions-Footnote-1519733 +Ref: Numeric Functions-Footnote-2520090 +Ref: Numeric Functions-Footnote-3520138 +Node: String Functions520410 +Ref: String Functions-Footnote-1543914 +Ref: String Functions-Footnote-2544042 +Ref: String Functions-Footnote-3544290 +Node: Gory Details544377 +Ref: table-sub-escapes546168 +Ref: table-sub-proposed547687 +Ref: table-posix-sub549050 +Ref: table-gensub-escapes550591 +Ref: Gory Details-Footnote-1551414 +Node: I/O Functions551568 +Ref: table-system-return-values558150 +Ref: I/O Functions-Footnote-1560130 +Ref: I/O Functions-Footnote-2560278 +Node: Time Functions560398 +Ref: Time Functions-Footnote-1570920 +Ref: Time Functions-Footnote-2570988 +Ref: Time Functions-Footnote-3571146 +Ref: Time Functions-Footnote-4571257 +Ref: Time Functions-Footnote-5571369 +Ref: Time Functions-Footnote-6571596 +Node: Bitwise Functions571862 +Ref: table-bitwise-ops572456 +Ref: Bitwise Functions-Footnote-1576794 +Node: Type Functions576967 +Node: I18N Functions579628 +Node: User-defined581279 +Node: Definition Syntax582084 +Ref: Definition Syntax-Footnote-1587771 +Node: Function Example587842 +Ref: Function Example-Footnote-1590764 +Node: Function Caveats590786 +Node: Calling A Function591304 +Node: Variable Scope592262 +Node: Pass By Value/Reference595256 +Node: Return Statement598755 +Node: Dynamic Typing601734 +Node: Indirect Calls602664 +Ref: Indirect Calls-Footnote-1612915 +Node: Functions Summary613043 +Node: Library Functions615748 +Ref: Library Functions-Footnote-1619355 +Ref: Library Functions-Footnote-2619498 +Node: Library Names619669 +Ref: Library Names-Footnote-1623129 +Ref: Library Names-Footnote-2623352 +Node: General Functions623438 +Node: Strtonum Function624541 +Node: Assert Function627563 +Node: Round Function630889 +Node: Cliff Random Function632430 +Node: Ordinal Functions633446 +Ref: Ordinal Functions-Footnote-1636509 +Ref: Ordinal Functions-Footnote-2636761 +Node: Join Function636971 +Ref: Join Function-Footnote-1638741 +Node: Getlocaltime Function638941 +Node: Readfile Function642683 +Node: Shell Quoting644655 +Node: Data File Management646056 +Node: Filetrans Function646688 +Node: Rewind Function650784 +Node: File Checking652690 +Ref: File Checking-Footnote-1654024 +Node: Empty Files654225 +Node: Ignoring Assigns656204 +Node: Getopt Function657754 +Ref: Getopt Function-Footnote-1669223 +Node: Passwd Functions669423 +Ref: Passwd Functions-Footnote-1678262 +Node: Group Functions678350 +Ref: Group Functions-Footnote-1686248 +Node: Walking Arrays686455 +Node: Library Functions Summary689463 +Node: Library Exercises690869 +Node: Sample Programs691334 +Node: Running Examples692104 +Node: Clones692832 +Node: Cut Program694056 +Node: Egrep Program703985 +Ref: Egrep Program-Footnote-1711497 +Node: Id Program711607 +Node: Split Program715287 +Ref: Split Program-Footnote-1718746 +Node: Tee Program718875 +Node: Uniq Program721665 +Node: Wc Program729091 +Ref: Wc Program-Footnote-1733346 +Node: Miscellaneous Programs733440 +Node: Dupword Program734653 +Node: Alarm Program736683 +Node: Translate Program741538 +Ref: Translate Program-Footnote-1746103 +Node: Labels Program746373 +Ref: Labels Program-Footnote-1749724 +Node: Word Sorting749808 +Node: History Sorting753880 +Node: Extract Program755715 +Node: Simple Sed763244 +Node: Igawk Program766318 +Ref: Igawk Program-Footnote-1780649 +Ref: Igawk Program-Footnote-2780851 +Ref: Igawk Program-Footnote-3780973 +Node: Anagram Program781088 +Node: Signature Program784150 +Node: Programs Summary785397 +Node: Programs Exercises786611 +Ref: Programs Exercises-Footnote-1790740 +Node: Advanced Features790831 +Node: Nondecimal Data792821 +Node: Array Sorting794412 +Node: Controlling Array Traversal795112 +Ref: Controlling Array Traversal-Footnote-1803479 +Node: Array Sorting Functions803597 +Ref: Array Sorting Functions-Footnote-1808688 +Node: Two-way I/O808884 +Ref: Two-way I/O-Footnote-1815434 +Ref: Two-way I/O-Footnote-2815621 +Node: TCP/IP Networking815703 +Node: Profiling818821 +Ref: Profiling-Footnote-1827314 +Node: Advanced Features Summary827637 +Node: Internationalization829481 +Node: I18N and L10N830961 +Node: Explaining gettext831648 +Ref: Explaining gettext-Footnote-1837540 +Ref: Explaining gettext-Footnote-2837725 +Node: Programmer i18n837890 +Ref: Programmer i18n-Footnote-1842745 +Node: Translator i18n842794 +Node: String Extraction843588 +Ref: String Extraction-Footnote-1844720 +Node: Printf Ordering844806 +Ref: Printf Ordering-Footnote-1847592 +Node: I18N Portability847656 +Ref: I18N Portability-Footnote-1850112 +Node: I18N Example850175 +Ref: I18N Example-Footnote-1852981 +Node: Gawk I18N853054 +Node: I18N Summary853699 +Node: Debugger855040 +Node: Debugging856062 +Node: Debugging Concepts856503 +Node: Debugging Terms858312 +Node: Awk Debugging860887 +Node: Sample Debugging Session861793 +Node: Debugger Invocation862327 +Node: Finding The Bug863713 +Node: List of Debugger Commands870191 +Node: Breakpoint Control871524 +Node: Debugger Execution Control875218 +Node: Viewing And Changing Data878580 +Node: Execution Stack881954 +Node: Debugger Info883591 +Node: Miscellaneous Debugger Commands887662 +Node: Readline Support892750 +Node: Limitations893646 +Ref: Limitations-Footnote-1897877 +Node: Debugging Summary897928 +Node: Arbitrary Precision Arithmetic899207 +Node: Computer Arithmetic900623 +Ref: table-numeric-ranges904214 +Ref: Computer Arithmetic-Footnote-1904936 +Node: Math Definitions904993 +Ref: table-ieee-formats908307 +Ref: Math Definitions-Footnote-1908910 +Node: MPFR features909015 +Node: FP Math Caution910732 +Ref: FP Math Caution-Footnote-1911804 +Node: Inexactness of computations912173 +Node: Inexact representation913133 +Node: Comparing FP Values914493 +Node: Errors accumulate915575 +Node: Getting Accuracy917008 +Node: Try To Round919718 +Node: Setting precision920617 +Ref: table-predefined-precision-strings921314 +Node: Setting the rounding mode923144 +Ref: table-gawk-rounding-modes923518 +Ref: Setting the rounding mode-Footnote-1926926 +Node: Arbitrary Precision Integers927105 +Ref: Arbitrary Precision Integers-Footnote-1932022 +Node: POSIX Floating Point Problems932171 +Ref: POSIX Floating Point Problems-Footnote-1936053 +Node: Floating point summary936091 +Node: Dynamic Extensions938281 +Node: Extension Intro939834 +Node: Plugin License941100 +Node: Extension Mechanism Outline941897 +Ref: figure-load-extension942336 +Ref: figure-register-new-function943901 +Ref: figure-call-new-function944993 +Node: Extension API Description947055 +Node: Extension API Functions Introduction948587 +Node: General Data Types953446 +Ref: General Data Types-Footnote-1959401 +Node: Memory Allocation Functions959700 +Ref: Memory Allocation Functions-Footnote-1962545 +Node: Constructor Functions962644 +Node: Registration Functions964389 +Node: Extension Functions965074 +Node: Exit Callback Functions967697 +Node: Extension Version String968947 +Node: Input Parsers969610 +Node: Output Wrappers979492 +Node: Two-way processors984004 +Node: Printing Messages986269 +Ref: Printing Messages-Footnote-1987440 +Node: Updating ERRNO987593 +Node: Requesting Values988332 +Ref: table-value-types-returned989069 +Node: Accessing Parameters989952 +Node: Symbol Table Access991187 +Node: Symbol table by name991699 +Node: Symbol table by cookie993720 +Ref: Symbol table by cookie-Footnote-1997872 +Node: Cached values997936 +Ref: Cached values-Footnote-11001443 +Node: Array Manipulation1001534 +Ref: Array Manipulation-Footnote-11002625 +Node: Array Data Types1002662 +Ref: Array Data Types-Footnote-11005320 +Node: Array Functions1005412 +Node: Flattening Arrays1009270 +Node: Creating Arrays1016178 +Node: Redirection API1020947 +Node: Extension API Variables1023778 +Node: Extension Versioning1024411 +Ref: gawk-api-version1024848 +Node: Extension API Informational Variables1026604 +Node: Extension API Boilerplate1027668 +Node: Finding Extensions1031482 +Node: Extension Example1032041 +Node: Internal File Description1032839 +Node: Internal File Ops1036919 +Ref: Internal File Ops-Footnote-11048681 +Node: Using Internal File Ops1048821 +Ref: Using Internal File Ops-Footnote-11051204 +Node: Extension Samples1051478 +Node: Extension Sample File Functions1053007 +Node: Extension Sample Fnmatch1060656 +Node: Extension Sample Fork1062143 +Node: Extension Sample Inplace1063361 +Node: Extension Sample Ord1066571 +Node: Extension Sample Readdir1067407 +Ref: table-readdir-file-types1068296 +Node: Extension Sample Revout1069101 +Node: Extension Sample Rev2way1069690 +Node: Extension Sample Read write array1070430 +Node: Extension Sample Readfile1072372 +Node: Extension Sample Time1073467 +Node: Extension Sample API Tests1074815 +Node: gawkextlib1075307 +Node: Extension summary1077754 +Node: Extension Exercises1081456 +Node: Language History1082954 +Node: V7/SVR3.11084610 +Node: SVR41086762 +Node: POSIX1088196 +Node: BTL1089575 +Node: POSIX/GNU1090304 +Node: Feature History1096166 +Node: Common Extensions1110536 +Node: Ranges and Locales1111819 +Ref: Ranges and Locales-Footnote-11116435 +Ref: Ranges and Locales-Footnote-21116462 +Ref: Ranges and Locales-Footnote-31116697 +Node: Contributors1116918 +Node: History summary1122478 +Node: Installation1123858 +Node: Gawk Distribution1124802 +Node: Getting1125286 +Node: Extracting1126247 +Node: Distribution contents1127885 +Node: Unix Installation1133970 +Node: Quick Installation1134652 +Node: Shell Startup Files1137066 +Node: Additional Configuration Options1138144 +Node: Configuration Philosophy1139949 +Node: Non-Unix Installation1142318 +Node: PC Installation1142778 +Node: PC Binary Installation1143616 +Node: PC Compiling1144051 +Node: PC Using1145168 +Node: Cygwin1148213 +Node: MSYS1148983 +Node: VMS Installation1149484 +Node: VMS Compilation1150275 +Ref: VMS Compilation-Footnote-11151504 +Node: VMS Dynamic Extensions1151562 +Node: VMS Installation Details1153247 +Node: VMS Running1155500 +Node: VMS GNV1159779 +Node: VMS Old Gawk1160514 +Node: Bugs1160985 +Node: Bug address1161648 +Node: Usenet1164045 +Node: Maintainers1164820 +Node: Other Versions1166196 +Node: Installation summary1172780 +Node: Notes1173815 +Node: Compatibility Mode1174680 +Node: Additions1175462 +Node: Accessing The Source1176387 +Node: Adding Code1177822 +Node: New Ports1184041 +Node: Derived Files1188529 +Ref: Derived Files-Footnote-11194014 +Ref: Derived Files-Footnote-21194049 +Ref: Derived Files-Footnote-31194647 +Node: Future Extensions1194761 +Node: Implementation Limitations1195419 +Node: Extension Design1196602 +Node: Old Extension Problems1197756 +Ref: Old Extension Problems-Footnote-11199274 +Node: Extension New Mechanism Goals1199331 +Ref: Extension New Mechanism Goals-Footnote-11202695 +Node: Extension Other Design Decisions1202884 +Node: Extension Future Growth1204997 +Node: Old Extension Mechanism1205833 +Node: Notes summary1207596 +Node: Basic Concepts1208778 +Node: Basic High Level1209459 +Ref: figure-general-flow1209741 +Ref: figure-process-flow1210426 +Ref: Basic High Level-Footnote-11213727 +Node: Basic Data Typing1213912 +Node: Glossary1217240 +Node: Copying1249187 +Node: GNU Free Documentation License1286726 +Node: Index1311844 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index adc5c917..dd4af936 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -6284,6 +6284,70 @@ 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 @@ -6327,6 +6391,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 @@ -19515,6 +19584,9 @@ Return one of the following strings, depending upon the type of @var{x}: @item "array" @var{x} is an array. +@item "regexp" +@var{x} is a strongly typed regexp (@pxref{Strong Regexp Constants}). + @item "number" @var{x} is a number. @@ -19571,7 +19643,8 @@ 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. +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 diff --git a/doc/gawktexi.in b/doc/gawktexi.in index afcf749a..6dae0186 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -6068,6 +6068,70 @@ 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 @@ -6111,6 +6175,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 @@ -18627,6 +18696,9 @@ Return one of the following strings, depending upon the type of @var{x}: @item "array" @var{x} is an array. +@item "regexp" +@var{x} is a strongly typed regexp (@pxref{Strong Regexp Constants}). + @item "number" @var{x} is a number. @@ -18683,7 +18755,8 @@ 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. +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 |