util/X86LINUX64/man/mann/regsub.n

   1 '\"
   2 '\" Copyright (c) 1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\" Copyright (c) 2000 Scriptics Corporation.
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .TH regsub n 8.3 Tcl "Tcl Built-In Commands"
  10 .\" The -*- nroff -*- definitions below are for supplemental macros used
  11 .\" in Tcl/Tk manual entries.
  12 .\"
  13 .\" .AP type name in/out ?indent?
  14 .\"     Start paragraph describing an argument to a library procedure.
  15 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  16 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  17 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  18 .\"     needed;  use .AS below instead)
  19 .\"
  20 .\" .AS ?type? ?name?
  21 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  22 .\"     name are examples of largest possible arguments that will be passed
  23 .\"     to .AP later.  If args are omitted, default tab stops are used.
  24 .\"
  25 .\" .BS
  26 .\"     Start box enclosure.  From here until next .BE, everything will be
  27 .\"     enclosed in one large box.
  28 .\"
  29 .\" .BE
  30 .\"     End of box enclosure.
  31 .\"
  32 .\" .CS
  33 .\"     Begin code excerpt.
  34 .\"
  35 .\" .CE
  36 .\"     End code excerpt.
  37 .\"
  38 .\" .VS ?version? ?br?
  39 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  40 .\"     of man pages.  The first argument is ignored and used for recording
  41 .\"     the version when the .VS was added, so that the sidebars can be
  42 .\"     found and removed when they reach a certain age.  If another argument
  43 .\"     is present, then a line break is forced before starting the sidebar.
  44 .\"
  45 .\" .VE
  46 .\"     End of vertical sidebar.
  47 .\"
  48 .\" .DS
  49 .\"     Begin an indented unfilled display.
  50 .\"
  51 .\" .DE
  52 .\"     End of indented unfilled display.
  53 .\"
  54 .\" .SO ?manpage?
  55 .\"     Start of list of standard options for a Tk widget. The manpage
  56 .\"     argument defines where to look up the standard options; if
  57 .\"     omitted, defaults to "options". The options follow on successive
  58 .\"     lines, in three columns separated by tabs.
  59 .\"
  60 .\" .SE
  61 .\"     End of list of standard options for a Tk widget.
  62 .\"
  63 .\" .OP cmdName dbName dbClass
  64 .\"     Start of description of a specific option.  cmdName gives the
  65 .\"     option's name as specified in the class command, dbName gives
  66 .\"     the option's name in the option database, and dbClass gives
  67 .\"     the option's class in the option database.
  68 .\"
  69 .\" .UL arg1 arg2
  70 .\"     Print arg1 underlined, then print arg2 normally.
  71 .\"
  72 .\" .QW arg1 ?arg2?
  73 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  74 .\"
  75 .\" .PQ arg1 ?arg2?
  76 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  77 .\"     (for trailing punctuation) and then a closing parenthesis.
  78 .\"
  79 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  80 .if t .wh -1.3i ^B
  81 .nr ^l \n(.l
  82 .ad b
  83 .\"     # Start an argument description
  84 .de AP
  85 .ie !"\\$4"" .TP \\$4
  86 .el \{\
  87 .   ie !"\\$2"" .TP \\n()Cu
  88 .   el          .TP 15
  89 .\}
  90 .ta \\n()Au \\n()Bu
  91 .ie !"\\$3"" \{\
  92 \&\\$1 \\fI\\$2\\fP (\\$3)
  93 .\".b
  94 .\}
  95 .el \{\
  96 .br
  97 .ie !"\\$2"" \{\
  98 \&\\$1  \\fI\\$2\\fP
  99 .\}
 100 .el \{\
 101 \&\\fI\\$1\\fP
 102 .\}
 103 .\}
 104 ..
 105 .\"     # define tabbing values for .AP
 106 .de AS
 107 .nr )A 10n
 108 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 109 .nr )B \\n()Au+15n
 110 .\"
 111 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 112 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 113 ..
 114 .AS Tcl_Interp Tcl_CreateInterp in/out
 115 .\"     # BS - start boxed text
 116 .\"     # ^y = starting y location
 117 .\"     # ^b = 1
 118 .de BS
 119 .br
 120 .mk ^y
 121 .nr ^b 1u
 122 .if n .nf
 123 .if n .ti 0
 124 .if n \l'\\n(.lu\(ul'
 125 .if n .fi
 126 ..
 127 .\"     # BE - end boxed text (draw box now)
 128 .de BE
 129 .nf
 130 .ti 0
 131 .mk ^t
 132 .ie n \l'\\n(^lu\(ul'
 133 .el \{\
 134 .\"     Draw four-sided box normally, but don't draw top of
 135 .\"     box if the box started on an earlier page.
 136 .ie !\\n(^b-1 \{\
 137 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 138 .\}
 139 .el \}\
 140 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 141 .\}
 142 .\}
 143 .fi
 144 .br
 145 .nr ^b 0
 146 ..
 147 .\"     # VS - start vertical sidebar
 148 .\"     # ^Y = starting y location
 149 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 150 .de VS
 151 .if !"\\$2"" .br
 152 .mk ^Y
 153 .ie n 'mc \s12\(br\s0
 154 .el .nr ^v 1u
 155 ..
 156 .\"     # VE - end of vertical sidebar
 157 .de VE
 158 .ie n 'mc
 159 .el \{\
 160 .ev 2
 161 .nf
 162 .ti 0
 163 .mk ^t
 164 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 165 .sp -1
 166 .fi
 167 .ev
 168 .\}
 169 .nr ^v 0
 170 ..
 171 .\"     # Special macro to handle page bottom:  finish off current
 172 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 173 .\"     # page bottom macro.
 174 .de ^B
 175 .ev 2
 176 'ti 0
 177 'nf
 178 .mk ^t
 179 .if \\n(^b \{\
 180 .\"     Draw three-sided box if this is the box's first page,
 181 .\"     draw two sides but no top otherwise.
 182 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 184 .\}
 185 .if \\n(^v \{\
 186 .nr ^x \\n(^tu+1v-\\n(^Yu
 187 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 188 .\}
 189 .bp
 190 'fi
 191 .ev
 192 .if \\n(^b \{\
 193 .mk ^y
 194 .nr ^b 2
 195 .\}
 196 .if \\n(^v \{\
 197 .mk ^Y
 198 .\}
 199 ..
 200 .\"     # DS - begin display
 201 .de DS
 202 .RS
 203 .nf
 204 .sp
 205 ..
 206 .\"     # DE - end display
 207 .de DE
 208 .fi
 209 .RE
 210 .sp
 211 ..
 212 .\"     # SO - start of list of standard options
 213 .de SO
 214 'ie '\\$1'' .ds So \\fBoptions\\fR
 215 'el .ds So \\fB\\$1\\fR
 216 .SH "STANDARD OPTIONS"
 217 .LP
 218 .nf
 219 .ta 5.5c 11c
 220 .ft B
 221 ..
 222 .\"     # SE - end of list of standard options
 223 .de SE
 224 .fi
 225 .ft R
 226 .LP
 227 See the \\*(So manual entry for details on the standard options.
 228 ..
 229 .\"     # OP - start of full description for a single option
 230 .de OP
 231 .LP
 232 .nf
 233 .ta 4c
 234 Command-Line Name:      \\fB\\$1\\fR
 235 Database Name:  \\fB\\$2\\fR
 236 Database Class: \\fB\\$3\\fR
 237 .fi
 238 .IP
 239 ..
 240 .\"     # CS - begin code excerpt
 241 .de CS
 242 .RS
 243 .nf
 244 .ta .25i .5i .75i 1i
 245 ..
 246 .\"     # CE - end code excerpt
 247 .de CE
 248 .fi
 249 .RE
 250 ..
 251 .\"     # UL - underline word
 252 .de UL
 253 \\$1\l'|0\(ul'\\$2
 254 ..
 255 .\"     # QW - apply quotation marks to word
 256 .de QW
 257 .ie '\\*(lq'"' ``\\$1''\\$2
 258 .\"" fix emacs highlighting
 259 .el \\*(lq\\$1\\*(rq\\$2
 260 ..
 261 .\"     # PQ - apply parens and quotation marks to word
 262 .de PQ
 263 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 264 .\"" fix emacs highlighting
 265 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 266 ..
 267 .\"     # QR - quoted range
 268 .de QR
 269 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 270 .\"" fix emacs highlighting
 271 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 272 ..
 273 .\"     # MT - "empty" string
 274 .de MT
 275 .QW ""
 276 ..
 277 .BS
 278 '\" Note:  do not modify the .SH NAME line immediately below!
 279 .SH NAME
 280 regsub \- Perform substitutions based on regular expression pattern matching
 281 .SH SYNOPSIS
 282 \fBregsub \fR?\fIswitches\fR? \fIexp string subSpec \fR?\fIvarName\fR?
 283 .BE
 284 .SH DESCRIPTION
 285 .PP
 286 This command matches the regular expression \fIexp\fR against
 287 \fIstring\fR,
 288 and either copies \fIstring\fR to the variable whose name is
 289 given by \fIvarName\fR or returns \fIstring\fR if \fIvarName\fR is not
 290 present.
 291 (Regular expression matching is described in the \fBre_syntax\fR
 292 reference page.)
 293 If there is a match, then while copying \fIstring\fR to \fIvarName\fR
 294 (or to the result of this command if \fIvarName\fR is not present)
 295 the portion of \fIstring\fR that
 296 matched \fIexp\fR is replaced with \fIsubSpec\fR.
 297 If \fIsubSpec\fR contains a
 298 .QW &
 299 or
 300 .QW \e0 ,
 301 then it is replaced in the substitution with the portion of
 302 \fIstring\fR that matched \fIexp\fR.
 303 If \fIsubSpec\fR contains a
 304 .QW \e\fIn\fR ,
 305 where \fIn\fR is a digit
 306 between 1 and 9, then it is replaced in the substitution with
 307 the portion of \fIstring\fR that matched the \fIn\fR'th
 308 parenthesized subexpression of \fIexp\fR.
 309 Additional backslashes may be used in \fIsubSpec\fR to prevent special
 310 interpretation of
 311 .QW & ,
 312 .QW \e0 ,
 313 .QW \e\fIn\fR
 314 and backslashes.
 315 The use of backslashes in \fIsubSpec\fR tends to interact badly
 316 with the Tcl parser's use of backslashes, so it is generally
 317 safest to enclose \fIsubSpec\fR in braces if it includes
 318 backslashes.
 319 .LP
 320 If the initial arguments to \fBregsub\fR start with \fB\-\fR then
 321 they are treated as switches.  The following switches are
 322 currently supported:
 323 .TP
 324 \fB\-all\fR
 325 .
 326 All ranges in \fIstring\fR that match \fIexp\fR are found and
 327 substitution is performed for each of these ranges.
 328 Without this switch only the first
 329 matching range is found and substituted.
 330 If \fB\-all\fR is specified, then
 331 .QW &
 332 and
 333 .QW \e\fIn\fR
 334 sequences are handled for each substitution using the information
 335 from the corresponding match.
 336 .TP
 337 \fB\-expanded\fR
 338 .
 339 Enables use of the expanded regular expression syntax where
 340 whitespace and comments are ignored.  This is the same as specifying
 341 the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page).
 342 .TP
 343 \fB\-line\fR
 344 .
 345 Enables newline-sensitive matching.  By default, newline is a
 346 completely ordinary character with no special meaning.  With this flag,
 347 .QW [^
 348 bracket expressions and
 349 .QW .
 350 never match newline,
 351 .QW ^
 352 matches an empty string after any newline in addition to its normal
 353 function, and
 354 .QW $
 355 matches an empty string before any newline in
 356 addition to its normal function.  This flag is equivalent to
 357 specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the
 358 \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page).
 359 .TP
 360 \fB\-linestop\fR
 361 .
 362 Changes the behavior of
 363 .QW [^
 364 bracket expressions and
 365 .QW .
 366 so that they
 367 stop at newlines.  This is the same as specifying the \fB(?p)\fR
 368 embedded option (see the \fBre_syntax\fR manual page).
 369 .TP
 370 \fB\-lineanchor\fR
 371 .
 372 Changes the behavior of
 373 .QW ^
 374 and
 375 .QW $
 376 (the
 377 .QW anchors )
 378 so they match the
 379 beginning and end of a line respectively.  This is the same as
 380 specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR
 381 manual page).
 382 .TP
 383 \fB\-nocase\fR
 384 .
 385 Upper-case characters in \fIstring\fR will be converted to lower-case
 386 before matching against \fIexp\fR;  however, substitutions specified
 387 by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
 388 .TP
 389 \fB\-start\fR \fIindex\fR
 390 .
 391 Specifies a character index offset into the string to start
 392 matching the regular expression at.
 393 The \fIindex\fR value is interpreted in the same manner
 394 as the \fIindex\fR argument to \fBstring index\fR.
 395 When using this switch,
 396 .QW ^
 397 will not match the beginning of the line, and \eA will still
 398 match the start of the string at \fIindex\fR.
 399 \fIindex\fR will be constrained to the bounds of the input string.
 400 .TP
 401 \fB\-\|\-\fR
 402 .
 403 Marks the end of switches.  The argument following this one will
 404 be treated as \fIexp\fR even if it starts with a \fB\-\fR.
 405 .PP
 406 If \fIvarName\fR is supplied, the command returns a count of the
 407 number of matching ranges that were found and replaced, otherwise the
 408 string after replacement is returned.
 409 See the manual entry for \fBregexp\fR for details on the interpretation
 410 of regular expressions.
 411 .SH EXAMPLES
 412 .PP
 413 Replace (in the string in variable \fIstring\fR) every instance of
 414 \fBfoo\fR which is a word by itself with \fBbar\fR:
 415 .PP
 416 .CS
 417 \fBregsub\fR -all {\emfoo\eM} $string bar string
 418 .CE
 419 .PP
 420 or (using the
 421 .QW "basic regular expression"
 422 syntax):
 423 .PP
 424 .CS
 425 \fBregsub\fR -all {(?b)\e<foo\e>} $string bar string
 426 .CE
 427 .PP
 428 Insert double-quotes around the first instance of the word
 429 \fBinteresting\fR, however it is capitalized.
 430 .PP
 431 .CS
 432 \fBregsub\fR -nocase {\eyinteresting\ey} $string {"&"} string
 433 .CE
 434 .PP
 435 Convert all non-ASCII and Tcl-significant characters into \eu escape
 436 sequences by using \fBregsub\fR and \fBsubst\fR in combination:
 437 .PP
 438 .CS
 439 # This RE is just a character class for almost everything "bad"
 440 set RE {[][{};#\e\e\e$ \er\et\eu0080-\euffff]}
 441
 442 # We will substitute with a fragment of Tcl script in brackets
 443 set substitution {[format \e\e\e\eu%04x [scan "\e\e&" %c]]}
 444
 445 # Now we apply the substitution to get a subst-string that
 446 # will perform the computational parts of the conversion. Note
 447 # that newline is handled specially through \fBstring map\fR since
 448 # backslash-newline is a special sequence.
 449 set quoted [subst [string map {\en {\e\eu000a}} \e
 450         [\fBregsub\fR -all $RE $string $substitution]]]
 451 .CE
 452 .SH "SEE ALSO"
 453 regexp(n), re_syntax(n), subst(n), string(n)
 454 .SH KEYWORDS
 455 match, pattern, quoting, regular expression, substitution
 456 '\" Local Variables:
 457 '\" mode: nroff
 458 '\" End: