CELLLINUX64/util/CELLLINUX64/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 '\" RCS: @(#) $Id: regsub.n,v 1.9 2003/02/20 15:33:02 dkf Exp $
  10 '\"
  11 '\" The definitions below are for supplemental macros used in Tcl/Tk
  12 '\" manual entries.
  13 '\"
  14 '\" .AP type name in/out ?indent?
  15 '\"     Start paragraph describing an argument to a library procedure.
  16 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  17 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  18 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  19 '\"     needed;  use .AS below instead)
  20 '\"
  21 '\" .AS ?type? ?name?
  22 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  23 '\"     name are examples of largest possible arguments that will be passed
  24 '\"     to .AP later.  If args are omitted, default tab stops are used.
  25 '\"
  26 '\" .BS
  27 '\"     Start box enclosure.  From here until next .BE, everything will be
  28 '\"     enclosed in one large box.
  29 '\"
  30 '\" .BE
  31 '\"     End of box enclosure.
  32 '\"
  33 '\" .CS
  34 '\"     Begin code excerpt.
  35 '\"
  36 '\" .CE
  37 '\"     End code excerpt.
  38 '\"
  39 '\" .VS ?version? ?br?
  40 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  41 '\"     of man pages.  The first argument is ignored and used for recording
  42 '\"     the version when the .VS was added, so that the sidebars can be
  43 '\"     found and removed when they reach a certain age.  If another argument
  44 '\"     is present, then a line break is forced before starting the sidebar.
  45 '\"
  46 '\" .VE
  47 '\"     End of vertical sidebar.
  48 '\"
  49 '\" .DS
  50 '\"     Begin an indented unfilled display.
  51 '\"
  52 '\" .DE
  53 '\"     End of indented unfilled display.
  54 '\"
  55 '\" .SO
  56 '\"     Start of list of standard options for a Tk widget.  The
  57 '\"     options follow on successive lines, in four columns separated
  58 '\"     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 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
  73 '\"
  74 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  75 .if t .wh -1.3i ^B
  76 .nr ^l \n(.l
  77 .ad b
  78 '\"     # Start an argument description
  79 .de AP
  80 .ie !"\\$4"" .TP \\$4
  81 .el \{\
  82 .   ie !"\\$2"" .TP \\n()Cu
  83 .   el          .TP 15
  84 .\}
  85 .ta \\n()Au \\n()Bu
  86 .ie !"\\$3"" \{\
  87 \&\\$1  \\fI\\$2\\fP    (\\$3)
  88 .\".b
  89 .\}
  90 .el \{\
  91 .br
  92 .ie !"\\$2"" \{\
  93 \&\\$1  \\fI\\$2\\fP
  94 .\}
  95 .el \{\
  96 \&\\fI\\$1\\fP
  97 .\}
  98 .\}
  99 ..
 100 '\"     # define tabbing values for .AP
 101 .de AS
 102 .nr )A 10n
 103 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 104 .nr )B \\n()Au+15n
 105 .\"
 106 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 107 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 108 ..
 109 .AS Tcl_Interp Tcl_CreateInterp in/out
 110 '\"     # BS - start boxed text
 111 '\"     # ^y = starting y location
 112 '\"     # ^b = 1
 113 .de BS
 114 .br
 115 .mk ^y
 116 .nr ^b 1u
 117 .if n .nf
 118 .if n .ti 0
 119 .if n \l'\\n(.lu\(ul'
 120 .if n .fi
 121 ..
 122 '\"     # BE - end boxed text (draw box now)
 123 .de BE
 124 .nf
 125 .ti 0
 126 .mk ^t
 127 .ie n \l'\\n(^lu\(ul'
 128 .el \{\
 129 .\"     Draw four-sided box normally, but don't draw top of
 130 .\"     box if the box started on an earlier page.
 131 .ie !\\n(^b-1 \{\
 132 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 133 .\}
 134 .el \}\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .\}
 138 .fi
 139 .br
 140 .nr ^b 0
 141 ..
 142 '\"     # VS - start vertical sidebar
 143 '\"     # ^Y = starting y location
 144 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 145 .de VS
 146 .if !"\\$2"" .br
 147 .mk ^Y
 148 .ie n 'mc \s12\(br\s0
 149 .el .nr ^v 1u
 150 ..
 151 '\"     # VE - end of vertical sidebar
 152 .de VE
 153 .ie n 'mc
 154 .el \{\
 155 .ev 2
 156 .nf
 157 .ti 0
 158 .mk ^t
 159 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 160 .sp -1
 161 .fi
 162 .ev
 163 .\}
 164 .nr ^v 0
 165 ..
 166 '\"     # Special macro to handle page bottom:  finish off current
 167 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 168 '\"     # page bottom macro.
 169 .de ^B
 170 .ev 2
 171 'ti 0
 172 'nf
 173 .mk ^t
 174 .if \\n(^b \{\
 175 .\"     Draw three-sided box if this is the box's first page,
 176 .\"     draw two sides but no top otherwise.
 177 .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
 178 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 179 .\}
 180 .if \\n(^v \{\
 181 .nr ^x \\n(^tu+1v-\\n(^Yu
 182 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 183 .\}
 184 .bp
 185 'fi
 186 .ev
 187 .if \\n(^b \{\
 188 .mk ^y
 189 .nr ^b 2
 190 .\}
 191 .if \\n(^v \{\
 192 .mk ^Y
 193 .\}
 194 ..
 195 '\"     # DS - begin display
 196 .de DS
 197 .RS
 198 .nf
 199 .sp
 200 ..
 201 '\"     # DE - end display
 202 .de DE
 203 .fi
 204 .RE
 205 .sp
 206 ..
 207 '\"     # SO - start of list of standard options
 208 .de SO
 209 .SH "STANDARD OPTIONS"
 210 .LP
 211 .nf
 212 .ta 5.5c 11c
 213 .ft B
 214 ..
 215 '\"     # SE - end of list of standard options
 216 .de SE
 217 .fi
 218 .ft R
 219 .LP
 220 See the \\fBoptions\\fR manual entry for details on the standard options.
 221 ..
 222 '\"     # OP - start of full description for a single option
 223 .de OP
 224 .LP
 225 .nf
 226 .ta 4c
 227 Command-Line Name:      \\fB\\$1\\fR
 228 Database Name:  \\fB\\$2\\fR
 229 Database Class: \\fB\\$3\\fR
 230 .fi
 231 .IP
 232 ..
 233 '\"     # CS - begin code excerpt
 234 .de CS
 235 .RS
 236 .nf
 237 .ta .25i .5i .75i 1i
 238 ..
 239 '\"     # CE - end code excerpt
 240 .de CE
 241 .fi
 242 .RE
 243 ..
 244 .de UL
 245 \\$1\l'|0\(ul'\\$2
 246 ..
 247 .TH regsub n 8.3 Tcl "Tcl Built-In Commands"
 248 .BS
 249 '\" Note:  do not modify the .SH NAME line immediately below!
 250 .SH NAME
 251 regsub \- Perform substitutions based on regular expression pattern matching
 252 .SH SYNOPSIS
 253 .VS 8.4
 254 \fBregsub \fR?\fIswitches\fR? \fIexp string subSpec \fR?\fIvarName\fR?
 255 .VE 8.4
 256 .BE
 257
 258 .SH DESCRIPTION
 259 .PP
 260 This command matches the regular expression \fIexp\fR against
 261 \fIstring\fR,
 262 .VS 8.4
 263 and either copies \fIstring\fR to the variable whose name is
 264 given by \fIvarName\fR or returns \fIstring\fR if \fIvarName\fR is not
 265 present.
 266 .VE 8.4
 267 (Regular expression matching is described in the \fBre_syntax\fR
 268 reference page.)
 269 If there is a match, then while copying \fIstring\fR to \fIvarName\fR
 270 .VS 8.4
 271 (or to the result of this command if \fIvarName\fR is not present)
 272 .VE 8.4
 273 the portion of \fIstring\fR that
 274 matched \fIexp\fR is replaced with \fIsubSpec\fR.
 275 If \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced
 276 in the substitution with the portion of \fIstring\fR that
 277 matched \fIexp\fR.
 278 If \fIsubSpec\fR contains a ``\e\fIn\fR'', where \fIn\fR is a digit
 279 between 1 and 9, then it is replaced in the substitution with
 280 the portion of \fIstring\fR that matched the \fIn\fR-th
 281 parenthesized subexpression of \fIexp\fR.
 282 Additional backslashes may be used in \fIsubSpec\fR to prevent special
 283 interpretation of ``&'' or ``\e0'' or ``\e\fIn\fR'' or
 284 backslash.
 285 The use of backslashes in \fIsubSpec\fR tends to interact badly
 286 with the Tcl parser's use of backslashes, so it's generally
 287 safest to enclose \fIsubSpec\fR in braces if it includes
 288 backslashes.
 289 .LP
 290 If the initial arguments to \fBregsub\fR start with \fB\-\fR then
 291 they are treated as switches.  The following switches are
 292 currently supported:
 293 .TP 10
 294 \fB\-all\fR
 295 All ranges in \fIstring\fR that match \fIexp\fR are found and
 296 substitution is performed for each of these ranges.
 297 Without this switch only the first
 298 matching range is found and substituted.
 299 If \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR''
 300 sequences are handled for each substitution using the information
 301 from the corresponding match.
 302 .TP 15
 303 \fB\-expanded\fR
 304 Enables use of the expanded regular expression syntax where
 305 whitespace and comments are ignored.  This is the same as specifying
 306 the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page).
 307 .TP 15
 308 \fB\-line\fR
 309 Enables newline-sensitive matching.  By default, newline is a
 310 completely ordinary character with no special meaning.  With this
 311 flag, `[^' bracket expressions and `.' never match newline, `^'
 312 matches an empty string after any newline in addition to its normal
 313 function, and `$' matches an empty string before any newline in
 314 addition to its normal function.  This flag is equivalent to
 315 specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the
 316 \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page).
 317 .TP 15
 318 \fB\-linestop\fR
 319 Changes the behavior of `[^' bracket expressions and `.' so that they
 320 stop at newlines.  This is the same as specifying the \fB(?p)\fR
 321 embedded option (see the \fBre_syntax\fR manual page).
 322 .TP 15
 323 \fB\-lineanchor\fR
 324 Changes the behavior of `^' and `$' (the ``anchors'') so they match the
 325 beginning and end of a line respectively.  This is the same as
 326 specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR
 327 manual page).
 328 .TP 10
 329 \fB\-nocase\fR
 330 Upper-case characters in \fIstring\fR will be converted to lower-case
 331 before matching against \fIexp\fR;  however, substitutions specified
 332 by \fIsubSpec\fR use the original unconverted form of \fIstring\fR.
 333 .TP 10
 334 \fB\-start\fR \fIindex\fR
 335 Specifies a character index offset into the string to start
 336 matching the regular expression at.  When using this switch, `^'
 337 will not match the beginning of the line, and \\A will still
 338 match the start of the string at \fIindex\fR.
 339 \fIindex\fR will be constrained to the bounds of the input string.
 340 .TP 10
 341 \fB\-\|\-\fR
 342 Marks the end of switches.  The argument following this one will
 343 be treated as \fIexp\fR even if it starts with a \fB\-\fR.
 344 .PP
 345 .VS 8.4
 346 If \fIvarName\fR is supplied, the command returns a count of the
 347 number of matching ranges that were found and replaced, otherwise the
 348 string after replacement is returned.
 349 .VE 8.4
 350 See the manual entry for \fBregexp\fR for details on the interpretation
 351 of regular expressions.
 352
 353 .SH "SEE ALSO"
 354 regexp(n), re_syntax(n)
 355
 356 .SH KEYWORDS
 357 match, pattern, regular expression, substitute