[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
| 3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
---|
| 4 | '\" |
---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 7 | '\" |
---|
| 8 | '\" RCS: @(#) $Id: switch.n,v 1.18 2008/03/21 19:22:31 dkf Exp $ |
---|
| 9 | '\" |
---|
| 10 | .so man.macros |
---|
| 11 | .TH switch n 8.5 Tcl "Tcl Built-In Commands" |
---|
| 12 | .BS |
---|
| 13 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
| 14 | .SH NAME |
---|
| 15 | switch \- Evaluate one of several scripts, depending on a given value |
---|
| 16 | .SH SYNOPSIS |
---|
| 17 | \fBswitch \fR?\fIoptions\fR?\fI string pattern body \fR?\fIpattern body \fR...? |
---|
| 18 | .sp |
---|
| 19 | \fBswitch \fR?\fIoptions\fR?\fI string \fR{\fIpattern body \fR?\fIpattern body \fR...?} |
---|
| 20 | .BE |
---|
| 21 | .SH DESCRIPTION |
---|
| 22 | .PP |
---|
| 23 | The \fBswitch\fR command matches its \fIstring\fR argument against each of |
---|
| 24 | the \fIpattern\fR arguments in order. |
---|
| 25 | As soon as it finds a \fIpattern\fR that matches \fIstring\fR it |
---|
| 26 | evaluates the following \fIbody\fR argument by passing it recursively |
---|
| 27 | to the Tcl interpreter and returns the result of that evaluation. |
---|
| 28 | If the last \fIpattern\fR argument is \fBdefault\fR then it matches |
---|
| 29 | anything. |
---|
| 30 | If no \fIpattern\fR argument |
---|
| 31 | matches \fIstring\fR and no default is given, then the \fBswitch\fR |
---|
| 32 | command returns an empty string. |
---|
| 33 | .PP |
---|
| 34 | If the initial arguments to \fBswitch\fR start with \fB\-\fR then |
---|
| 35 | they are treated as options |
---|
| 36 | .VS 8.5 |
---|
| 37 | unless there are exactly two arguments to \fBswitch\fR (in which case the |
---|
| 38 | first must the \fIstring\fR and the second must be the |
---|
| 39 | \fIpattern\fR/\fIbody\fR list). |
---|
| 40 | .VE 8.5 |
---|
| 41 | The following options are currently supported: |
---|
| 42 | .TP 10 |
---|
| 43 | \fB\-exact\fR |
---|
| 44 | Use exact matching when comparing \fIstring\fR to a pattern. This |
---|
| 45 | is the default. |
---|
| 46 | .TP 10 |
---|
| 47 | \fB\-glob\fR |
---|
| 48 | When matching \fIstring\fR to the patterns, use glob-style matching |
---|
| 49 | (i.e. the same as implemented by the \fBstring match\fR command). |
---|
| 50 | .TP 10 |
---|
| 51 | \fB\-regexp\fR |
---|
| 52 | When matching \fIstring\fR to the patterns, use regular |
---|
| 53 | expression matching |
---|
| 54 | (as described in the \fBre_syntax\fR reference page). |
---|
| 55 | '\" Options defined by TIP#75 |
---|
| 56 | .VS 8.5 |
---|
| 57 | .TP 10 |
---|
| 58 | \fB\-nocase\fR |
---|
| 59 | Causes comparisons to be handled in a case-insensitive manner. |
---|
| 60 | .TP 10 |
---|
| 61 | \fB\-matchvar\fR \fIvarName\fR |
---|
| 62 | This option (only legal when \fB\-regexp\fR is also specified) |
---|
| 63 | specifies the name of a variable into which the list of matches |
---|
| 64 | found by the regular expression engine will be written. The first |
---|
| 65 | element of the list written will be the overall substring of the input |
---|
| 66 | string (i.e. the \fIstring\fR argument to \fBswitch\fR) matched, the |
---|
| 67 | second element of the list will be the substring matched by the first |
---|
| 68 | capturing parenthesis in the regular expression that matched, and so |
---|
| 69 | on. When a \fBdefault\fR branch is taken, the variable will have the |
---|
| 70 | empty list written to it. This option may be specified at the same |
---|
| 71 | time as the \fB\-indexvar\fR option. |
---|
| 72 | .TP 10 |
---|
| 73 | \fB\-indexvar\fR \fIvarName\fR |
---|
| 74 | This option (only legal when \fB\-regexp\fR is also specified) |
---|
| 75 | specifies the name of a variable into which the list of indices |
---|
| 76 | referring to matching substrings |
---|
| 77 | found by the regular expression engine will be written. The first |
---|
| 78 | element of the list written will be a two-element list specifying the |
---|
| 79 | index of the start and index of the first character after the end of |
---|
| 80 | the overall substring of the input |
---|
| 81 | string (i.e. the \fIstring\fR argument to \fBswitch\fR) matched, in a |
---|
| 82 | similar way to the \fB\-indices\fR option to the \fBregexp\fR can |
---|
| 83 | obtain. Similarly, the second element of the list refers to the first |
---|
| 84 | capturing parenthesis in the regular expression that matched, and so |
---|
| 85 | on. When a \fBdefault\fR branch is taken, the variable will have the |
---|
| 86 | empty list written to it. This option may be specified at the same |
---|
| 87 | time as the \fB\-matchvar\fR option. |
---|
| 88 | .VE 8.5 |
---|
| 89 | .TP 10 |
---|
| 90 | \fB\-\|\-\fR |
---|
| 91 | Marks the end of options. The argument following this one will |
---|
| 92 | be treated as \fIstring\fR even if it starts with a \fB\-\fR. |
---|
| 93 | .VS 8.5 |
---|
| 94 | This is not required when the matching patterns and bodies are grouped |
---|
| 95 | together in a single argument. |
---|
| 96 | .VE 8.5 |
---|
| 97 | .PP |
---|
| 98 | Two syntaxes are provided for the \fIpattern\fR and \fIbody\fR arguments. |
---|
| 99 | The first uses a separate argument for each of the patterns and commands; |
---|
| 100 | this form is convenient if substitutions are desired on some of the |
---|
| 101 | patterns or commands. |
---|
| 102 | The second form places all of the patterns and commands together into |
---|
| 103 | a single argument; the argument must have proper list structure, with |
---|
| 104 | the elements of the list being the patterns and commands. |
---|
| 105 | The second form makes it easy to construct multi-line switch commands, |
---|
| 106 | since the braces around the whole list make it unnecessary to include a |
---|
| 107 | backslash at the end of each line. |
---|
| 108 | Since the \fIpattern\fR arguments are in braces in the second form, |
---|
| 109 | no command or variable substitutions are performed on them; this makes |
---|
| 110 | the behavior of the second form different than the first form in some |
---|
| 111 | cases. |
---|
| 112 | .PP |
---|
| 113 | If a \fIbody\fR is specified as |
---|
| 114 | .QW \fB\-\fR |
---|
| 115 | it means that the \fIbody\fR |
---|
| 116 | for the next pattern should also be used as the body for this |
---|
| 117 | pattern (if the next pattern also has a body of |
---|
| 118 | .QW \fB\-\fR |
---|
| 119 | then the body after that is used, and so on). |
---|
| 120 | This feature makes it possible to share a single \fIbody\fR among |
---|
| 121 | several patterns. |
---|
| 122 | .PP |
---|
| 123 | Beware of how you place comments in \fBswitch\fR commands. Comments |
---|
| 124 | should only be placed \fBinside\fR the execution body of one of the |
---|
| 125 | patterns, and not intermingled with the patterns. |
---|
| 126 | .SH "EXAMPLES" |
---|
| 127 | The \fBswitch\fR command can match against variables and not just |
---|
| 128 | literals, as shown here (the result is \fI2\fR): |
---|
| 129 | .CS |
---|
| 130 | set foo "abc" |
---|
| 131 | \fBswitch\fR abc a \- b {expr {1}} $foo {expr {2}} default {expr {3}} |
---|
| 132 | .CE |
---|
| 133 | .PP |
---|
| 134 | Using glob matching and the fall-through body is an alternative to |
---|
| 135 | writing regular expressions with alternations, as can be seen here |
---|
| 136 | (this returns \fI1\fR): |
---|
| 137 | .CS |
---|
| 138 | \fBswitch\fR \-glob aaab { |
---|
| 139 | a*b \- |
---|
| 140 | b {expr {1}} |
---|
| 141 | a* {expr {2}} |
---|
| 142 | default {expr {3}} |
---|
| 143 | } |
---|
| 144 | .CE |
---|
| 145 | .PP |
---|
| 146 | Whenever nothing matches, the \fBdefault\fR clause (which must be |
---|
| 147 | last) is taken. This example has a result of \fI3\fR: |
---|
| 148 | .CS |
---|
| 149 | \fBswitch\fR xyz { |
---|
| 150 | a \- |
---|
| 151 | b { |
---|
| 152 | # Correct Comment Placement |
---|
| 153 | expr {1} |
---|
| 154 | } |
---|
| 155 | c { |
---|
| 156 | expr {2} |
---|
| 157 | } |
---|
| 158 | default { |
---|
| 159 | expr {3} |
---|
| 160 | } |
---|
| 161 | } |
---|
| 162 | .CE |
---|
| 163 | .PP |
---|
| 164 | .VS 8.5 |
---|
| 165 | When matching against regular expressions, information about what |
---|
| 166 | exactly matched is easily obtained using the \fB\-matchvar\fR option: |
---|
| 167 | .CS |
---|
| 168 | \fBswitch\fR \-regexp \-matchvar foo \-\- $bar { |
---|
| 169 | a(b*)c { |
---|
| 170 | puts "Found [string length [lindex $foo 1]] 'b's" |
---|
| 171 | } |
---|
| 172 | d(e*)f(g*)h { |
---|
| 173 | puts "Found [string length [lindex $foo 1]] 'e's and\e |
---|
| 174 | [string length [lindex $foo 2]] 'g's" |
---|
| 175 | } |
---|
| 176 | } |
---|
| 177 | .CE |
---|
| 178 | .VE 8.5 |
---|
| 179 | .SH "SEE ALSO" |
---|
| 180 | for(n), if(n), regexp(n) |
---|
| 181 | .SH KEYWORDS |
---|
| 182 | switch, match, regular expression |
---|
| 183 | .\" Local Variables: |
---|
| 184 | .\" mode: nroff |
---|
| 185 | .\" End: |
---|