Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
switch(n)		     Tcl Built-In Commands		     switch(n)

______________________________________________________________________________

NAME
       switch -	Evaluate one of	several	scripts, depending on a	given value

SYNOPSIS
       switch ?options?	string pattern body ?pattern body ...?

       switch ?options?	string {pattern	body ?pattern body ...?}
______________________________________________________________________________

DESCRIPTION
       The switch command matches its string argument against each of the pat-
       tern arguments in order.	 As soon as it finds a	pattern	 that  matches
       string  it  evaluates  the following body argument by passing it	recur-
       sively to the Tcl interpreter and returns the result  of	 that  evalua-
       tion.   If  the	last  pattern argument is default then it matches any-
       thing.  If no pattern argument matches string and no default is	given,
       then the	switch command returns an empty	string.

       If  the	initial	arguments to switch start with - then they are treated
       as options unless there are exactly two arguments to switch  (in	 which
       case  the first must the	string and the second must be the pattern/body
       list).  The following options are currently supported:

       -exact	 Use exact matching when comparing string to a pattern.	  This
		 is the	default.

       -glob	 When matching string to the patterns, use glob-style matching
		 (i.e. the same	as implemented by the string match command).

       -regexp	 When matching string to the patterns, use regular  expression
		 matching (as described	in the re_syntax reference page).

       -nocase	 Causes	 comparisons  to be handled in a case-insensitive man-
		 ner.

       -matchvar varName
		 This option (only legal when -regexp is also specified) spec-
		 ifies	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 sub-
		 string	of the input  string  (i.e.  the  string  argument  to
		 switch)  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 default
		 branch	is taken, the variable will have the empty list	 writ-
		 ten  to it.  This option may be specified at the same time as
		 the -indexvar option.

       -indexvar varName
		 This option (only legal when -regexp is also specified) spec-
		 ifies	the  name of a variable	into which the list of indices
		 referring to matching substrings found	by the regular expres-
		 sion  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	string
		 argument to switch) matched, in a similar way to the -indices
		 option	to the regexp can obtain.  Similarly, the second  ele-
		 ment of the list refers to the	first capturing	parenthesis in
		 the regular expression	that matched, and so on.  When	a  de-
		 fault	branch is taken, the variable will have	the empty list
		 written to it.	 This option may be specified at the same time
		 as the	-matchvar option.

       --	 Marks	the  end  of options.  The argument following this one
		 will be treated as string even	if it starts with a  -.	  This
		 is  not  required  when  the matching patterns	and bodies are
		 grouped together in a single argument.

       Two syntaxes are	provided for the  pattern  and	body  arguments.   The
       first  uses  a separate argument	for each of the	patterns and commands;
       this form is convenient if substitutions	are desired  on	 some  of  the
       patterns	 or  commands.	The second form	places all of the patterns and
       commands	together into a	single argument; the argument must have	proper
       list  structure,	 with  the elements of the list	being the patterns and
       commands.  The second form makes	it easy	to construct multi-line	switch
       commands, since the braces around the whole list	make it	unnecessary to
       include a backslash at the end of each line.  Since the	pattern	 argu-
       ments  are in braces in the second form,	no command or variable substi-
       tutions are performed on	them;  this makes the behavior of  the	second
       form different than the first form in some cases.

       If  a body is specified as "-" it means that the	body for the next pat-
       tern should also	be used	as the body for	this pattern (if the next pat-
       tern  also  has	a body of "-" then the body after that is used,	and so
       on).  This feature makes	it possible to share a single body among  sev-
       eral patterns.

       Beware  of  how you place comments in switch commands.  Comments	should
       only be placed inside the execution body	of one of  the	patterns,  and
       not intermingled	with the patterns.

EXAMPLES
       The  switch  command can	match against variables	and not	just literals,
       as shown	here (the result is 2):

	      set foo "abc"
	      switch abc a - b {expr {1}} $foo {expr {2}} default {expr	{3}}

       Using glob matching and the fall-through	 body  is  an  alternative  to
       writing	regular	 expressions  with  alternations,  as can be seen here
       (this returns 1):

	      switch -glob aaab	{
		  a*b	  -
		  b	  {expr	{1}}
		  a*	  {expr	{2}}
		  default {expr	{3}}
	      }

       Whenever	nothing	matches, the default clause (which must	 be  last)  is
       taken.  This example has	a result of 3:

	      switch xyz {
		  a -
		  b {
		      #	Correct	Comment	Placement
		      expr {1}
		  }
		  c {
		      expr {2}
		  }
		  default {
		      expr {3}
		  }
	      }

       When  matching  against regular expressions, information	about what ex-
       actly matched is	easily obtained	using the -matchvar option:

	      switch -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\
			      [string length [lindex $foo 2]] 'g's"
		  }
	      }

SEE ALSO
       for(n), if(n), regexp(n)

KEYWORDS
       switch, match, regular expression

Tcl				      8.5			     switch(n)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=switch.tcl87&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help