diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Break.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Break.md index 9785a090b3f1..1091a7340ed2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Break.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Break.md @@ -132,7 +132,7 @@ specific condition: ```powershell $var = "word2" -switch -regex ($var) { +switch -Regex ($var) { "word2" { Write-Host "Exact" $_ break diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Keywords.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Keywords.md index abdaab87520b..7bb2ed962e2c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Keywords.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Keywords.md @@ -474,7 +474,7 @@ condition obtains, the action is performed. Syntax 1: ```Syntax -switch [-regex|-wildcard|-exact][-casesensitive] ( ) +switch [-Regex|-Wildcard|-Exact][-CaseSensitive] ( ) { |||{ } {} |||{ } {} @@ -487,7 +487,7 @@ switch [-regex|-wildcard|-exact][-casesensitive] ( ) Syntax 2: ```Syntax -switch [-regex|-wildcard|-exact][-casesensitive] -file +switch [-Regex|-Wildcard|-Exact][-CaseSensitive] -File { |||{ } {} |||{ } {} diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 3f838c2554aa..8622e0bfbcf6 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -30,7 +30,7 @@ more about their syntax and usage at the links below. - [Select-String][11] - [-match and -replace operators][07] - [-split operator][09] -- [switch statement with -regex option][10] +- [switch statement with -Regex option][10] PowerShell regular expressions are case-insensitive by default. Each method shown above has a different way to force case sensitivity. diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md index 4c76dd96dd27..9a8bf5b134fa 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 02/28/2024 +ms.date: 02/19/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -19,20 +19,19 @@ statement can check many types of conditions, including the value of variables and the properties of objects. To check multiple conditions, use a `switch` statement. The `switch` statement -is equivalent to a series of `if` statements, but it is simpler. The `switch` +is equivalent to a series of `if` statements, but it's simpler. The `switch` statement lists each condition and an optional action. If a condition obtains, the action is performed. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see -[about_Automatic_Variables](about_Automatic_Variables.md). +more information, see [about_Automatic_Variables][02]. ## Syntax A basic `switch` statement has the following format: ```Syntax -Switch () +switch () { {} {} @@ -46,23 +45,23 @@ if ( -eq ()) {} if ( -eq ()) {} ``` -The `` is single expression that is evaluated in expression +The `` is single expression that's evaluated in expression mode to return a value. The `` is an expression whose value is compared to the input value. Expressions include literal values (strings or numbers), variables, and scriptblocks that return a boolean value. -Any unquoted value that is not recognized as a number is treated as a string. +Any unquoted value that's not recognized as a number is treated as a string. To avoid confusion or unintended string conversion, you should always quote string values. Enclose any expressions in parentheses `()`, creating subexpressions, to ensure that the expression is evaluated correctly. -It is important to understand that the `` value is on the +It's important to understand that the `` value is on the left-hand side of the comparison expression. That means the result of the `` is on the right-hand side, which can be converted to the type of the left-hand side value for comparison. For more information, see -[about_Comparison_Operators](about_Comparison_Operators.md) +[about_Comparison_Operators][04] The value `default` is reserved for the action used when there are no other matches. @@ -74,9 +73,9 @@ the `` statements. The complete `switch` statement syntax is as follows: ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] () -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] () { + string | number | variable | { } + { } default { } # optional } ``` @@ -84,39 +83,40 @@ switch [-regex | -wildcard | -exact] [-casesensitive] () or ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] -file filename -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] -File filename { + string | number | variable | { } + { } default { } # optional } ``` -If no parameters are used, `switch` behaves the same as using the **Exact** +If you don't use parameters, `switch` behaves the same as using the **Exact** parameter. It performs a case-insensitive match for the value. If the value is a collection, each element is evaluated in the order in which it appears. The `switch` statement must include at least one condition statement. -The `default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `else` clause in an `if` statement. Only one +The `default` clause is triggered when the value doesn't match any of the +conditions. It's equivalent to an `else` clause in an `if` statement. Only one `default` clause is permitted in each `switch` statement. `switch` has the following parameters: - **Wildcard** - Indicates that the condition is a wildcard string. If the - match clause is not a string, the parameter is ignored. The comparison is + match clause isn't a string, the parameter is ignored. The comparison is case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match - exactly. If the match clause is not a string, this parameter is ignored. The +- **Exact** - Indicates that the match clause, if it's a string, must match + exactly. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. - **CaseSensitive** - Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a ``. If - multiple **File** parameters are included, only the last one is used. Each - line of the file is read and evaluated by the `switch` statement. The - comparison is case-insensitive. +- **File**- Takes input from a file rather than a ``. The file + is read a line at a time and evaluated by the `switch` statement. By default, + the comparison is case-insensitive. The **File** parameter only supports one + file. If multiple **File** parameters are included, only the last one is + used.For more information see [File parameter examples][01]. - **Regex** - Performs regular expression matching of the value to the - condition. If the match clause is not a string, this parameter is ignored. + condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$matches` automatic variable is available for use within the matching statement block. @@ -126,44 +126,41 @@ conditions. It is equivalent to an `else` clause in an `if` statement. Only one > ignored. Multiple instances of parameters are also permitted. However, only > the last parameter listed is used. -## Examples +## Simple match examples -In the following example, the `switch` statement compares the test value, 3, to +In the following example, the `switch` statement compares the test value `3` to each of the conditions. When the test value matches the condition, the action is performed. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } } ``` ```Output -It is three. +It's three. ``` -In this simple example, the value is compared to each condition in the list, -even though there is a match for the value 3. The following `switch` statement -has two conditions for a value of 3. It demonstrates that, by default, all -conditions are tested. +In this example, the value is compared to each condition in the list. The +following `switch` statement has two conditions for a value of 3, which +demonstrates that all conditions are tested. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. Three again. ``` @@ -171,18 +168,17 @@ To direct the `switch` to stop comparing after a match, use the `break` statement. The `break` statement terminates the `switch` statement. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."; Break} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three."; break } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. ``` If the test value is a collection, such as an array, each item in the @@ -190,19 +186,18 @@ collection is evaluated in the order in which it appears. The following examples evaluates 4 and then 2. ```powershell -switch (4, 2) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is four. -It is two. +It's four. +It's two. ``` Any `break` statements apply to the collection, not to each value, as shown @@ -210,20 +205,21 @@ in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell -switch (4, 2) -{ - 1 {"It is one."; Break} - 2 {"It is two." ; Break} - 3 {"It is three." ; Break} - 4 {"It is four." ; Break} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one."; break } + 2 { "It's two." ; break } + 3 { "It's three." ; break } + 4 { "It's four." ; break } + 3 { "Three again." } } ``` ```Output -It is four. +It's four. ``` +## More complex match examples + In this example, the `switch` statement is testing for the type of the value in the hashtable. You must use and expression that returns a boolean value to select the scriptblock to execute. @@ -256,16 +252,9 @@ $test = @{ $test.ToString() -switch -Exact ($test) -{ - 'System.Collections.Hashtable' - { - 'Hashtable string coercion' - } - 'test' - { - 'Hashtable value' - } +switch -Exact ($test) { + 'System.Collections.Hashtable' { 'Hashtable string coercion' } + 'test' { 'Hashtable value' } } ``` @@ -277,13 +266,12 @@ Hashtable string coercion In this example, there is no matching case so there is no output. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } } ``` @@ -291,16 +279,13 @@ By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - Default { - "No matches" - } +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } + default { "No matches" } } ``` @@ -308,19 +293,18 @@ switch ("fourteen") No matches ``` -For the word "fourteen" to match a case you must use the `-Wildcard` or +For the word `fourteen` to match a case you must use the `-Wildcard` or `-Regex` parameter. ```powershell - PS> switch -Wildcard ("fourteen") - { - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - } - ``` +switch -Wildcard ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } +} +``` ```Output That's too many. @@ -330,11 +314,22 @@ The following example uses the `-Regex` parameter. ```powershell $target = 'https://bing.com' -switch -Regex ($target) -{ - '^ftp\://.*$' { "$_ is an ftp address"; Break } - '^\w+@\w+\.com|edu|org$' { "$_ is an email address"; Break } - '^(http[s]?)\://.*$' { "$_ is a web address that uses $($matches[1])"; Break } +switch -Regex ($target) { + '^ftp\://.*$' + { + "$_ is an ftp address" + break + } + '^\w+@\w+\.com|edu|org$' + { + "$_ is an email address" + break + } + '^(http[s]?)\://.*$' + { + "$_ is a web address that uses $($matches[1])" + break + } } ``` @@ -346,14 +341,9 @@ The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell -switch ("Test") -{ - {$_ -is [String]} { - "Found a string" - } - "Test" { - "This $_ executes as well" - } +switch ("Test") { + { $_ -is [String] } { "Found a string" } + "Test" { "This $_ executes as well" } } ``` @@ -369,10 +359,11 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { - { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).Days - "There are $days days until 2022." - } + { $_.Year -eq 2021 } + { + $days = ((Get-Date 1/1/2022) - $_).Days + "There are $days days until 2022." + } { $_.Year -eq 2022 } { 'Welcome to 2022!' } } ``` @@ -385,21 +376,16 @@ The `break` keyword stops processing and exits the `switch` statement. The `continue` keyword stops processing the current value, but continues processing any subsequent values. -The following example processes an array of numbers and displays if they are +The following example processes an array of numbers and displays if they're odd or even. Negative numbers are skipped with the `continue` keyword. If a non-number is encountered, execution is terminated with the `break` keyword. ```powershell -switch (1,4,-1,3,"Hello",2,1) -{ - {$_ -lt 0} { continue } - {$_ -isnot [Int32]} { break } - {$_ % 2} { - "$_ is Odd" - } - {-not ($_ % 2)} { - "$_ is Even" - } +switch (1,4,-1,3,"Hello",2,1) { + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } + {$_ % 2} { "$_ is Odd" } + {-not ($_ % 2)} { "$_ is Even" } } ``` @@ -409,9 +395,66 @@ switch (1,4,-1,3,"Hello",2,1) 3 is Odd ``` +## File parameter examples + +Using the `switch` statement with the **File** parameter is an efficient way to +process large files line by line. PowerShell streams the lines of the file to +the `switch` statement. Each line is processed individually. + +You can terminate +the processing before reaching the end of the file by using the `break` keyword +in the action statement. The `switch` statement is more efficient than using +`Get-Content` to process large files line by line. + +You can combine `switch -File` with `-Wildcard` or `-Regex` for flexible and efficient line-by-line pattern matching. + +The following example reads the `README.md` in the PowerShell-Docs repository. +It outputs each line until it reaches the line that starts with `##`. + +```powershell +switch -Regex -File .\README.md { + '^##\s' { break } + default { $_; continue } +} +``` + +The `` argument is interpreted as a wildcard expression, but it must +match only one file. The following example is the same as the previous one +except it uses a wildcard in the `` argument. This example works +because the wildcard pattern matches only one file. + +```powershell +switch -Regex -File .\README.* { + '^##\s' { break } + default { $_; continue } +} +``` + +You must escape characters that can be interpreted as wildcards if you want +them to be treated as literals. + +```powershell +$file = (New-Item -Path 'Temp:\Foo[0]' -Value Foo -Force).FullName +switch -File $file { Foo { 'Foo' } } +# No files matching '...\Temp\Foo[0]' were found. + +$fileEscaped = [WildcardPattern]::Escape($file) +switch -File $fileEscaped { foo { 'Foo' } } +# Foo +``` + ## See also -- [about_Break](about_Break.md) -- [about_Continue](about_Continue.md) -- [about_If](about_If.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_break][03] +- [about_Continue][05] +- [about_If][06] +- [about_Script_Blocks][07] + + +[01]: #file-parameter-examples +[02]: about_Automatic_Variables.md +[03]: about_break.md +[04]: about_Comparison_Operators.md +[05]: about_Continue.md +[06]: about_If.md +[07]: about_Script_Blocks.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Break.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Break.md index 58f643d730e5..af39e4288e7c 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Break.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Break.md @@ -132,7 +132,7 @@ specific condition: ```powershell $var = "word2" -switch -regex ($var) { +switch -Regex ($var) { "word2" { Write-Host "Exact" $_ break diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Language_Keywords.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Language_Keywords.md index 79647f4f541d..b4474b40ab29 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Language_Keywords.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Language_Keywords.md @@ -487,7 +487,7 @@ condition obtains, the action is performed. Syntax 1: ```Syntax -switch [-regex|-wildcard|-exact][-casesensitive] ( ) +switch [-Regex|-Wildcard|-Exact][-CaseSensitive] ( ) { |||{ } {} |||{ } {} @@ -500,7 +500,7 @@ switch [-regex|-wildcard|-exact][-casesensitive] ( ) Syntax 2: ```Syntax -switch [-regex|-wildcard|-exact][-casesensitive] -file +switch [-Regex|-Wildcard|-Exact][-CaseSensitive] -File { |||{ } {} |||{ } {} diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md index 3b2ae06239d7..353b823c9068 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 02/28/2024 +ms.date: 02/19/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -19,20 +19,19 @@ statement can check many types of conditions, including the value of variables and the properties of objects. To check multiple conditions, use a `switch` statement. The `switch` statement -is equivalent to a series of `if` statements, but it is simpler. The `switch` +is equivalent to a series of `if` statements, but it's simpler. The `switch` statement lists each condition and an optional action. If a condition obtains, the action is performed. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see -[about_Automatic_Variables](about_Automatic_Variables.md). +more information, see [about_Automatic_Variables][02]. ## Syntax A basic `switch` statement has the following format: ```Syntax -Switch () +switch () { {} {} @@ -46,23 +45,23 @@ if ( -eq ()) {} if ( -eq ()) {} ``` -The `` is single expression that is evaluated in expression +The `` is single expression that's evaluated in expression mode to return a value. The `` is an expression whose value is compared to the input value. Expressions include literal values (strings or numbers), variables, and scriptblocks that return a boolean value. -Any unquoted value that is not recognized as a number is treated as a string. +Any unquoted value that's not recognized as a number is treated as a string. To avoid confusion or unintended string conversion, you should always quote string values. Enclose any expressions in parentheses `()`, creating subexpressions, to ensure that the expression is evaluated correctly. -It is important to understand that the `` value is on the +It's important to understand that the `` value is on the left-hand side of the comparison expression. That means the result of the `` is on the right-hand side, which can be converted to the type of the left-hand side value for comparison. For more information, see -[about_Comparison_Operators](about_Comparison_Operators.md) +[about_Comparison_Operators][04] The value `default` is reserved for the action used when there are no other matches. @@ -74,9 +73,9 @@ the `` statements. The complete `switch` statement syntax is as follows: ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] () -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] () { + string | number | variable | { } + { } default { } # optional } ``` @@ -84,39 +83,40 @@ switch [-regex | -wildcard | -exact] [-casesensitive] () or ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] -file filename -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] -File filename { + string | number | variable | { } + { } default { } # optional } ``` -If no parameters are used, `switch` behaves the same as using the **Exact** +If you don't use parameters, `switch` behaves the same as using the **Exact** parameter. It performs a case-insensitive match for the value. If the value is a collection, each element is evaluated in the order in which it appears. The `switch` statement must include at least one condition statement. -The `default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `else` clause in an `if` statement. Only one +The `default` clause is triggered when the value doesn't match any of the +conditions. It's equivalent to an `else` clause in an `if` statement. Only one `default` clause is permitted in each `switch` statement. `switch` has the following parameters: - **Wildcard** - Indicates that the condition is a wildcard string. If the - match clause is not a string, the parameter is ignored. The comparison is + match clause isn't a string, the parameter is ignored. The comparison is case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match - exactly. If the match clause is not a string, this parameter is ignored. The +- **Exact** - Indicates that the match clause, if it's a string, must match + exactly. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. - **CaseSensitive** - Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a ``. If - multiple **File** parameters are included, only the last one is used. Each - line of the file is read and evaluated by the `switch` statement. The - comparison is case-insensitive. +- **File**- Takes input from a file rather than a ``. The file + is read a line at a time and evaluated by the `switch` statement. By default, + the comparison is case-insensitive. The **File** parameter only supports one + file. If multiple **File** parameters are included, only the last one is + used.For more information see [File parameter examples][01]. - **Regex** - Performs regular expression matching of the value to the - condition. If the match clause is not a string, this parameter is ignored. + condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$matches` automatic variable is available for use within the matching statement block. @@ -126,44 +126,41 @@ conditions. It is equivalent to an `else` clause in an `if` statement. Only one > ignored. Multiple instances of parameters are also permitted. However, only > the last parameter listed is used. -## Examples +## Simple match examples -In the following example, the `switch` statement compares the test value, 3, to +In the following example, the `switch` statement compares the test value `3` to each of the conditions. When the test value matches the condition, the action is performed. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } } ``` ```Output -It is three. +It's three. ``` -In this simple example, the value is compared to each condition in the list, -even though there is a match for the value 3. The following `switch` statement -has two conditions for a value of 3. It demonstrates that, by default, all -conditions are tested. +In this example, the value is compared to each condition in the list. The +following `switch` statement has two conditions for a value of 3, which +demonstrates that all conditions are tested. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. Three again. ``` @@ -171,18 +168,17 @@ To direct the `switch` to stop comparing after a match, use the `break` statement. The `break` statement terminates the `switch` statement. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."; Break} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three."; break } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. ``` If the test value is a collection, such as an array, each item in the @@ -190,19 +186,18 @@ collection is evaluated in the order in which it appears. The following examples evaluates 4 and then 2. ```powershell -switch (4, 2) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is four. -It is two. +It's four. +It's two. ``` Any `break` statements apply to the collection, not to each value, as shown @@ -210,20 +205,21 @@ in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell -switch (4, 2) -{ - 1 {"It is one."; Break} - 2 {"It is two." ; Break} - 3 {"It is three." ; Break} - 4 {"It is four." ; Break} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one."; break } + 2 { "It's two." ; break } + 3 { "It's three." ; break } + 4 { "It's four." ; break } + 3 { "Three again." } } ``` ```Output -It is four. +It's four. ``` +## More complex match examples + In this example, the `switch` statement is testing for the type of the value in the hashtable. You must use and expression that returns a boolean value to select the scriptblock to execute. @@ -256,16 +252,9 @@ $test = @{ $test.ToString() -switch -Exact ($test) -{ - 'System.Collections.Hashtable' - { - 'Hashtable string coercion' - } - 'test' - { - 'Hashtable value' - } +switch -Exact ($test) { + 'System.Collections.Hashtable' { 'Hashtable string coercion' } + 'test' { 'Hashtable value' } } ``` @@ -277,13 +266,12 @@ Hashtable string coercion In this example, there is no matching case so there is no output. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } } ``` @@ -291,16 +279,13 @@ By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - Default { - "No matches" - } +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } + default { "No matches" } } ``` @@ -308,19 +293,18 @@ switch ("fourteen") No matches ``` -For the word "fourteen" to match a case you must use the `-Wildcard` or +For the word `fourteen` to match a case you must use the `-Wildcard` or `-Regex` parameter. ```powershell - PS> switch -Wildcard ("fourteen") - { - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - } - ``` +switch -Wildcard ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } +} +``` ```Output That's too many. @@ -330,11 +314,22 @@ The following example uses the `-Regex` parameter. ```powershell $target = 'https://bing.com' -switch -Regex ($target) -{ - '^ftp\://.*$' { "$_ is an ftp address"; Break } - '^\w+@\w+\.com|edu|org$' { "$_ is an email address"; Break } - '^(http[s]?)\://.*$' { "$_ is a web address that uses $($matches[1])"; Break } +switch -Regex ($target) { + '^ftp\://.*$' + { + "$_ is an ftp address" + break + } + '^\w+@\w+\.com|edu|org$' + { + "$_ is an email address" + break + } + '^(http[s]?)\://.*$' + { + "$_ is a web address that uses $($matches[1])" + break + } } ``` @@ -346,14 +341,9 @@ The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell -switch ("Test") -{ - {$_ -is [String]} { - "Found a string" - } - "Test" { - "This $_ executes as well" - } +switch ("Test") { + { $_ -is [String] } { "Found a string" } + "Test" { "This $_ executes as well" } } ``` @@ -369,10 +359,11 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { - { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).Days - "There are $days days until 2022." - } + { $_.Year -eq 2021 } + { + $days = ((Get-Date 1/1/2022) - $_).Days + "There are $days days until 2022." + } { $_.Year -eq 2022 } { 'Welcome to 2022!' } } ``` @@ -385,21 +376,16 @@ The `break` keyword stops processing and exits the `switch` statement. The `continue` keyword stops processing the current value, but continues processing any subsequent values. -The following example processes an array of numbers and displays if they are +The following example processes an array of numbers and displays if they're odd or even. Negative numbers are skipped with the `continue` keyword. If a non-number is encountered, execution is terminated with the `break` keyword. ```powershell -switch (1,4,-1,3,"Hello",2,1) -{ - {$_ -lt 0} { continue } - {$_ -isnot [Int32]} { break } - {$_ % 2} { - "$_ is Odd" - } - {-not ($_ % 2)} { - "$_ is Even" - } +switch (1,4,-1,3,"Hello",2,1) { + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } + {$_ % 2} { "$_ is Odd" } + {-not ($_ % 2)} { "$_ is Even" } } ``` @@ -409,9 +395,66 @@ switch (1,4,-1,3,"Hello",2,1) 3 is Odd ``` +## File parameter examples + +Using the `switch` statement with the **File** parameter is an efficient way to +process large files line by line. PowerShell streams the lines of the file to +the `switch` statement. Each line is processed individually. + +You can terminate +the processing before reaching the end of the file by using the `break` keyword +in the action statement. The `switch` statement is more efficient than using +`Get-Content` to process large files line by line. + +You can combine `switch -File` with `-Wildcard` or `-Regex` for flexible and efficient line-by-line pattern matching. + +The following example reads the `README.md` in the PowerShell-Docs repository. +It outputs each line until it reaches the line that starts with `##`. + +```powershell +switch -Regex -File .\README.md { + '^##\s' { break } + default { $_; continue } +} +``` + +The `` argument is interpreted as a wildcard expression, but it must +match only one file. The following example is the same as the previous one +except it uses a wildcard in the `` argument. This example works +because the wildcard pattern matches only one file. + +```powershell +switch -Regex -File .\README.* { + '^##\s' { break } + default { $_; continue } +} +``` + +You must escape characters that can be interpreted as wildcards if you want +them to be treated as literals. + +```powershell +$file = (New-Item -Path 'Temp:\Foo[0]' -Value Foo -Force).FullName +switch -File $file { Foo { 'Foo' } } +# No files matching '...\Temp\Foo[0]' were found. + +$fileEscaped = [WildcardPattern]::Escape($file) +switch -File $fileEscaped { foo { 'Foo' } } +# Foo +``` + ## See also -- [about_Break](about_Break.md) -- [about_Continue](about_Continue.md) -- [about_If](about_If.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_break][03] +- [about_Continue][05] +- [about_If][06] +- [about_Script_Blocks][07] + + +[01]: #file-parameter-examples +[02]: about_Automatic_Variables.md +[03]: about_break.md +[04]: about_Comparison_Operators.md +[05]: about_Continue.md +[06]: about_If.md +[07]: about_Script_Blocks.md diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Break.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Break.md index e85f34bda438..892d4e94914b 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Break.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Break.md @@ -132,7 +132,7 @@ specific condition: ```powershell $var = "word2" -switch -regex ($var) { +switch -Regex ($var) { "word2" { Write-Host "Exact" $_ break diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Language_Keywords.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Language_Keywords.md index bb879fdc1a8f..b44a46a95f7b 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Language_Keywords.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Language_Keywords.md @@ -487,7 +487,7 @@ condition obtains, the action is performed. Syntax 1: ```Syntax -switch [-regex|-wildcard|-exact][-casesensitive] ( ) +switch [-Regex|-Wildcard|-Exact][-CaseSensitive] ( ) { |||{ } {} |||{ } {} @@ -500,7 +500,7 @@ switch [-regex|-wildcard|-exact][-casesensitive] ( ) Syntax 2: ```Syntax -switch [-regex|-wildcard|-exact][-casesensitive] -file +switch [-Regex|-Wildcard|-Exact][-CaseSensitive] -File { |||{ } {} |||{ } {} diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md index e34c39f84a76..e2fee3aed9c3 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 02/28/2024 +ms.date: 02/19/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -19,20 +19,19 @@ statement can check many types of conditions, including the value of variables and the properties of objects. To check multiple conditions, use a `switch` statement. The `switch` statement -is equivalent to a series of `if` statements, but it is simpler. The `switch` +is equivalent to a series of `if` statements, but it's simpler. The `switch` statement lists each condition and an optional action. If a condition obtains, the action is performed. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see -[about_Automatic_Variables](about_Automatic_Variables.md). +more information, see [about_Automatic_Variables][02]. ## Syntax A basic `switch` statement has the following format: ```Syntax -Switch () +switch () { {} {} @@ -46,23 +45,23 @@ if ( -eq ()) {} if ( -eq ()) {} ``` -The `` is single expression that is evaluated in expression +The `` is single expression that's evaluated in expression mode to return a value. The `` is an expression whose value is compared to the input value. Expressions include literal values (strings or numbers), variables, and scriptblocks that return a boolean value. -Any unquoted value that is not recognized as a number is treated as a string. +Any unquoted value that's not recognized as a number is treated as a string. To avoid confusion or unintended string conversion, you should always quote string values. Enclose any expressions in parentheses `()`, creating subexpressions, to ensure that the expression is evaluated correctly. -It is important to understand that the `` value is on the +It's important to understand that the `` value is on the left-hand side of the comparison expression. That means the result of the `` is on the right-hand side, which can be converted to the type of the left-hand side value for comparison. For more information, see -[about_Comparison_Operators](about_Comparison_Operators.md) +[about_Comparison_Operators][04] The value `default` is reserved for the action used when there are no other matches. @@ -74,9 +73,9 @@ the `` statements. The complete `switch` statement syntax is as follows: ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] () -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] () { + string | number | variable | { } + { } default { } # optional } ``` @@ -84,39 +83,40 @@ switch [-regex | -wildcard | -exact] [-casesensitive] () or ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] -file filename -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] -File filename { + string | number | variable | { } + { } default { } # optional } ``` -If no parameters are used, `switch` behaves the same as using the **Exact** +If you don't use parameters, `switch` behaves the same as using the **Exact** parameter. It performs a case-insensitive match for the value. If the value is a collection, each element is evaluated in the order in which it appears. The `switch` statement must include at least one condition statement. -The `default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `else` clause in an `if` statement. Only one +The `default` clause is triggered when the value doesn't match any of the +conditions. It's equivalent to an `else` clause in an `if` statement. Only one `default` clause is permitted in each `switch` statement. `switch` has the following parameters: - **Wildcard** - Indicates that the condition is a wildcard string. If the - match clause is not a string, the parameter is ignored. The comparison is + match clause isn't a string, the parameter is ignored. The comparison is case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match - exactly. If the match clause is not a string, this parameter is ignored. The +- **Exact** - Indicates that the match clause, if it's a string, must match + exactly. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. - **CaseSensitive** - Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a ``. If - multiple **File** parameters are included, only the last one is used. Each - line of the file is read and evaluated by the `switch` statement. The - comparison is case-insensitive. +- **File**- Takes input from a file rather than a ``. The file + is read a line at a time and evaluated by the `switch` statement. By default, + the comparison is case-insensitive. The **File** parameter only supports one + file. If multiple **File** parameters are included, only the last one is + used.For more information see [File parameter examples][01]. - **Regex** - Performs regular expression matching of the value to the - condition. If the match clause is not a string, this parameter is ignored. + condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$matches` automatic variable is available for use within the matching statement block. @@ -126,44 +126,41 @@ conditions. It is equivalent to an `else` clause in an `if` statement. Only one > ignored. Multiple instances of parameters are also permitted. However, only > the last parameter listed is used. -## Examples +## Simple match examples -In the following example, the `switch` statement compares the test value, 3, to +In the following example, the `switch` statement compares the test value `3` to each of the conditions. When the test value matches the condition, the action is performed. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } } ``` ```Output -It is three. +It's three. ``` -In this simple example, the value is compared to each condition in the list, -even though there is a match for the value 3. The following `switch` statement -has two conditions for a value of 3. It demonstrates that, by default, all -conditions are tested. +In this example, the value is compared to each condition in the list. The +following `switch` statement has two conditions for a value of 3, which +demonstrates that all conditions are tested. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. Three again. ``` @@ -171,18 +168,17 @@ To direct the `switch` to stop comparing after a match, use the `break` statement. The `break` statement terminates the `switch` statement. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."; Break} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three."; break } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. ``` If the test value is a collection, such as an array, each item in the @@ -190,19 +186,18 @@ collection is evaluated in the order in which it appears. The following examples evaluates 4 and then 2. ```powershell -switch (4, 2) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is four. -It is two. +It's four. +It's two. ``` Any `break` statements apply to the collection, not to each value, as shown @@ -210,20 +205,21 @@ in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell -switch (4, 2) -{ - 1 {"It is one."; Break} - 2 {"It is two." ; Break} - 3 {"It is three." ; Break} - 4 {"It is four." ; Break} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one."; break } + 2 { "It's two." ; break } + 3 { "It's three." ; break } + 4 { "It's four." ; break } + 3 { "Three again." } } ``` ```Output -It is four. +It's four. ``` +## More complex match examples + In this example, the `switch` statement is testing for the type of the value in the hashtable. You must use and expression that returns a boolean value to select the scriptblock to execute. @@ -256,16 +252,9 @@ $test = @{ $test.ToString() -switch -Exact ($test) -{ - 'System.Collections.Hashtable' - { - 'Hashtable string coercion' - } - 'test' - { - 'Hashtable value' - } +switch -Exact ($test) { + 'System.Collections.Hashtable' { 'Hashtable string coercion' } + 'test' { 'Hashtable value' } } ``` @@ -277,13 +266,12 @@ Hashtable string coercion In this example, there is no matching case so there is no output. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } } ``` @@ -291,16 +279,13 @@ By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - Default { - "No matches" - } +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } + default { "No matches" } } ``` @@ -308,19 +293,18 @@ switch ("fourteen") No matches ``` -For the word "fourteen" to match a case you must use the `-Wildcard` or +For the word `fourteen` to match a case you must use the `-Wildcard` or `-Regex` parameter. ```powershell - PS> switch -Wildcard ("fourteen") - { - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - } - ``` +switch -Wildcard ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } +} +``` ```Output That's too many. @@ -330,11 +314,22 @@ The following example uses the `-Regex` parameter. ```powershell $target = 'https://bing.com' -switch -Regex ($target) -{ - '^ftp\://.*$' { "$_ is an ftp address"; Break } - '^\w+@\w+\.com|edu|org$' { "$_ is an email address"; Break } - '^(http[s]?)\://.*$' { "$_ is a web address that uses $($matches[1])"; Break } +switch -Regex ($target) { + '^ftp\://.*$' + { + "$_ is an ftp address" + break + } + '^\w+@\w+\.com|edu|org$' + { + "$_ is an email address" + break + } + '^(http[s]?)\://.*$' + { + "$_ is a web address that uses $($matches[1])" + break + } } ``` @@ -346,14 +341,9 @@ The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell -switch ("Test") -{ - {$_ -is [String]} { - "Found a string" - } - "Test" { - "This $_ executes as well" - } +switch ("Test") { + { $_ -is [String] } { "Found a string" } + "Test" { "This $_ executes as well" } } ``` @@ -369,10 +359,11 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { - { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).Days - "There are $days days until 2022." - } + { $_.Year -eq 2021 } + { + $days = ((Get-Date 1/1/2022) - $_).Days + "There are $days days until 2022." + } { $_.Year -eq 2022 } { 'Welcome to 2022!' } } ``` @@ -385,21 +376,16 @@ The `break` keyword stops processing and exits the `switch` statement. The `continue` keyword stops processing the current value, but continues processing any subsequent values. -The following example processes an array of numbers and displays if they are +The following example processes an array of numbers and displays if they're odd or even. Negative numbers are skipped with the `continue` keyword. If a non-number is encountered, execution is terminated with the `break` keyword. ```powershell -switch (1,4,-1,3,"Hello",2,1) -{ - {$_ -lt 0} { continue } - {$_ -isnot [Int32]} { break } - {$_ % 2} { - "$_ is Odd" - } - {-not ($_ % 2)} { - "$_ is Even" - } +switch (1,4,-1,3,"Hello",2,1) { + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } + {$_ % 2} { "$_ is Odd" } + {-not ($_ % 2)} { "$_ is Even" } } ``` @@ -409,9 +395,66 @@ switch (1,4,-1,3,"Hello",2,1) 3 is Odd ``` +## File parameter examples + +Using the `switch` statement with the **File** parameter is an efficient way to +process large files line by line. PowerShell streams the lines of the file to +the `switch` statement. Each line is processed individually. + +You can terminate +the processing before reaching the end of the file by using the `break` keyword +in the action statement. The `switch` statement is more efficient than using +`Get-Content` to process large files line by line. + +You can combine `switch -File` with `-Wildcard` or `-Regex` for flexible and efficient line-by-line pattern matching. + +The following example reads the `README.md` in the PowerShell-Docs repository. +It outputs each line until it reaches the line that starts with `##`. + +```powershell +switch -Regex -File .\README.md { + '^##\s' { break } + default { $_; continue } +} +``` + +The `` argument is interpreted as a wildcard expression, but it must +match only one file. The following example is the same as the previous one +except it uses a wildcard in the `` argument. This example works +because the wildcard pattern matches only one file. + +```powershell +switch -Regex -File .\README.* { + '^##\s' { break } + default { $_; continue } +} +``` + +You must escape characters that can be interpreted as wildcards if you want +them to be treated as literals. + +```powershell +$file = (New-Item -Path 'Temp:\Foo[0]' -Value Foo -Force).FullName +switch -File $file { Foo { 'Foo' } } +# No files matching '...\Temp\Foo[0]' were found. + +$fileEscaped = [WildcardPattern]::Escape($file) +switch -File $fileEscaped { foo { 'Foo' } } +# Foo +``` + ## See also -- [about_Break](about_Break.md) -- [about_Continue](about_Continue.md) -- [about_If](about_If.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_break][03] +- [about_Continue][05] +- [about_If][06] +- [about_Script_Blocks][07] + + +[01]: #file-parameter-examples +[02]: about_Automatic_Variables.md +[03]: about_break.md +[04]: about_Comparison_Operators.md +[05]: about_Continue.md +[06]: about_If.md +[07]: about_Script_Blocks.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Language_Keywords.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Language_Keywords.md index 8ceb12511d52..587e21bd4dd4 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Language_Keywords.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Language_Keywords.md @@ -487,7 +487,7 @@ condition obtains, the action is performed. Syntax 1: ```Syntax -switch [-regex|-wildcard|-exact][-casesensitive] ( ) +switch [-Regex|-Wildcard|-Exact][-CaseSensitive] ( ) { |||{ } {} |||{ } {} @@ -500,7 +500,7 @@ switch [-regex|-wildcard|-exact][-casesensitive] ( ) Syntax 2: ```Syntax -switch [-regex|-wildcard|-exact][-casesensitive] -file +switch [-Regex|-Wildcard|-Exact][-CaseSensitive] -File { |||{ } {} |||{ } {} diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md index a0d2e38624e8..e26a256d9337 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 02/28/2024 +ms.date: 02/19/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -19,20 +19,19 @@ statement can check many types of conditions, including the value of variables and the properties of objects. To check multiple conditions, use a `switch` statement. The `switch` statement -is equivalent to a series of `if` statements, but it is simpler. The `switch` +is equivalent to a series of `if` statements, but it's simpler. The `switch` statement lists each condition and an optional action. If a condition obtains, the action is performed. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see -[about_Automatic_Variables](about_Automatic_Variables.md). +more information, see [about_Automatic_Variables][02]. ## Syntax A basic `switch` statement has the following format: ```Syntax -Switch () +switch () { {} {} @@ -46,23 +45,23 @@ if ( -eq ()) {} if ( -eq ()) {} ``` -The `` is single expression that is evaluated in expression +The `` is single expression that's evaluated in expression mode to return a value. The `` is an expression whose value is compared to the input value. Expressions include literal values (strings or numbers), variables, and scriptblocks that return a boolean value. -Any unquoted value that is not recognized as a number is treated as a string. +Any unquoted value that's not recognized as a number is treated as a string. To avoid confusion or unintended string conversion, you should always quote string values. Enclose any expressions in parentheses `()`, creating subexpressions, to ensure that the expression is evaluated correctly. -It is important to understand that the `` value is on the +It's important to understand that the `` value is on the left-hand side of the comparison expression. That means the result of the `` is on the right-hand side, which can be converted to the type of the left-hand side value for comparison. For more information, see -[about_Comparison_Operators](about_Comparison_Operators.md) +[about_Comparison_Operators][04] The value `default` is reserved for the action used when there are no other matches. @@ -74,9 +73,9 @@ the `` statements. The complete `switch` statement syntax is as follows: ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] () -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] () { + string | number | variable | { } + { } default { } # optional } ``` @@ -84,39 +83,40 @@ switch [-regex | -wildcard | -exact] [-casesensitive] () or ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] -file filename -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] -File filename { + string | number | variable | { } + { } default { } # optional } ``` -If no parameters are used, `switch` behaves the same as using the **Exact** +If you don't use parameters, `switch` behaves the same as using the **Exact** parameter. It performs a case-insensitive match for the value. If the value is a collection, each element is evaluated in the order in which it appears. The `switch` statement must include at least one condition statement. -The `default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `else` clause in an `if` statement. Only one +The `default` clause is triggered when the value doesn't match any of the +conditions. It's equivalent to an `else` clause in an `if` statement. Only one `default` clause is permitted in each `switch` statement. `switch` has the following parameters: - **Wildcard** - Indicates that the condition is a wildcard string. If the - match clause is not a string, the parameter is ignored. The comparison is + match clause isn't a string, the parameter is ignored. The comparison is case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match - exactly. If the match clause is not a string, this parameter is ignored. The +- **Exact** - Indicates that the match clause, if it's a string, must match + exactly. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. - **CaseSensitive** - Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a ``. If - multiple **File** parameters are included, only the last one is used. Each - line of the file is read and evaluated by the `switch` statement. The - comparison is case-insensitive. +- **File**- Takes input from a file rather than a ``. The file + is read a line at a time and evaluated by the `switch` statement. By default, + the comparison is case-insensitive. The **File** parameter only supports one + file. If multiple **File** parameters are included, only the last one is + used.For more information see [File parameter examples][01]. - **Regex** - Performs regular expression matching of the value to the - condition. If the match clause is not a string, this parameter is ignored. + condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$matches` automatic variable is available for use within the matching statement block. @@ -126,44 +126,41 @@ conditions. It is equivalent to an `else` clause in an `if` statement. Only one > ignored. Multiple instances of parameters are also permitted. However, only > the last parameter listed is used. -## Examples +## Simple match examples -In the following example, the `switch` statement compares the test value, 3, to +In the following example, the `switch` statement compares the test value `3` to each of the conditions. When the test value matches the condition, the action is performed. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } } ``` ```Output -It is three. +It's three. ``` -In this simple example, the value is compared to each condition in the list, -even though there is a match for the value 3. The following `switch` statement -has two conditions for a value of 3. It demonstrates that, by default, all -conditions are tested. +In this example, the value is compared to each condition in the list. The +following `switch` statement has two conditions for a value of 3, which +demonstrates that all conditions are tested. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. Three again. ``` @@ -171,18 +168,17 @@ To direct the `switch` to stop comparing after a match, use the `break` statement. The `break` statement terminates the `switch` statement. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."; Break} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three."; break } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. ``` If the test value is a collection, such as an array, each item in the @@ -190,19 +186,18 @@ collection is evaluated in the order in which it appears. The following examples evaluates 4 and then 2. ```powershell -switch (4, 2) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is four. -It is two. +It's four. +It's two. ``` Any `break` statements apply to the collection, not to each value, as shown @@ -210,20 +205,21 @@ in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell -switch (4, 2) -{ - 1 {"It is one."; Break} - 2 {"It is two." ; Break} - 3 {"It is three." ; Break} - 4 {"It is four." ; Break} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one."; break } + 2 { "It's two." ; break } + 3 { "It's three." ; break } + 4 { "It's four." ; break } + 3 { "Three again." } } ``` ```Output -It is four. +It's four. ``` +## More complex match examples + In this example, the `switch` statement is testing for the type of the value in the hashtable. You must use and expression that returns a boolean value to select the scriptblock to execute. @@ -256,16 +252,9 @@ $test = @{ $test.ToString() -switch -Exact ($test) -{ - 'System.Collections.Hashtable' - { - 'Hashtable string coercion' - } - 'test' - { - 'Hashtable value' - } +switch -Exact ($test) { + 'System.Collections.Hashtable' { 'Hashtable string coercion' } + 'test' { 'Hashtable value' } } ``` @@ -277,13 +266,12 @@ Hashtable string coercion In this example, there is no matching case so there is no output. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } } ``` @@ -291,16 +279,13 @@ By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - Default { - "No matches" - } +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } + default { "No matches" } } ``` @@ -308,19 +293,18 @@ switch ("fourteen") No matches ``` -For the word "fourteen" to match a case you must use the `-Wildcard` or +For the word `fourteen` to match a case you must use the `-Wildcard` or `-Regex` parameter. ```powershell - PS> switch -Wildcard ("fourteen") - { - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - } - ``` +switch -Wildcard ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } +} +``` ```Output That's too many. @@ -330,11 +314,22 @@ The following example uses the `-Regex` parameter. ```powershell $target = 'https://bing.com' -switch -Regex ($target) -{ - '^ftp\://.*$' { "$_ is an ftp address"; Break } - '^\w+@\w+\.com|edu|org$' { "$_ is an email address"; Break } - '^(http[s]?)\://.*$' { "$_ is a web address that uses $($matches[1])"; Break } +switch -Regex ($target) { + '^ftp\://.*$' + { + "$_ is an ftp address" + break + } + '^\w+@\w+\.com|edu|org$' + { + "$_ is an email address" + break + } + '^(http[s]?)\://.*$' + { + "$_ is a web address that uses $($matches[1])" + break + } } ``` @@ -346,14 +341,9 @@ The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell -switch ("Test") -{ - {$_ -is [String]} { - "Found a string" - } - "Test" { - "This $_ executes as well" - } +switch ("Test") { + { $_ -is [String] } { "Found a string" } + "Test" { "This $_ executes as well" } } ``` @@ -369,10 +359,11 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { - { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).Days - "There are $days days until 2022." - } + { $_.Year -eq 2021 } + { + $days = ((Get-Date 1/1/2022) - $_).Days + "There are $days days until 2022." + } { $_.Year -eq 2022 } { 'Welcome to 2022!' } } ``` @@ -385,21 +376,16 @@ The `break` keyword stops processing and exits the `switch` statement. The `continue` keyword stops processing the current value, but continues processing any subsequent values. -The following example processes an array of numbers and displays if they are +The following example processes an array of numbers and displays if they're odd or even. Negative numbers are skipped with the `continue` keyword. If a non-number is encountered, execution is terminated with the `break` keyword. ```powershell -switch (1,4,-1,3,"Hello",2,1) -{ - {$_ -lt 0} { continue } - {$_ -isnot [Int32]} { break } - {$_ % 2} { - "$_ is Odd" - } - {-not ($_ % 2)} { - "$_ is Even" - } +switch (1,4,-1,3,"Hello",2,1) { + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } + {$_ % 2} { "$_ is Odd" } + {-not ($_ % 2)} { "$_ is Even" } } ``` @@ -409,9 +395,66 @@ switch (1,4,-1,3,"Hello",2,1) 3 is Odd ``` +## File parameter examples + +Using the `switch` statement with the **File** parameter is an efficient way to +process large files line by line. PowerShell streams the lines of the file to +the `switch` statement. Each line is processed individually. + +You can terminate +the processing before reaching the end of the file by using the `break` keyword +in the action statement. The `switch` statement is more efficient than using +`Get-Content` to process large files line by line. + +You can combine `switch -File` with `-Wildcard` or `-Regex` for flexible and efficient line-by-line pattern matching. + +The following example reads the `README.md` in the PowerShell-Docs repository. +It outputs each line until it reaches the line that starts with `##`. + +```powershell +switch -Regex -File .\README.md { + '^##\s' { break } + default { $_; continue } +} +``` + +The `` argument is interpreted as a wildcard expression, but it must +match only one file. The following example is the same as the previous one +except it uses a wildcard in the `` argument. This example works +because the wildcard pattern matches only one file. + +```powershell +switch -Regex -File .\README.* { + '^##\s' { break } + default { $_; continue } +} +``` + +You must escape characters that can be interpreted as wildcards if you want +them to be treated as literals. + +```powershell +$file = (New-Item -Path 'Temp:\Foo[0]' -Value Foo -Force).FullName +switch -File $file { Foo { 'Foo' } } +# No files matching '...\Temp\Foo[0]' were found. + +$fileEscaped = [WildcardPattern]::Escape($file) +switch -File $fileEscaped { foo { 'Foo' } } +# Foo +``` + ## See also -- [about_Break](about_Break.md) -- [about_Continue](about_Continue.md) -- [about_If](about_If.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_break][03] +- [about_Continue][05] +- [about_If][06] +- [about_Script_Blocks][07] + + +[01]: #file-parameter-examples +[02]: about_Automatic_Variables.md +[03]: about_break.md +[04]: about_Comparison_Operators.md +[05]: about_Continue.md +[06]: about_If.md +[07]: about_Script_Blocks.md diff --git a/reference/docs-conceptual/lang-spec/chapter-08.md b/reference/docs-conceptual/lang-spec/chapter-08.md index 2034451860c9..1d270df94fae 100644 --- a/reference/docs-conceptual/lang-spec/chapter-08.md +++ b/reference/docs-conceptual/lang-spec/chapter-08.md @@ -63,10 +63,10 @@ labeled-statement: Description: -An iteration statement ([§8.4][§8.4]) or a switch statement ([§8.6][§8.6]) may optionally be preceded -immediately by one statement label, *label*. A statement label is used as the optional target of a -break ([§8.5.1][§8.5.1]) or continue ([§8.5.2][§8.5.2]) statement. However, a label does not alter the flow of -control. +An iteration statement ([§8.4][§8.4]) or a switch statement ([§8.6][§8.6]) may optionally be +preceded immediately by one statement label, *label*. A statement label is used as the optional +target of a break ([§8.5.1][§8.5.1]) or continue ([§8.5.2][§8.5.2]) statement. However, a label +does not alter the flow of control. White space is not permitted between the colon (`:`) and the token that follows it. @@ -228,14 +228,14 @@ governing arguments are as follows: - Putting parentheses around an argument causes that expression to be evaluated with the result being passed instead of the text of the original expression. -- To pass an argument that looks like a switch parameter ([§2.3.4][§2.3.4]) but is not intended as such, - enclose that argument in quotes. +- To pass an argument that looks like a switch parameter ([§2.3.4][§2.3.4]) but is not intended as + such, enclose that argument in quotes. - When specifying an argument that matches a parameter having the `[switch]` type constraint - ([§8.10.5][§8.10.5]), the presence of the argument name on its own causes that parameter to be set to - `$true`. However, the parameter's value can be set explicitly by appending a suffix to the - argument. For example, given a type constrained parameter *p*, an argument of `-p:$true` sets p to - True, while `-p:$false` sets p to False. + ([§8.10.5][§8.10.5]), the presence of the argument name on its own causes that parameter to be + set to `$true`. However, the parameter's value can be set explicitly by appending a suffix to the + argument. For example, given a type constrained parameter *p*, an argument of `-p:$true` sets p + to True, while `-p:$false` sets p to False. - An argument of `--` indicates that all arguments following it are to be passed in their actual form as though double quotes were placed around them. @@ -258,16 +258,16 @@ For information about parameter binding see [§8.14][§8.14]. For information ab [§3.8][§3.8]. Once argument processing has been completed, the command is invoked. If the invoked command -terminates normally ([§8.5.4][§8.5.4]), control reverts to the point in the script or function immediately -following the command invocation. For a description of the behavior on abnormal termination see -`break` ([§8.5.1][§8.5.1]), `continue` ([§8.5.2][§8.5.2]), `throw` ([§8.5.3][§8.5.3]), `exit` ([§8.5.5][§8.5.5]), `try` -([§8.7][§8.7]), and `trap` ([§8.8][§8.8]). +terminates normally ([§8.5.4][§8.5.4]), control reverts to the point in the script or function +immediately following the command invocation. For a description of the behavior on abnormal +termination see `break` ([§8.5.1][§8.5.1]), `continue` ([§8.5.2][§8.5.2]), `throw` +([§8.5.3][§8.5.3]), `exit` ([§8.5.5][§8.5.5]), `try` ([§8.7][§8.7]), and `trap` ([§8.8][§8.8]). Ordinarily, a command is invoked by using its name followed by any arguments. However, the command-invocation operator, &, can be used. If the command name contains unescaped white space, it -must be quoted and invoked with this operator. As a script block has no name, it too must be invoked -with this operator. For example, the following invocations of a command call `Get-Factorial` are -equivalent: +must be quoted and invoked with this operator. As a script block has no name, it too must be +invoked with this operator. For example, the following invocations of a command call +`Get-Factorial` are equivalent: ```powershell Get-Factorial 5 @@ -292,7 +292,9 @@ New-Object -ArgumentList 3,2 -TypeName 'int[,]' dir e:\PowerShell\Scripts\*statement*.ps1 | Foreach-Object {$_.Length} -dir e:\PowerShell\Scripts\*.ps1 | Select-String -List "catch" | Format-Table path,linenumber -AutoSize +dir e:\PowerShell\Scripts\*.ps1 | + Select-String -List "catch" | + Format-Table path,linenumber -AutoSize ``` ## 8.3 The if statement @@ -786,15 +788,15 @@ switch-parameters: switch-parameters switch-parameter switch-parameter: - -regex - -wildcard - -exact - -casesensitive - -parallel + -Regex + -Wildcard + -Exact + -CaseSensitive + -Parallel switch-condition: ( new-lines~opt~ pipeline new-lines~opt~ ) - -file new-lines~opt~ switch-filename + -File new-lines~opt~ switch-filename switch-filename: command-argument @@ -847,26 +849,26 @@ that *statement-block*'s *switch-clause-condition*. Matching of non-strings is done by testing for equality ([§7.8.1][§7.8.1]). If the matching involves strings, by default, the comparison is case-insensitive. The presence of -the *switch-parameter* `-casesensitive` makes the comparison case-sensitive. +the *switch-parameter* `-CaseSensitive` makes the comparison case-sensitive. A pattern may contain wildcard characters ([§3.15][§3.15]), in which case, wildcard string comparisons -are performed, but only if the *switch-parameter* -wildcard is present. By default, the comparison +are performed, but only if the *switch-parameter* `-Wildcard` is present. By default, the comparison is case-insensitive. A pattern may contain a regular expression ([§3.16][§3.16]), in which case, regular expression string -comparisons are performed, but only if the *switch-parameter* `-regex` is present. By default, the -comparison is case-insensitive. If `-regex` is present and a pattern is matched, `$matches` is +comparisons are performed, but only if the *switch-parameter* `-Regex` is present. By default, the +comparison is case-insensitive. If `-Regex` is present and a pattern is matched, `$matches` is defined in the *switch-clause* *statement-block* for that pattern. A *switch-parameter* may be abbreviated; any distinct leading part of a parameter may be used. For -example, `‑regex`, `‑rege`, `‑reg`, `‑re`, and `‑r` are equivalent. +example, `‑Regex`, `‑Rege`, `‑Reg`, `‑Re`, and `‑R` are equivalent. If conflicting *switch-parameter*s are specified, the lexically final one prevails. The presence of -`‑exact` disables `-regex` and `-wildcard`; it has no affect on `‑case`, however. +`‑Exact` disables `-Regex` and `-Wildcard`; it has no affect on `‑Case`, however. -If the *switch-parameter* `‑parallel` is specified, the behavior is implementation defined. +If the *switch-parameter* `‑Parallel` is specified, the behavior is implementation defined. -The *switch-parameter* `‑parallel` is only allowed in a workflow ([§8.10.2][§8.10.2]). +The *switch-parameter* `‑Parallel` is only allowed in a workflow ([§8.10.2][§8.10.2]). If a pattern is a *script-block-expression*, that block is evaluated and the result is converted to bool, if necessary. If the result has the value `$true`, the corresponding *statement-block* is @@ -880,7 +882,7 @@ while that switch is executing. A switch statement may have a label, and it may contain labeled and unlabeled break ([§8.5.1][§8.5.1]) and continue ([§8.5.2][§8.5.2]) statements. -If *switch-condition* is `-file` *switch-filename*, instead of iterating over the values in an +If *switch-condition* is `-File` *switch-filename*, instead of iterating over the values in an expression, the switch iterates over the values in the file designated by *switch-filename*.The file is read a line at a time with each line comprising a value. Line terminator characters are not included in the values. @@ -901,13 +903,13 @@ for ($i = 0; $i -lt $s.Length; ++$i) { } } -switch -wildcard ("abc") { +switch -Wildcard ("abc") { a* { "a*, $_" } ?B? { "?B? , $_" } default { "default, $_" } } -switch -regex -casesensitive ("abc") { +switch -Regex -CaseSensitive ("abc") { ^a* { "a*" } ^A* { "A*" } } diff --git a/reference/docs-conceptual/lang-spec/chapter-15.md b/reference/docs-conceptual/lang-spec/chapter-15.md index b9d7d0854413..8af7d22556f2 100644 --- a/reference/docs-conceptual/lang-spec/chapter-15.md +++ b/reference/docs-conceptual/lang-spec/chapter-15.md @@ -656,11 +656,11 @@ switch-parameters: switch-parameters switch-parameter switch-parameter: - -regex - -wildcard - -exact - -casesensitive - -parallel + -Regex + -Wildcard + -Exact + -CaseSensitive + -Parallel switch-condition: ( new-lines~opt~ pipeline new-lines~opt~ ) diff --git a/reference/docs-conceptual/learn/deep-dives/everything-about-switch.md b/reference/docs-conceptual/learn/deep-dives/everything-about-switch.md index 50b63d1f55dd..b3b10ce22749 100644 --- a/reference/docs-conceptual/learn/deep-dives/everything-about-switch.md +++ b/reference/docs-conceptual/learn/deep-dives/everything-about-switch.md @@ -190,7 +190,7 @@ The matches aren't case-sensitive by default. If you need to be case-sensitive, ### -Wildcard -We can enable wildcard support with the `-wildcard` switch. This uses the same wildcard logic as the +We can enable wildcard support with the `-Wildcard` switch. This uses the same wildcard logic as the `-like` operator to do each match. ``` powershell @@ -247,7 +247,7 @@ I have more examples of using regex in another article I wrote: ### -File A little known feature of the switch statement is that it can process a file with the `-File` -parameter. You use `-file` with a path to a file instead of giving it a variable expression. +parameter. You use `-File` with a path to a file instead of giving it a variable expression. ``` powershell switch -Wildcard -File $path @@ -289,7 +289,7 @@ Whatever the expression evaluates to is the value used for the match. ### Multiple matches You may have already picked up on this, but a `switch` can match to multiple conditions. This is -especially true when using `-wildcard` or `-regex` matches. You can add the same condition multiple +especially true when using `-Wildcard` or `-Regex` matches. You can add the same condition multiple times and all are triggered. ``` powershell @@ -568,7 +568,7 @@ action with named matches. ``` powershell $message = 'my ssn is 123-23-3456 and credit card: 1234-5678-1234-5678' -switch -regex ($message) +switch -Regex ($message) { '(?\d\d\d-\d\d-\d\d\d\d)' {