diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Foreach.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Foreach.md index 8b14449a8a88..94b18ce2fca3 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Foreach.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Foreach.md @@ -1,7 +1,7 @@ --- description: Describes a language command you can use to traverse all the items in a collection of items. Locale: en-US -ms.date: 01/18/2022 +ms.date: 10/20/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_foreach?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Foreach @@ -14,11 +14,11 @@ collection of items. ## Long description -The `foreach` statement (also known as a `foreach` loop) is a language construct -for stepping through (iterating) a series of values in a collection of items. +The `foreach` statement is a language construct for iterating over a set of +values in a collection. The simplest and most typical type of collection to traverse is an array. -Within a `foreach` loop, it is common to run one or more commands against each +Within a `foreach` loop, it's common to run one or more commands against each item in an array. ## Syntax @@ -29,37 +29,34 @@ The following shows the `foreach` syntax: foreach ($ in $){} ``` -The part of the `foreach` statement enclosed in parenthesis represents a -variable and a collection to iterate. PowerShell creates the variable -`$` automatically when the `foreach` loop runs. Prior to each -iteration through the loop, the variable is set to a value in the collection. -The block following a `foreach` statement `{}` contains a set -of commands to execute against each item in a collection. +The part of the `foreach` statement inside parenthesis represents a variable +and a collection to iterate. PowerShell creates the variable `$` +automatically when the `foreach` loop runs. At the start of each iteration, +`foreach` sets the item variable to the next value in the collection. The +`{}` block contains the commands to execute for each iteration. ### Examples -For example, the `foreach` loop in the following example displays the values -in the `$letterArray` array. +For example, the `foreach` loop in the following example displays the values in +the `$letterArray` array. ```powershell -$letterArray = "a","b","c","d" +$letterArray = 'a','b','c','d' foreach ($letter in $letterArray) { Write-Host $letter } ``` -In this example, the `$letterArray` array is created and initialized with the -string values `"a"`, `"b"`, `"c"`, and `"d"`. The first time the `foreach` -statement runs, it sets the `$letter` variable equal to the first item in -`$letterArray` (`"a"`). Then, it uses the `Write-Host` cmdlet to display the -letter a. The next time through the loop, `$letter` is set to `"b"`, and so -on. After the `foreach` loop displays the letter d, PowerShell exits -the loop. +In this example, the `$letterArray` contains the string values `a`, `b`, +`c`, and `d`. The first time the `foreach` statement runs, it sets the +`$letter` variable equal to the first item in `$letterArray` (`a`). Then, it +uses `Write-Host` to display the value. The next time through the loop, +`$letter` is set to `b`. The pattern repeats for each item in the array. -`foreach` statements can also be used together with cmdlets that return a -collection of items. In the following example, the Foreach statement steps -through the list of items that is returned by the `Get-ChildItem` cmdlet. +You can also use `foreach` statements with cmdlets that return a collection of +items. In the following example, the `foreach` statement steps through the list +of items returned by the `Get-ChildItem` cmdlet. ```powershell foreach ($file in Get-ChildItem) @@ -68,16 +65,14 @@ foreach ($file in Get-ChildItem) } ``` -You can refine the example by using an `if` statement to limit the results -that are returned. In the following example, the `foreach` statement performs -the same looping operation as the previous example, but it adds an `if` -statement to limit the results to files that are greater than 100 kilobytes -(KB): +You can refine the example using an `if` statement to limit the results that +are returned. In the following example, the `if` statement limits the results +to files that are greater than 100 kilobytes (KB): ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) + if ($file.Length -gt 100KB) { Write-Host $file } @@ -85,75 +80,67 @@ foreach ($file in Get-ChildItem) ``` In this example, the `foreach` loop uses a property of the `$file` variable to -perform a comparison operation (`$file.length -gt 100KB`). The `$file` -variable contains all the properties in the object that is returned by the -`Get-ChildItem` cmdlet. Therefore, you can return more than just a file name. -In the next example, PowerShell returns the length and the last access time +perform a comparison operation (`$file.length -gt 100KB`). The `$file` variable +has all the properties of the object returned by the `Get-ChildItem`. + +In the next example, the script displays the length and the last access time inside the statement list: ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) + if ($file.Length -gt 100KB) { Write-Host $file - Write-Host $file.length - Write-Host $file.lastaccesstime + Write-Host $file.Length + Write-Host $file.LastAccessTime } } ``` -In this example, you are not limited to running a single command in a -statement list. - -You can also use a variable outside a `foreach` loop and increment the -variable inside the loop. The following example counts files over 100 KB in -size: +You can also use variables from outside a `foreach` loop. The following example +counts files over 100 KB in size: ```powershell $i = 0 foreach ($file in Get-ChildItem) { if ($file.length -gt 100KB) { - Write-Host $file "file size:" ($file.length / 1024).ToString("F0") KB + Write-Host $file 'file size:' ($file.length / 1024).ToString('F0') KB $i = $i + 1 } } if ($i -ne 0) { Write-Host - Write-Host $i " file(s) over 100 KB in the current directory." + Write-Host $i ' file(s) over 100KB in the current directory.' } else { - Write-Host "No files greater than 100 KB in the current directory." + Write-Host 'No files greater than 100KB in the current directory.' } ``` -In the preceding example, the `$i` variable is set to `0` outside the loop, -and the variable is incremented inside the loop for each file that is found -that is larger than 100 KB. When the loop exits, an `if` statement evaluates -the value of `$i` to display a count of all the files over 100 KB. Or, it -displays a message stating that no files over 100 KB were found. +In the preceding example, `$i` starts with a value of `0` outside the loop. +Then, `$i` is incremented inside the loop for each file that's larger than +100KB. When the loop exits, an `if` statement evaluates the value of `$i` to +display a count of files over 100KB. The previous example also demonstrates how to format the file length results: ```powershell -($file.length / 1024).ToString("F0") +($file.length / 1024).ToString('F0') ``` The value is divided by 1,024 to show the results in kilobytes rather than bytes, and the resulting value is then formatted using the fixed-point format -specifier to remove any decimal values from the result. The 0 makes the format -specifier show no decimal places. +specifier to remove any decimal values from the result. The `0` makes the +format specifier show no decimal places. -In the following example, the function defined parses PowerShell scripts and -script modules and returns the location of functions contained within. The -example demonstrates how to use the `MoveNext` method (which works similarly -to `skip X` on a `For` loop) and the `Current` property of the `$foreach` -variable inside of a foreach script block. The example function can find -functions in a script even if there are unusually- or inconsistently-spaced -function definitions that span multiple lines. +The following function parses PowerShell scripts and script modules and returns +the location of functions contained within. The example demonstrates how to use +the `MoveNext` method and the `Current` property of the `$foreach` variable +inside of a `foreach` script block. -For more information, see [Using Enumerators](about_Automatic_Variables.md#using-enumerators). +For more information, see [Using Enumerators][02]. ```powershell function Get-FunctionPosition { @@ -171,23 +158,19 @@ function Get-FunctionPosition { process { try { $filesToProcess = if ($_ -is [System.IO.FileSystemInfo]) { - Write-Verbose "From pipeline" $_ } else { - Write-Verbose "From parameter, $Path" Get-Item -Path $Path } $parser = [System.Management.Automation.Language.Parser] - Write-Verbose "lets start the foreach loop on `$filesToProcess with $($filesToProcess.count) as count" foreach ($item in $filesToProcess) { - Write-Verbose "$item" if ($item.PSIsContainer -or $item.Extension -notin @('.ps1', '.psm1')) { continue } $tokens = $errors = $null - $parser::ParseFile($item.FullName, ([REF]$tokens), - ([REF]$errors)) | Out-Null + $ast = $parser::ParseFile($item.FullName, ([ref]$tokens), + ([ref]$errors)) if ($errors) { $msg = "File '{0}' has {1} parser errors." -f $item.FullName, $errors.Count @@ -209,8 +192,12 @@ function Get-FunctionPosition { LineNumber = $position Path = $item.FullName } - Add-Member -InputObject $functionPosition ` - -TypeName FunctionPosition -PassThru + $addMemberSplat = @{ + InputObject = $functionPosition + TypeName = 'FunctionPosition' + PassThru = $true + } + Add-Member @addMemberSplat } } } @@ -223,6 +210,12 @@ function Get-FunctionPosition { ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_If](about_If.md) -- [ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) +- [about_Automatic_Variables][01] +- [about_If][03] +- [ForEach-Object][04] + + +[01]: about_Automatic_Variables.md +[02]: about_Automatic_Variables.md#using-enumerators +[03]: about_If.md +[04]: xref:Microsoft.PowerShell.Core.ForEach-Object diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Foreach.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Foreach.md index 233fd663ea8c..b8153c8eba34 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Foreach.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Foreach.md @@ -1,7 +1,7 @@ --- description: Describes a language command you can use to traverse all the items in a collection of items. Locale: en-US -ms.date: 01/18/2022 +ms.date: 10/20/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_foreach?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Foreach @@ -14,11 +14,11 @@ collection of items. ## Long description -The `foreach` statement (also known as a `foreach` loop) is a language construct -for stepping through (iterating) a series of values in a collection of items. +The `foreach` statement is a language construct for iterating over a set of +values in a collection. The simplest and most typical type of collection to traverse is an array. -Within a `foreach` loop, it is common to run one or more commands against each +Within a `foreach` loop, it's common to run one or more commands against each item in an array. ## Syntax @@ -29,37 +29,34 @@ The following shows the `foreach` syntax: foreach ($ in $){} ``` -The part of the `foreach` statement enclosed in parenthesis represents a -variable and a collection to iterate. PowerShell creates the variable -`$` automatically when the `foreach` loop runs. Prior to each -iteration through the loop, the variable is set to a value in the collection. -The block following a `foreach` statement `{}` contains a set -of commands to execute against each item in a collection. +The part of the `foreach` statement inside parenthesis represents a variable +and a collection to iterate. PowerShell creates the variable `$` +automatically when the `foreach` loop runs. At the start of each iteration, +`foreach` sets the item variable to the next value in the collection. The +`{}` block contains the commands to execute for each iteration. ### Examples -For example, the `foreach` loop in the following example displays the values -in the `$letterArray` array. +For example, the `foreach` loop in the following example displays the values in +the `$letterArray` array. ```powershell -$letterArray = "a","b","c","d" +$letterArray = 'a','b','c','d' foreach ($letter in $letterArray) { Write-Host $letter } ``` -In this example, the `$letterArray` array is created and initialized with the -string values `"a"`, `"b"`, `"c"`, and `"d"`. The first time the `foreach` -statement runs, it sets the `$letter` variable equal to the first item in -`$letterArray` (`"a"`). Then, it uses the `Write-Host` cmdlet to display the -letter a. The next time through the loop, `$letter` is set to `"b"`, and so -on. After the `foreach` loop displays the letter d, PowerShell exits -the loop. +In this example, the `$letterArray` contains the string values `a`, `b`, +`c`, and `d`. The first time the `foreach` statement runs, it sets the +`$letter` variable equal to the first item in `$letterArray` (`a`). Then, it +uses `Write-Host` to display the value. The next time through the loop, +`$letter` is set to `b`. The pattern repeats for each item in the array. -`foreach` statements can also be used together with cmdlets that return a -collection of items. In the following example, the Foreach statement steps -through the list of items that is returned by the `Get-ChildItem` cmdlet. +You can also use `foreach` statements with cmdlets that return a collection of +items. In the following example, the `foreach` statement steps through the list +of items returned by the `Get-ChildItem` cmdlet. ```powershell foreach ($file in Get-ChildItem) @@ -68,16 +65,14 @@ foreach ($file in Get-ChildItem) } ``` -You can refine the example by using an `if` statement to limit the results -that are returned. In the following example, the `foreach` statement performs -the same looping operation as the previous example, but it adds an `if` -statement to limit the results to files that are greater than 100 kilobytes -(KB): +You can refine the example using an `if` statement to limit the results that +are returned. In the following example, the `if` statement limits the results +to files that are greater than 100 kilobytes (KB): ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) + if ($file.Length -gt 100KB) { Write-Host $file } @@ -85,75 +80,67 @@ foreach ($file in Get-ChildItem) ``` In this example, the `foreach` loop uses a property of the `$file` variable to -perform a comparison operation (`$file.length -gt 100KB`). The `$file` -variable contains all the properties in the object that is returned by the -`Get-ChildItem` cmdlet. Therefore, you can return more than just a file name. -In the next example, PowerShell returns the length and the last access time +perform a comparison operation (`$file.length -gt 100KB`). The `$file` variable +has all the properties of the object returned by the `Get-ChildItem`. + +In the next example, the script displays the length and the last access time inside the statement list: ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) + if ($file.Length -gt 100KB) { Write-Host $file - Write-Host $file.length - Write-Host $file.lastaccesstime + Write-Host $file.Length + Write-Host $file.LastAccessTime } } ``` -In this example, you are not limited to running a single command in a -statement list. - -You can also use a variable outside a `foreach` loop and increment the -variable inside the loop. The following example counts files over 100 KB in -size: +You can also use variables from outside a `foreach` loop. The following example +counts files over 100 KB in size: ```powershell $i = 0 foreach ($file in Get-ChildItem) { if ($file.length -gt 100KB) { - Write-Host $file "file size:" ($file.length / 1024).ToString("F0") KB + Write-Host $file 'file size:' ($file.length / 1024).ToString('F0') KB $i = $i + 1 } } if ($i -ne 0) { Write-Host - Write-Host $i " file(s) over 100 KB in the current directory." + Write-Host $i ' file(s) over 100KB in the current directory.' } else { - Write-Host "No files greater than 100 KB in the current directory." + Write-Host 'No files greater than 100KB in the current directory.' } ``` -In the preceding example, the `$i` variable is set to `0` outside the loop, -and the variable is incremented inside the loop for each file that is found -that is larger than 100 KB. When the loop exits, an `if` statement evaluates -the value of `$i` to display a count of all the files over 100 KB. Or, it -displays a message stating that no files over 100 KB were found. +In the preceding example, `$i` starts with a value of `0` outside the loop. +Then, `$i` is incremented inside the loop for each file that's larger than +100KB. When the loop exits, an `if` statement evaluates the value of `$i` to +display a count of files over 100KB. The previous example also demonstrates how to format the file length results: ```powershell -($file.length / 1024).ToString("F0") +($file.length / 1024).ToString('F0') ``` The value is divided by 1,024 to show the results in kilobytes rather than bytes, and the resulting value is then formatted using the fixed-point format -specifier to remove any decimal values from the result. The 0 makes the format -specifier show no decimal places. +specifier to remove any decimal values from the result. The `0` makes the +format specifier show no decimal places. -In the following example, the function defined parses PowerShell scripts and -script modules and returns the location of functions contained within. The -example demonstrates how to use the `MoveNext` method (which works similarly -to `skip X` on a `For` loop) and the `Current` property of the `$foreach` -variable inside of a foreach script block. The example function can find -functions in a script even if there are unusually- or inconsistently-spaced -function definitions that span multiple lines. +The following function parses PowerShell scripts and script modules and returns +the location of functions contained within. The example demonstrates how to use +the `MoveNext` method and the `Current` property of the `$foreach` variable +inside of a `foreach` script block. -For more information, see [Using Enumerators](about_Automatic_Variables.md#using-enumerators). +For more information, see [Using Enumerators][02]. ```powershell function Get-FunctionPosition { @@ -182,8 +169,8 @@ function Get-FunctionPosition { continue } $tokens = $errors = $null - $ast = $parser::ParseFile($item.FullName, ([REF]$tokens), - ([REF]$errors)) + $ast = $parser::ParseFile($item.FullName, ([ref]$tokens), + ([ref]$errors)) if ($errors) { $msg = "File '{0}' has {1} parser errors." -f $item.FullName, $errors.Count @@ -205,8 +192,12 @@ function Get-FunctionPosition { LineNumber = $position Path = $item.FullName } - Add-Member -InputObject $functionPosition ` - -TypeName FunctionPosition -PassThru + $addMemberSplat = @{ + InputObject = $functionPosition + TypeName = 'FunctionPosition' + PassThru = $true + } + Add-Member @addMemberSplat } } } @@ -219,6 +210,12 @@ function Get-FunctionPosition { ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_If](about_If.md) -- [ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) +- [about_Automatic_Variables][01] +- [about_If][03] +- [ForEach-Object][04] + + +[01]: about_Automatic_Variables.md +[02]: about_Automatic_Variables.md#using-enumerators +[03]: about_If.md +[04]: xref:Microsoft.PowerShell.Core.ForEach-Object diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Foreach.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Foreach.md index 528c402f2be0..0b5ddf8f4e06 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Foreach.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Foreach.md @@ -1,7 +1,7 @@ --- description: Describes a language command you can use to traverse all the items in a collection of items. Locale: en-US -ms.date: 01/18/2022 +ms.date: 10/20/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_foreach?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Foreach @@ -14,11 +14,11 @@ collection of items. ## Long description -The `foreach` statement (also known as a `foreach` loop) is a language construct -for stepping through (iterating) a series of values in a collection of items. +The `foreach` statement is a language construct for iterating over a set of +values in a collection. The simplest and most typical type of collection to traverse is an array. -Within a `foreach` loop, it is common to run one or more commands against each +Within a `foreach` loop, it's common to run one or more commands against each item in an array. ## Syntax @@ -29,37 +29,34 @@ The following shows the `foreach` syntax: foreach ($ in $){} ``` -The part of the `foreach` statement enclosed in parenthesis represents a -variable and a collection to iterate. PowerShell creates the variable -`$` automatically when the `foreach` loop runs. Prior to each -iteration through the loop, the variable is set to a value in the collection. -The block following a `foreach` statement `{}` contains a set -of commands to execute against each item in a collection. +The part of the `foreach` statement inside parenthesis represents a variable +and a collection to iterate. PowerShell creates the variable `$` +automatically when the `foreach` loop runs. At the start of each iteration, +`foreach` sets the item variable to the next value in the collection. The +`{}` block contains the commands to execute for each iteration. ### Examples -For example, the `foreach` loop in the following example displays the values -in the `$letterArray` array. +For example, the `foreach` loop in the following example displays the values in +the `$letterArray` array. ```powershell -$letterArray = "a","b","c","d" +$letterArray = 'a','b','c','d' foreach ($letter in $letterArray) { Write-Host $letter } ``` -In this example, the `$letterArray` array is created and initialized with the -string values `"a"`, `"b"`, `"c"`, and `"d"`. The first time the `foreach` -statement runs, it sets the `$letter` variable equal to the first item in -`$letterArray` (`"a"`). Then, it uses the `Write-Host` cmdlet to display the -letter a. The next time through the loop, `$letter` is set to `"b"`, and so -on. After the `foreach` loop displays the letter d, PowerShell exits -the loop. +In this example, the `$letterArray` contains the string values `a`, `b`, +`c`, and `d`. The first time the `foreach` statement runs, it sets the +`$letter` variable equal to the first item in `$letterArray` (`a`). Then, it +uses `Write-Host` to display the value. The next time through the loop, +`$letter` is set to `b`. The pattern repeats for each item in the array. -`foreach` statements can also be used together with cmdlets that return a -collection of items. In the following example, the Foreach statement steps -through the list of items that is returned by the `Get-ChildItem` cmdlet. +You can also use `foreach` statements with cmdlets that return a collection of +items. In the following example, the `foreach` statement steps through the list +of items returned by the `Get-ChildItem` cmdlet. ```powershell foreach ($file in Get-ChildItem) @@ -68,16 +65,14 @@ foreach ($file in Get-ChildItem) } ``` -You can refine the example by using an `if` statement to limit the results -that are returned. In the following example, the `foreach` statement performs -the same looping operation as the previous example, but it adds an `if` -statement to limit the results to files that are greater than 100 kilobytes -(KB): +You can refine the example using an `if` statement to limit the results that +are returned. In the following example, the `if` statement limits the results +to files that are greater than 100 kilobytes (KB): ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) + if ($file.Length -gt 100KB) { Write-Host $file } @@ -85,75 +80,67 @@ foreach ($file in Get-ChildItem) ``` In this example, the `foreach` loop uses a property of the `$file` variable to -perform a comparison operation (`$file.length -gt 100KB`). The `$file` -variable contains all the properties in the object that is returned by the -`Get-ChildItem` cmdlet. Therefore, you can return more than just a file name. -In the next example, PowerShell returns the length and the last access time +perform a comparison operation (`$file.length -gt 100KB`). The `$file` variable +has all the properties of the object returned by the `Get-ChildItem`. + +In the next example, the script displays the length and the last access time inside the statement list: ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) + if ($file.Length -gt 100KB) { Write-Host $file - Write-Host $file.length - Write-Host $file.lastaccesstime + Write-Host $file.Length + Write-Host $file.LastAccessTime } } ``` -In this example, you are not limited to running a single command in a -statement list. - -You can also use a variable outside a `foreach` loop and increment the -variable inside the loop. The following example counts files over 100 KB in -size: +You can also use variables from outside a `foreach` loop. The following example +counts files over 100 KB in size: ```powershell $i = 0 foreach ($file in Get-ChildItem) { if ($file.length -gt 100KB) { - Write-Host $file "file size:" ($file.length / 1024).ToString("F0") KB + Write-Host $file 'file size:' ($file.length / 1024).ToString('F0') KB $i = $i + 1 } } if ($i -ne 0) { Write-Host - Write-Host $i " file(s) over 100 KB in the current directory." + Write-Host $i ' file(s) over 100KB in the current directory.' } else { - Write-Host "No files greater than 100 KB in the current directory." + Write-Host 'No files greater than 100KB in the current directory.' } ``` -In the preceding example, the `$i` variable is set to `0` outside the loop, -and the variable is incremented inside the loop for each file that is found -that is larger than 100 KB. When the loop exits, an `if` statement evaluates -the value of `$i` to display a count of all the files over 100 KB. Or, it -displays a message stating that no files over 100 KB were found. +In the preceding example, `$i` starts with a value of `0` outside the loop. +Then, `$i` is incremented inside the loop for each file that's larger than +100KB. When the loop exits, an `if` statement evaluates the value of `$i` to +display a count of files over 100KB. The previous example also demonstrates how to format the file length results: ```powershell -($file.length / 1024).ToString("F0") +($file.length / 1024).ToString('F0') ``` The value is divided by 1,024 to show the results in kilobytes rather than bytes, and the resulting value is then formatted using the fixed-point format -specifier to remove any decimal values from the result. The 0 makes the format -specifier show no decimal places. +specifier to remove any decimal values from the result. The `0` makes the +format specifier show no decimal places. -In the following example, the function defined parses PowerShell scripts and -script modules and returns the location of functions contained within. The -example demonstrates how to use the `MoveNext` method (which works similarly -to `skip X` on a `For` loop) and the `Current` property of the `$foreach` -variable inside of a foreach script block. The example function can find -functions in a script even if there are unusually- or inconsistently-spaced -function definitions that span multiple lines. +The following function parses PowerShell scripts and script modules and returns +the location of functions contained within. The example demonstrates how to use +the `MoveNext` method and the `Current` property of the `$foreach` variable +inside of a `foreach` script block. -For more information, see [Using Enumerators](about_Automatic_Variables.md#using-enumerators). +For more information, see [Using Enumerators][02]. ```powershell function Get-FunctionPosition { @@ -182,8 +169,8 @@ function Get-FunctionPosition { continue } $tokens = $errors = $null - $ast = $parser::ParseFile($item.FullName, ([REF]$tokens), - ([REF]$errors)) + $ast = $parser::ParseFile($item.FullName, ([ref]$tokens), + ([ref]$errors)) if ($errors) { $msg = "File '{0}' has {1} parser errors." -f $item.FullName, $errors.Count @@ -205,8 +192,12 @@ function Get-FunctionPosition { LineNumber = $position Path = $item.FullName } - Add-Member -InputObject $functionPosition ` - -TypeName FunctionPosition -PassThru + $addMemberSplat = @{ + InputObject = $functionPosition + TypeName = 'FunctionPosition' + PassThru = $true + } + Add-Member @addMemberSplat } } } @@ -219,6 +210,12 @@ function Get-FunctionPosition { ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_If](about_If.md) -- [ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) +- [about_Automatic_Variables][01] +- [about_If][03] +- [ForEach-Object][04] + + +[01]: about_Automatic_Variables.md +[02]: about_Automatic_Variables.md#using-enumerators +[03]: about_If.md +[04]: xref:Microsoft.PowerShell.Core.ForEach-Object diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Foreach.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Foreach.md index 57cb7c290eb4..39a85d3fa87b 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Foreach.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Foreach.md @@ -1,7 +1,7 @@ --- description: Describes a language command you can use to traverse all the items in a collection of items. Locale: en-US -ms.date: 01/18/2022 +ms.date: 10/20/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_foreach?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Foreach @@ -14,11 +14,11 @@ collection of items. ## Long description -The `foreach` statement (also known as a `foreach` loop) is a language construct -for stepping through (iterating) a series of values in a collection of items. +The `foreach` statement is a language construct for iterating over a set of +values in a collection. The simplest and most typical type of collection to traverse is an array. -Within a `foreach` loop, it is common to run one or more commands against each +Within a `foreach` loop, it's common to run one or more commands against each item in an array. ## Syntax @@ -29,37 +29,34 @@ The following shows the `foreach` syntax: foreach ($ in $){} ``` -The part of the `foreach` statement enclosed in parenthesis represents a -variable and a collection to iterate. PowerShell creates the variable -`$` automatically when the `foreach` loop runs. Prior to each -iteration through the loop, the variable is set to a value in the collection. -The block following a `foreach` statement `{}` contains a set -of commands to execute against each item in a collection. +The part of the `foreach` statement inside parenthesis represents a variable +and a collection to iterate. PowerShell creates the variable `$` +automatically when the `foreach` loop runs. At the start of each iteration, +`foreach` sets the item variable to the next value in the collection. The +`{}` block contains the commands to execute for each iteration. ### Examples -For example, the `foreach` loop in the following example displays the values -in the `$letterArray` array. +For example, the `foreach` loop in the following example displays the values in +the `$letterArray` array. ```powershell -$letterArray = "a","b","c","d" +$letterArray = 'a','b','c','d' foreach ($letter in $letterArray) { Write-Host $letter } ``` -In this example, the `$letterArray` array is created and initialized with the -string values `"a"`, `"b"`, `"c"`, and `"d"`. The first time the `foreach` -statement runs, it sets the `$letter` variable equal to the first item in -`$letterArray` (`"a"`). Then, it uses the `Write-Host` cmdlet to display the -letter a. The next time through the loop, `$letter` is set to `"b"`, and so -on. After the `foreach` loop displays the letter d, PowerShell exits -the loop. +In this example, the `$letterArray` contains the string values `a`, `b`, +`c`, and `d`. The first time the `foreach` statement runs, it sets the +`$letter` variable equal to the first item in `$letterArray` (`a`). Then, it +uses `Write-Host` to display the value. The next time through the loop, +`$letter` is set to `b`. The pattern repeats for each item in the array. -`foreach` statements can also be used together with cmdlets that return a -collection of items. In the following example, the Foreach statement steps -through the list of items that is returned by the `Get-ChildItem` cmdlet. +You can also use `foreach` statements with cmdlets that return a collection of +items. In the following example, the `foreach` statement steps through the list +of items returned by the `Get-ChildItem` cmdlet. ```powershell foreach ($file in Get-ChildItem) @@ -68,16 +65,14 @@ foreach ($file in Get-ChildItem) } ``` -You can refine the example by using an `if` statement to limit the results -that are returned. In the following example, the `foreach` statement performs -the same looping operation as the previous example, but it adds an `if` -statement to limit the results to files that are greater than 100 kilobytes -(KB): +You can refine the example using an `if` statement to limit the results that +are returned. In the following example, the `if` statement limits the results +to files that are greater than 100 kilobytes (KB): ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) + if ($file.Length -gt 100KB) { Write-Host $file } @@ -85,75 +80,67 @@ foreach ($file in Get-ChildItem) ``` In this example, the `foreach` loop uses a property of the `$file` variable to -perform a comparison operation (`$file.length -gt 100KB`). The `$file` -variable contains all the properties in the object that is returned by the -`Get-ChildItem` cmdlet. Therefore, you can return more than just a file name. -In the next example, PowerShell returns the length and the last access time +perform a comparison operation (`$file.length -gt 100KB`). The `$file` variable +has all the properties of the object returned by the `Get-ChildItem`. + +In the next example, the script displays the length and the last access time inside the statement list: ```powershell foreach ($file in Get-ChildItem) { - if ($file.length -gt 100KB) + if ($file.Length -gt 100KB) { Write-Host $file - Write-Host $file.length - Write-Host $file.lastaccesstime + Write-Host $file.Length + Write-Host $file.LastAccessTime } } ``` -In this example, you are not limited to running a single command in a -statement list. - -You can also use a variable outside a `foreach` loop and increment the -variable inside the loop. The following example counts files over 100 KB in -size: +You can also use variables from outside a `foreach` loop. The following example +counts files over 100 KB in size: ```powershell $i = 0 foreach ($file in Get-ChildItem) { if ($file.length -gt 100KB) { - Write-Host $file "file size:" ($file.length / 1024).ToString("F0") KB + Write-Host $file 'file size:' ($file.length / 1024).ToString('F0') KB $i = $i + 1 } } if ($i -ne 0) { Write-Host - Write-Host $i " file(s) over 100 KB in the current directory." + Write-Host $i ' file(s) over 100KB in the current directory.' } else { - Write-Host "No files greater than 100 KB in the current directory." + Write-Host 'No files greater than 100KB in the current directory.' } ``` -In the preceding example, the `$i` variable is set to `0` outside the loop, -and the variable is incremented inside the loop for each file that is found -that is larger than 100 KB. When the loop exits, an `if` statement evaluates -the value of `$i` to display a count of all the files over 100 KB. Or, it -displays a message stating that no files over 100 KB were found. +In the preceding example, `$i` starts with a value of `0` outside the loop. +Then, `$i` is incremented inside the loop for each file that's larger than +100KB. When the loop exits, an `if` statement evaluates the value of `$i` to +display a count of files over 100KB. The previous example also demonstrates how to format the file length results: ```powershell -($file.length / 1024).ToString("F0") +($file.length / 1024).ToString('F0') ``` The value is divided by 1,024 to show the results in kilobytes rather than bytes, and the resulting value is then formatted using the fixed-point format -specifier to remove any decimal values from the result. The 0 makes the format -specifier show no decimal places. +specifier to remove any decimal values from the result. The `0` makes the +format specifier show no decimal places. -In the following example, the function defined parses PowerShell scripts and -script modules and returns the location of functions contained within. The -example demonstrates how to use the `MoveNext` method (which works similarly -to `skip X` on a `For` loop) and the `Current` property of the `$foreach` -variable inside of a foreach script block. The example function can find -functions in a script even if there are unusually- or inconsistently-spaced -function definitions that span multiple lines. +The following function parses PowerShell scripts and script modules and returns +the location of functions contained within. The example demonstrates how to use +the `MoveNext` method and the `Current` property of the `$foreach` variable +inside of a `foreach` script block. -For more information, see [Using Enumerators](about_Automatic_Variables.md#using-enumerators). +For more information, see [Using Enumerators][02]. ```powershell function Get-FunctionPosition { @@ -182,8 +169,8 @@ function Get-FunctionPosition { continue } $tokens = $errors = $null - $ast = $parser::ParseFile($item.FullName, ([REF]$tokens), - ([REF]$errors)) + $ast = $parser::ParseFile($item.FullName, ([ref]$tokens), + ([ref]$errors)) if ($errors) { $msg = "File '{0}' has {1} parser errors." -f $item.FullName, $errors.Count @@ -205,8 +192,12 @@ function Get-FunctionPosition { LineNumber = $position Path = $item.FullName } - Add-Member -InputObject $functionPosition ` - -TypeName FunctionPosition -PassThru + $addMemberSplat = @{ + InputObject = $functionPosition + TypeName = 'FunctionPosition' + PassThru = $true + } + Add-Member @addMemberSplat } } } @@ -219,6 +210,12 @@ function Get-FunctionPosition { ## See also -- [about_Automatic_Variables](about_Automatic_Variables.md) -- [about_If](about_If.md) -- [ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) +- [about_Automatic_Variables][01] +- [about_If][03] +- [ForEach-Object][04] + + +[01]: about_Automatic_Variables.md +[02]: about_Automatic_Variables.md#using-enumerators +[03]: about_If.md +[04]: xref:Microsoft.PowerShell.Core.ForEach-Object