diff options
Diffstat (limited to 'doc/switch.n')
| -rw-r--r-- | doc/switch.n | 94 |
1 files changed, 78 insertions, 16 deletions
diff --git a/doc/switch.n b/doc/switch.n index 32da66c..defa849 100644 --- a/doc/switch.n +++ b/doc/switch.n @@ -6,7 +6,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .so man.macros -.TH switch n 7.0 Tcl "Tcl Built-In Commands" +.TH switch n 8.5 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -16,7 +16,6 @@ switch \- Evaluate one of several scripts, depending on a given value .sp \fBswitch \fR?\fIoptions\fR?\fI string \fR{\fIpattern body \fR?\fIpattern body \fR...?} .BE - .SH DESCRIPTION .PP The \fBswitch\fR command matches its \fIstring\fR argument against each of @@ -31,8 +30,13 @@ matches \fIstring\fR and no default is given, then the \fBswitch\fR command returns an empty string. .PP If the initial arguments to \fBswitch\fR start with \fB\-\fR then -they are treated as options. The following options are -currently supported: +they are treated as options +.VS 8.5 +unless there are exactly two arguments to \fBswitch\fR (in which case the +first must the \fIstring\fR and the second must be the +\fIpattern\fR/\fIbody\fR list). +.VE 8.5 +The following options are currently supported: .TP 10 \fB\-exact\fR Use exact matching when comparing \fIstring\fR to a pattern. This @@ -46,10 +50,48 @@ When matching \fIstring\fR to the patterns, use glob-style matching When matching \fIstring\fR to the patterns, use regular expression matching (as described in the \fBre_syntax\fR reference page). +'\" Options defined by TIP#75 +.VS 8.5 +.TP 10 +\fB\-nocase\fR +Causes comparisons to be handled in a case-insensitive manner. +.TP 10 +\fB\-matchvar\fR \fIvarName\fR +This option (only legal when \fB\-regexp\fR is also specified) +specifies the name of a variable into which the list of matches +found by the regular expression engine will be written. The first +element of the list written will be the overall substring of the input +string (i.e. the \fIstring\fR argument to \fBswitch\fR) matched, the +second element of the list will be the substring matched by the first +capturing parenthesis in the regular expression that matched, and so +on. When a \fBdefault\fR branch is taken, the variable will have the +empty list written to it. This option may be specified at the same +time as the \fB\-indexvar\fR option. +.TP 10 +\fB\-indexvar\fR \fIvarName\fR +This option (only legal when \fB\-regexp\fR is also specified) +specifies the name of a variable into which the list of indices +referring to matching substrings +found by the regular expression engine will be written. The first +element of the list written will be a two-element list specifying the +index of the start and index of the first character after the end of +the overall substring of the input +string (i.e. the \fIstring\fR argument to \fBswitch\fR) matched, in a +similar way to the \fB\-indices\fR option to the \fBregexp\fR can +obtain. Similarly, the second element of the list refers to the first +capturing parenthesis in the regular expression that matched, and so +on. When a \fBdefault\fR branch is taken, the variable will have the +empty list written to it. This option may be specified at the same +time as the \fB\-matchvar\fR option. +.VE 8.5 .TP 10 \fB\-\|\-\fR Marks the end of options. The argument following this one will be treated as \fIstring\fR even if it starts with a \fB\-\fR. +.VS 8.5 +This is not required when the matching patterns and bodies are grouped +together in a single argument. +.VE 8.5 .PP Two syntaxes are provided for the \fIpattern\fR and \fIbody\fR arguments. The first uses a separate argument for each of the patterns and commands; @@ -66,9 +108,12 @@ no command or variable substitutions are performed on them; this makes the behavior of the second form different than the first form in some cases. .PP -If a \fIbody\fR is specified as ``\fB\-\fR'' it means that the \fIbody\fR +If a \fIbody\fR is specified as +.QW \fB\-\fR +it means that the \fIbody\fR for the next pattern should also be used as the body for this -pattern (if the next pattern also has a body of ``\fB\-\fR'' +pattern (if the next pattern also has a body of +.QW \fB\-\fR then the body after that is used, and so on). This feature makes it possible to share a single \fIbody\fR among several patterns. @@ -81,7 +126,7 @@ The \fBswitch\fR command can match against variables and not just literals, as shown here (the result is \fI2\fR): .CS set foo "abc" -\fBswitch\fR abc a \- b {expr 1} $foo {expr 2} default {expr 3} +\fBswitch\fR abc a \- b {expr {1}} $foo {expr {2}} default {expr {3}} .CE .PP Using glob matching and the fall-through body is an alternative to @@ -90,9 +135,9 @@ writing regular expressions with alternations, as can be seen here .CS \fBswitch\fR \-glob aaab { a*b \- - b {expr 1} - a* {expr 2} - default {expr 3} + b {expr {1}} + a* {expr {2}} + default {expr {3}} } .CE .PP @@ -100,22 +145,39 @@ Whenever nothing matches, the \fBdefault\fR clause (which must be last) is taken. This example has a result of \fI3\fR: .CS \fBswitch\fR xyz { - a \- + a \- b { # Correct Comment Placement - expr 1 + expr {1} } c { - expr 2 + expr {2} } default { - expr 3 + expr {3} + } +} +.CE +.PP +.VS 8.5 +When matching against regular expressions, information about what +exactly matched is easily obtained using the \fB\-matchvar\fR option: +.CS +\fBswitch\fR \-regexp \-matchvar foo \-\- $bar { + a(b*)c { + puts "Found [string length [lindex $foo 1]] 'b's" + } + d(e*)f(g*)h { + puts "Found [string length [lindex $foo 1]] 'e's and\e + [string length [lindex $foo 2]] 'g's" } } .CE - +.VE 8.5 .SH "SEE ALSO" for(n), if(n), regexp(n) - .SH KEYWORDS switch, match, regular expression +.\" Local Variables: +.\" mode: nroff +.\" End: |