CELLLINUX64/util/CELLLINUX64/man/mann/regexp.n

   1 '\"
   2 '\" Copyright (c) 1998 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" RCS: @(#) $Id: regexp.n,v 1.12 2002/10/10 14:46:57 dgp Exp $
   8 '\"
   9 '\" The definitions below are for supplemental macros used in Tcl/Tk
  10 '\" manual entries.
  11 '\"
  12 '\" .AP type name in/out ?indent?
  13 '\"     Start paragraph describing an argument to a library procedure.
  14 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 '\"     needed;  use .AS below instead)
  18 '\"
  19 '\" .AS ?type? ?name?
  20 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 '\"     name are examples of largest possible arguments that will be passed
  22 '\"     to .AP later.  If args are omitted, default tab stops are used.
  23 '\"
  24 '\" .BS
  25 '\"     Start box enclosure.  From here until next .BE, everything will be
  26 '\"     enclosed in one large box.
  27 '\"
  28 '\" .BE
  29 '\"     End of box enclosure.
  30 '\"
  31 '\" .CS
  32 '\"     Begin code excerpt.
  33 '\"
  34 '\" .CE
  35 '\"     End code excerpt.
  36 '\"
  37 '\" .VS ?version? ?br?
  38 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 '\"     of man pages.  The first argument is ignored and used for recording
  40 '\"     the version when the .VS was added, so that the sidebars can be
  41 '\"     found and removed when they reach a certain age.  If another argument
  42 '\"     is present, then a line break is forced before starting the sidebar.
  43 '\"
  44 '\" .VE
  45 '\"     End of vertical sidebar.
  46 '\"
  47 '\" .DS
  48 '\"     Begin an indented unfilled display.
  49 '\"
  50 '\" .DE
  51 '\"     End of indented unfilled display.
  52 '\"
  53 '\" .SO
  54 '\"     Start of list of standard options for a Tk widget.  The
  55 '\"     options follow on successive lines, in four columns separated
  56 '\"     by tabs.
  57 '\"
  58 '\" .SE
  59 '\"     End of list of standard options for a Tk widget.
  60 '\"
  61 '\" .OP cmdName dbName dbClass
  62 '\"     Start of description of a specific option.  cmdName gives the
  63 '\"     option's name as specified in the class command, dbName gives
  64 '\"     the option's name in the option database, and dbClass gives
  65 '\"     the option's class in the option database.
  66 '\"
  67 '\" .UL arg1 arg2
  68 '\"     Print arg1 underlined, then print arg2 normally.
  69 '\"
  70 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
  71 '\"
  72 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  73 .if t .wh -1.3i ^B
  74 .nr ^l \n(.l
  75 .ad b
  76 '\"     # Start an argument description
  77 .de AP
  78 .ie !"\\$4"" .TP \\$4
  79 .el \{\
  80 .   ie !"\\$2"" .TP \\n()Cu
  81 .   el          .TP 15
  82 .\}
  83 .ta \\n()Au \\n()Bu
  84 .ie !"\\$3"" \{\
  85 \&\\$1  \\fI\\$2\\fP    (\\$3)
  86 .\".b
  87 .\}
  88 .el \{\
  89 .br
  90 .ie !"\\$2"" \{\
  91 \&\\$1  \\fI\\$2\\fP
  92 .\}
  93 .el \{\
  94 \&\\fI\\$1\\fP
  95 .\}
  96 .\}
  97 ..
  98 '\"     # define tabbing values for .AP
  99 .de AS
 100 .nr )A 10n
 101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 102 .nr )B \\n()Au+15n
 103 .\"
 104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 106 ..
 107 .AS Tcl_Interp Tcl_CreateInterp in/out
 108 '\"     # BS - start boxed text
 109 '\"     # ^y = starting y location
 110 '\"     # ^b = 1
 111 .de BS
 112 .br
 113 .mk ^y
 114 .nr ^b 1u
 115 .if n .nf
 116 .if n .ti 0
 117 .if n \l'\\n(.lu\(ul'
 118 .if n .fi
 119 ..
 120 '\"     # BE - end boxed text (draw box now)
 121 .de BE
 122 .nf
 123 .ti 0
 124 .mk ^t
 125 .ie n \l'\\n(^lu\(ul'
 126 .el \{\
 127 .\"     Draw four-sided box normally, but don't draw top of
 128 .\"     box if the box started on an earlier page.
 129 .ie !\\n(^b-1 \{\
 130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 131 .\}
 132 .el \}\
 133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 134 .\}
 135 .\}
 136 .fi
 137 .br
 138 .nr ^b 0
 139 ..
 140 '\"     # VS - start vertical sidebar
 141 '\"     # ^Y = starting y location
 142 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 143 .de VS
 144 .if !"\\$2"" .br
 145 .mk ^Y
 146 .ie n 'mc \s12\(br\s0
 147 .el .nr ^v 1u
 148 ..
 149 '\"     # VE - end of vertical sidebar
 150 .de VE
 151 .ie n 'mc
 152 .el \{\
 153 .ev 2
 154 .nf
 155 .ti 0
 156 .mk ^t
 157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 158 .sp -1
 159 .fi
 160 .ev
 161 .\}
 162 .nr ^v 0
 163 ..
 164 '\"     # Special macro to handle page bottom:  finish off current
 165 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 166 '\"     # page bottom macro.
 167 .de ^B
 168 .ev 2
 169 'ti 0
 170 'nf
 171 .mk ^t
 172 .if \\n(^b \{\
 173 .\"     Draw three-sided box if this is the box's first page,
 174 .\"     draw two sides but no top otherwise.
 175 .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
 176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 177 .\}
 178 .if \\n(^v \{\
 179 .nr ^x \\n(^tu+1v-\\n(^Yu
 180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 181 .\}
 182 .bp
 183 'fi
 184 .ev
 185 .if \\n(^b \{\
 186 .mk ^y
 187 .nr ^b 2
 188 .\}
 189 .if \\n(^v \{\
 190 .mk ^Y
 191 .\}
 192 ..
 193 '\"     # DS - begin display
 194 .de DS
 195 .RS
 196 .nf
 197 .sp
 198 ..
 199 '\"     # DE - end display
 200 .de DE
 201 .fi
 202 .RE
 203 .sp
 204 ..
 205 '\"     # SO - start of list of standard options
 206 .de SO
 207 .SH "STANDARD OPTIONS"
 208 .LP
 209 .nf
 210 .ta 5.5c 11c
 211 .ft B
 212 ..
 213 '\"     # SE - end of list of standard options
 214 .de SE
 215 .fi
 216 .ft R
 217 .LP
 218 See the \\fBoptions\\fR manual entry for details on the standard options.
 219 ..
 220 '\"     # OP - start of full description for a single option
 221 .de OP
 222 .LP
 223 .nf
 224 .ta 4c
 225 Command-Line Name:      \\fB\\$1\\fR
 226 Database Name:  \\fB\\$2\\fR
 227 Database Class: \\fB\\$3\\fR
 228 .fi
 229 .IP
 230 ..
 231 '\"     # CS - begin code excerpt
 232 .de CS
 233 .RS
 234 .nf
 235 .ta .25i .5i .75i 1i
 236 ..
 237 '\"     # CE - end code excerpt
 238 .de CE
 239 .fi
 240 .RE
 241 ..
 242 .de UL
 243 \\$1\l'|0\(ul'\\$2
 244 ..
 245 .TH regexp n 8.3 Tcl "Tcl Built-In Commands"
 246 .BS
 247 '\" Note:  do not modify the .SH NAME line immediately below!
 248 .SH NAME
 249 regexp \- Match a regular expression against a string
 250
 251 .SH SYNOPSIS
 252 \fBregexp \fR?\fIswitches\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR?
 253 .BE
 254
 255 .SH DESCRIPTION
 256 .PP
 257 Determines whether the regular expression \fIexp\fR matches part or
 258 all of \fIstring\fR and returns 1 if it does, 0 if it doesn't, unless
 259 \fB-inline\fR is specified (see below).
 260 (Regular expression matching is described in the \fBre_syntax\fR
 261 reference page.)
 262 .LP
 263 If additional arguments are specified after \fIstring\fR then they
 264 are treated as the names of variables in which to return
 265 information about which part(s) of \fIstring\fR matched \fIexp\fR.
 266 \fIMatchVar\fR will be set to the range of \fIstring\fR that
 267 matched all of \fIexp\fR.  The first \fIsubMatchVar\fR will contain
 268 the characters in \fIstring\fR that matched the leftmost parenthesized
 269 subexpression within \fIexp\fR, the next \fIsubMatchVar\fR will
 270 contain the characters that matched the next parenthesized
 271 subexpression to the right in \fIexp\fR, and so on.
 272 .PP
 273 If the initial arguments to \fBregexp\fR start with \fB\-\fR then
 274 they are treated as switches.  The following switches are
 275 currently supported:
 276 .TP 15
 277 \fB\-about\fR
 278 Instead of attempting to match the regular expression, returns a list
 279 containing information about the regular expression.  The first
 280 element of the list is a subexpression count.  The second element is a
 281 list of property names that describe various attributes of the regular
 282 expression. This switch is primarily intended for debugging purposes.
 283 .TP 15
 284 \fB\-expanded\fR
 285 Enables use of the expanded regular expression syntax where
 286 whitespace and comments are ignored.  This is the same as specifying
 287 the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page).
 288 .TP 15
 289 \fB\-indices\fR
 290 Changes what is stored in the \fIsubMatchVar\fRs.
 291 Instead of storing the matching characters from \fIstring\fR,
 292 each variable
 293 will contain a list of two decimal strings giving the indices
 294 in \fIstring\fR of the first and last characters in the matching
 295 range of characters.
 296 .TP 15
 297 \fB\-line\fR
 298 Enables newline-sensitive matching.  By default, newline is a
 299 completely ordinary character with no special meaning.  With this
 300 flag, `[^' bracket expressions and `.' never match newline, `^'
 301 matches an empty string after any newline in addition to its normal
 302 function, and `$' matches an empty string before any newline in
 303 addition to its normal function.  This flag is equivalent to
 304 specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the
 305 \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page).
 306 .TP 15
 307 \fB\-linestop\fR
 308 Changes the behavior of `[^' bracket expressions and `.' so that they
 309 stop at newlines.  This is the same as specifying the \fB(?p)\fR
 310 embedded option (see the \fBre_syntax\fR manual page).
 311 .TP 15
 312 \fB\-lineanchor\fR
 313 Changes the behavior of `^' and `$' (the ``anchors'') so they match the
 314 beginning and end of a line respectively.  This is the same as
 315 specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR
 316 manual page).
 317 .TP 15
 318 \fB\-nocase\fR
 319 Causes upper-case characters in \fIstring\fR to be treated as
 320 lower case during the matching process.
 321 .VS 8.3
 322 .TP 15
 323 \fB\-all\fR
 324 Causes the regular expression to be matched as many times as possible
 325 in the string, returning the total number of matches found.  If this
 326 is specified with match variables, they will contain information for
 327 the last match only.
 328 .TP 15
 329 \fB\-inline\fR
 330 Causes the command to return, as a list, the data that would otherwise
 331 be placed in match variables.  When using \fB-inline\fR,
 332 match variables may not be specified.  If used with \fB-all\fR, the
 333 list will be concatenated at each iteration, such that a flat list is
 334 always returned.  For each match iteration, the command will append the
 335 overall match data, plus one element for each subexpression in the
 336 regular expression.  Examples are:
 337 .CS
 338     regexp -inline -- {\\w(\\w)} " inlined "
 339  => {in n}
 340     regexp -all -inline -- {\\w(\\w)} " inlined "
 341  => {in n li i ne e}
 342 .CE
 343 .TP 15
 344 \fB\-start\fR \fIindex\fR
 345 Specifies a character index offset into the string to start
 346 matching the regular expression at.  When using this switch, `^'
 347 will not match the beginning of the line, and \\A will still
 348 match the start of the string at \fIindex\fR.  If \fB\-indices\fR
 349 is specified, the indices will be indexed starting from the
 350 absolute beginning of the input string.
 351 \fIindex\fR will be constrained to the bounds of the input string.
 352 .VE 8.3
 353 .TP 15
 354 \fB\-\|\-\fR
 355 Marks the end of switches.  The argument following this one will
 356 be treated as \fIexp\fR even if it starts with a \fB\-\fR.
 357 .PP
 358 If there are more \fIsubMatchVar\fR's than parenthesized
 359 subexpressions within \fIexp\fR, or if a particular subexpression
 360 in \fIexp\fR doesn't match the string (e.g. because it was in a
 361 portion of the expression that wasn't matched), then the corresponding
 362 \fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR
 363 has been specified or to an empty string otherwise.
 364
 365 .SH "SEE ALSO"
 366 re_syntax(n), regsub(n)
 367
 368 .SH KEYWORDS
 369 match, regular expression, string