about_Switch

Applies To: Windows PowerShell 2.0

TOPIC
    about_Switch

SHORT DESCRIPTION
    Explains how to use a switch to handle multiple If statements.

LONG DESCRIPTION
    You use an If statement to make a decision in a script or program. 
    Essentially, it says; “If this condition exists, perform this action. 
    Otherwise do that action.” You can perform that operation as many 
    times as you want, but if you have a long list of conditions, an If 
    statement becomes unwieldy. You can combine a long list of conditions
    in a switch statement. As in all branching statements, braces ({}) 
    must enclose script blocks.

    A Switch statement is, in effect, a series of If statements. It matches 
    the expression with each of the conditions case by case. If a match 
    is found, the action associated with that condition is performed. A 
    basic switch statement takes the following form:

        PS> $a = 3
        PS> switch ($a) {
            1 {"It is one."}
            2 {"It is two."}
            3 {"It is three."}
            4 {"It is four."}
            }
        
        It is three.


    This simple example takes a value and compares it with each condition 
    in the list. The action echoes a string from the match. But, you 
    could have a problem if you check all of the conditions. 
    For example:

        PS> $day = "day5"
        PS> switch ($day){
            day1 {"Monday"; break}
            day2 {"Tuesday"; break}
            day3 {"Wednesday"; break}
            day4 {"Thursday"; break}
            day5 {"Friday"; break}
            day6 {"Saturday"; break}
            day7 {"Sunday"; break}
            day5 {"Too many days"; break}
            }
        
        Friday


    There are two day5 conditions in the list. But, the break at the end of 
    each condition tells the switch to stop looking further and to perform 
    the action it finds. If the break statements were not there, both 
    day5 actions would be performed. 

    If the value to switch against is an array, then each element in the 
    array will be evaluated in order, starting at element 0 (zero). At least 
    one element must be present that meets at least one condition; otherwise, 
    an error will result. If there is more than one default clause, an 
    error will result.

    The complete switch syntax is as follows:

        switch [-regex|-wildcard|-exact][-casesensitive] ( pipeline )
    
    or

        switch [-regex|-wildcard|-exact][-casesensitive] -file filename

    followed by

        { 
            "string"|number|variable|{ expression } { statementlist }
            default { statementlist } 
        }

    
    By default, if no parameters are used, Switch behaves as if a case- 
    insensitive exact match is in effect. If "pipeline" results in an 
    array, each element of the array will be evaluated in ascending offset 
    order (starting at 0 [zero]).   

    At least one conditional element must be present in the Switch 
    codeblock, and only one default clause can be present. If more than 
    one default clause is present, a ParseException will be thrown.

    Switch has the following parameters:

        Regex           Indicates that the match clause, if it is a string, is 
                        treated as a regex string. Use of this parameter 
                        disables Wildcard and Exact. If the match clause is not
                        a string, this parameter is ignored.

        Wildcard    Indicates that the match clause, if it is a string, is 
                        treated as a wildcard string. Use of this 
                        parameter disables Regex and Exact. If the match clause
                        is not a string, this parameter is ignored.

        Exact           Indicates that the match clause, if it is a string, must 
                        match exactly. Use of this parameter disables 
                        Wildcard and Regex. If the match clause is not a 
                        string, this parameter is ignored.

        CaseSensitive   Modifies the match clause, if it is a string, to be
                        case-sensitive. If the match clause is not a string,
                        this parameter is ignored.

        File            Takes input from a file (or representative) rather 
                        than a statement. If multiple File parameters are 
                        used, the last one is used. Each line of the 
                        file is read and passed through the switch block.

    Multiple uses of Regex, Wildcard, or Exact are allowed. However, only 
    the last parameter used governs the behavior.

    The Break keyword indicates that no more processing will occur and 
    that the Switch statement will exit.  

    The Continue keyword indicates that no processing will continue 
    against the current token and that the next token in the conditional will 
    be evaluated. If no tokens are available, the Switch statement will 
    exit.

    The "{ expression }" block may be a code block that will be evaluated 
    at the time of the comparison. The current object is bound to 
    the $_ automatic variable and is available during the evaluation of 
    the expression. A comparison is considered a match if the expression 
    evaluates to "True".  This expression is evaluated in a new scope.

    The "Default" keyword within the switch statement indicates that if 
    no matches are found, the code block that follows the keyword will 
    be evaluated. Program flow will not be allowed from block to 
    block because the closing brace ( } ) in the compound list is an explicit 
    break. 

    If multiple matches are found, each match results in the 
    expression being executed. To avoid this, the Break or Continue 
    keywords can be used to halt further comparisons.


SEE ALSO
    about_Break
    about_Continue
    about_If
    about_Script_Blocks