diff options
Diffstat (limited to 'doc/regex-add-doc.diff')
| -rw-r--r-- | doc/regex-add-doc.diff | 107 |
1 files changed, 107 insertions, 0 deletions
diff --git a/doc/regex-add-doc.diff b/doc/regex-add-doc.diff new file mode 100644 index 00000000..93b2a6ee --- /dev/null +++ b/doc/regex-add-doc.diff @@ -0,0 +1,107 @@ +diff --git a/tmp/gawktexi.in b/doc/gawktexi.in +index 14a1748..6159450 100644 +--- a/tmp/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 + + +@@ -18681,6 +18750,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. + +@@ -18737,7 +18809,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 |