util/X86LINUX64/man/mann/subst.n

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\" Copyright (c) 2001 Donal K. Fellows
   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 subst n 7.4 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 subst \- Perform backslash, command, and variable substitutions
 281 .SH SYNOPSIS
 282 \fBsubst \fR?\fB\-nobackslashes\fR? ?\fB\-nocommands\fR? ?\fB\-novariables\fR? \fIstring\fR
 283 .BE
 284 .SH DESCRIPTION
 285 .PP
 286 This command performs variable substitutions, command substitutions,
 287 and backslash substitutions on its \fIstring\fR argument and
 288 returns the fully-substituted result.
 289 The substitutions are performed in exactly the same way as for
 290 Tcl commands.
 291 As a result, the \fIstring\fR argument is actually substituted twice,
 292 once by the Tcl parser in the usual fashion for Tcl commands, and
 293 again by the \fIsubst\fR command.
 294 .PP
 295 If any of the \fB\-nobackslashes\fR, \fB\-nocommands\fR, or
 296 \fB\-novariables\fR are specified, then the corresponding substitutions
 297 are not performed.
 298 For example, if \fB\-nocommands\fR is specified, command substitution
 299 is not performed:  open and close brackets are treated as ordinary characters
 300 with no special interpretation.
 301 .PP
 302 Note that the substitution of one kind can include substitution of
 303 other kinds.  For example, even when the \fB\-novariables\fR option
 304 is specified, command substitution is performed without restriction.
 305 This means that any variable substitution necessary to complete the
 306 command substitution will still take place.  Likewise, any command
 307 substitution necessary to complete a variable substitution will
 308 take place, even when \fB\-nocommands\fR is specified.  See the
 309 \fBEXAMPLES\fR below.
 310 .PP
 311 If an error occurs during substitution, then \fBsubst\fR will return
 312 that error.  If a break exception occurs during command or variable
 313 substitution, the result of the whole substitution will be the
 314 string (as substituted) up to the start of the substitution that
 315 raised the exception.  If a continue exception occurs during the
 316 evaluation of a command or variable substitution, an empty string
 317 will be substituted for that entire command or variable substitution
 318 (as long as it is well-formed Tcl.)  If a return exception occurs,
 319 or any other return code is returned during command or variable
 320 substitution, then the returned value is substituted for that
 321 substitution.  See the \fBEXAMPLES\fR below.  In this way, all exceptional
 322 return codes are
 323 .QW caught
 324 by \fBsubst\fR.  The \fBsubst\fR command
 325 itself will either return an error, or will complete successfully.
 326 .SH EXAMPLES
 327 .PP
 328 When it performs its substitutions, \fIsubst\fR does not give any
 329 special treatment to double quotes or curly braces (except within
 330 command substitutions) so the script
 331 .PP
 332 .CS
 333 set a 44
 334 \fBsubst\fR {xyz {$a}}
 335 .CE
 336 .PP
 337 returns
 338 .QW "\fBxyz {44}\fR" ,
 339 not
 340 .QW "\fBxyz {$a}\fR"
 341 and the script
 342 .PP
 343 .CS
 344 set a "p\e} q \e{r"
 345 \fBsubst\fR {xyz {$a}}
 346 .CE
 347 .PP
 348 returns
 349 .QW "\fBxyz {p} q {r}\fR" ,
 350 not
 351 .QW "\fBxyz {p\e} q \e{r}\fR".
 352 .PP
 353 When command substitution is performed, it includes any variable
 354 substitution necessary to evaluate the script.
 355 .PP
 356 .CS
 357 set a 44
 358 \fBsubst\fR -novariables {$a [format $a]}
 359 .CE
 360 .PP
 361 returns
 362 .QW "\fB$a 44\fR" ,
 363 not
 364 .QW "\fB$a $a\fR" .
 365 Similarly, when
 366 variable substitution is performed, it includes any command
 367 substitution necessary to retrieve the value of the variable.
 368 .PP
 369 .CS
 370 proc b {} {return c}
 371 array set a {c c [b] tricky}
 372 \fBsubst\fR -nocommands {[b] $a([b])}
 373 .CE
 374 .PP
 375 returns
 376 .QW "\fB[b] c\fR" ,
 377 not
 378 .QW "\fB[b] tricky\fR" .
 379 .PP
 380 The continue and break exceptions allow command substitutions to
 381 prevent substitution of the rest of the command substitution and the
 382 rest of \fIstring\fR respectively, giving script authors more options
 383 when processing text using \fIsubst\fR.  For example, the script
 384 .PP
 385 .CS
 386 \fBsubst\fR {abc,[break],def}
 387 .CE
 388 .PP
 389 returns
 390 .QW \fBabc,\fR ,
 391 not
 392 .QW \fBabc,,def\fR
 393 and the script
 394 .PP
 395 .CS
 396 \fBsubst\fR {abc,[continue;expr {1+2}],def}
 397 .CE
 398 .PP
 399 returns
 400 .QW \fBabc,,def\fR ,
 401 not
 402 .QW \fBabc,3,def\fR .
 403 .PP
 404 Other exceptional return codes substitute the returned value
 405 .PP
 406 .CS
 407 \fBsubst\fR {abc,[return foo;expr {1+2}],def}
 408 .CE
 409 .PP
 410 returns
 411 .QW \fBabc,foo,def\fR ,
 412 not
 413 .QW \fBabc,3,def\fR
 414 and
 415 .PP
 416 .CS
 417 \fBsubst\fR {abc,[return -code 10 foo;expr {1+2}],def}
 418 .CE
 419 .PP
 420 also returns
 421 .QW \fBabc,foo,def\fR ,
 422 not
 423 .QW \fBabc,3,def\fR .
 424 .SH "SEE ALSO"
 425 Tcl(n), eval(n), break(n), continue(n)
 426 .SH KEYWORDS
 427 backslash substitution, command substitution, quoting, substitution, variable substitution
 428 .\" Local Variables:
 429 .\" mode: nroff
 430 .\" End: