(MicrosoftDocsGH-10088) Add example for normalizing Read-Host input

Prior to this change, the documentation for the `Read-Host` cmdlet didn't include information about trimming the input. The cmdlet doesn't have a built-in way to trim extra spaces from the input value, which is an arbitrary string. This change: - Adds an example to `Read-Host` showing how user input may need to normalized before it can be used. It also shows how a reader can apply some simple normalizing techniques to clean up the input. - Resolves MicrosoftDocs#10088 - Fixes AB#91532
michaeltlombardi · May 22, 2023 · 15fb612 · 15fb612
1 parent ea377f3
commit 15fb612
Show file tree

Hide file tree

Showing 4 changed files with 200 additions and 4 deletions.
diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Read-Host.md b/reference/5.1/Microsoft.PowerShell.Utility/Read-Host.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 05/22/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/read-host?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Read-Host
@@ -49,6 +49,55 @@ value is stored as a **SecureString** object in the `$pwd_secure_string` variabl
 $pwd_secure_string = Read-Host "Enter a Password" -AsSecureString
 ```
 
+### Example 3: Normalizing input
+
+This example prompts the user to input a list of cities separated by semi-colons. It shows the
+string's value as typed by the user. In the example, the user added spaces between some of
+the entries. This could lead to an error later in the script where the code expects an exact
+name.
+
+The example shows how you can convert an input string into an array of entries without any
+extra spaces.
+
+```powershell
+$prompt = @(
+    'List the cities you want weather information for.'
+    'When specifying multiple cities, separate them with a semi-colon, like:'
+    "'New York; Osan; Koforidua'"
+) -join ' '
+
+$cities = Read-Host $prompt
+
+"Input cities string: `n`t'$cities'"
+
+$splitCities = $cities -split ';'
+
+"Split cities array:"
+$splitCities | ForEach-Object -Process { "`t'$_'" }
+
+$normalizedCities = $splitCities  | ForEach-Object -Process { $_.Trim() }
+
+"Normalized split cities array:"
+$normalizedCities | ForEach-Object -Process { "`t'$_'" }
+```
+
+```output
+Input cities string:
+        '    New York;  Osan   ;Koforidua   '
+Split cities array:
+        '    New York'
+        '  Osan   '
+        'Koforidua   '
+Normalized split cities array:
+        'New York'
+        'Osan'
+        'Koforidua'
+```
+
+The example uses the `-split` operator to convert the input string into an array of strings. Each
+string in the array includes the name of a different city. However, the split strings include extra
+spaces. The `Trim()` method removes the leading and trailing spaces from each string.
+
 ## PARAMETERS
 
 ### -AsSecureString

diff --git a/reference/7.2/Microsoft.PowerShell.Utility/Read-Host.md b/reference/7.2/Microsoft.PowerShell.Utility/Read-Host.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 05/22/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/read-host?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Read-Host
@@ -67,6 +67,55 @@ value is stored as a plaintext **String** object in the `$pwd_string` variable.
 $pwd_string = Read-Host "Enter a Password" -MaskInput
 ```
 
+### Example 4: Normalizing input
+
+This example prompts the user to input a list of cities separated by semi-colons. It shows the
+string's value as typed by the user. In the example, the user added spaces between some of
+the entries. This could lead to an error later in the script where the code expects an exact
+name.
+
+The example shows how you can convert an input string into an array of entries without any
+extra spaces.
+
+```powershell
+$prompt = @(
+    'List the cities you want weather information for.'
+    'When specifying multiple cities, separate them with a semi-colon, like:'
+    "'New York; Osan; Koforidua'"
+) -join ' '
+
+$cities = Read-Host $prompt
+
+"Input cities string: `n`t'$cities'"
+
+$splitCities = $cities -split ';'
+
+"Split cities array:"
+$splitCities | ForEach-Object -Process { "`t'$_'" }
+
+$normalizedCities = $splitCities  | ForEach-Object -Process { $_.Trim() }
+
+"Normalized split cities array:"
+$normalizedCities | ForEach-Object -Process { "`t'$_'" }
+```
+
+```output
+Input cities string:
+        '    New York;  Osan   ;Koforidua   '
+Split cities array:
+        '    New York'
+        '  Osan   '
+        'Koforidua   '
+Normalized split cities array:
+        'New York'
+        'Osan'
+        'Koforidua'
+```
+
+The example uses the `-split` operator to convert the input string into an array of strings. Each
+string in the array includes the name of a different city. However, the split strings include extra
+spaces. The `Trim()` method removes the leading and trailing spaces from each string.
+
 ## PARAMETERS
 
 ### -AsSecureString

diff --git a/reference/7.3/Microsoft.PowerShell.Utility/Read-Host.md b/reference/7.3/Microsoft.PowerShell.Utility/Read-Host.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 05/22/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/read-host?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Read-Host
@@ -67,6 +67,55 @@ value is stored as a plaintext **String** object in the `$pwd_string` variable.
 $pwd_string = Read-Host "Enter a Password" -MaskInput
 ```
 
+### Example 4: Normalizing input
+
+This example prompts the user to input a list of cities separated by semi-colons. It shows the
+string's value as typed by the user. In the example, the user added spaces between some of
+the entries. This could lead to an error later in the script where the code expects an exact
+name.
+
+The example shows how you can convert an input string into an array of entries without any
+extra spaces.
+
+```powershell
+$prompt = @(
+    'List the cities you want weather information for.'
+    'When specifying multiple cities, separate them with a semi-colon, like:'
+    "'New York; Osan; Koforidua'"
+) -join ' '
+
+$cities = Read-Host $prompt
+
+"Input cities string: `n`t'$cities'"
+
+$splitCities = $cities -split ';'
+
+"Split cities array:"
+$splitCities | ForEach-Object -Process { "`t'$_'" }
+
+$normalizedCities = $splitCities  | ForEach-Object -Process { $_.Trim() }
+
+"Normalized split cities array:"
+$normalizedCities | ForEach-Object -Process { "`t'$_'" }
+```
+
+```output
+Input cities string:
+        '    New York;  Osan   ;Koforidua   '
+Split cities array:
+        '    New York'
+        '  Osan   '
+        'Koforidua   '
+Normalized split cities array:
+        'New York'
+        'Osan'
+        'Koforidua'
+```
+
+The example uses the `-split` operator to convert the input string into an array of strings. Each
+string in the array includes the name of a different city. However, the split strings include extra
+spaces. The `Trim()` method removes the leading and trailing spaces from each string.
+
 ## PARAMETERS
 
 ### -AsSecureString

diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Read-Host.md b/reference/7.4/Microsoft.PowerShell.Utility/Read-Host.md
@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 Locale: en-US
 Module Name: Microsoft.PowerShell.Utility
-ms.date: 12/12/2022
+ms.date: 05/22/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/read-host?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Read-Host
@@ -67,6 +67,55 @@ value is stored as a plaintext **String** object in the `$pwd_string` variable.
 $pwd_string = Read-Host "Enter a Password" -MaskInput
 ```
 
+### Example 4: Normalizing input
+
+This example prompts the user to input a list of cities separated by semi-colons. It shows the
+string's value as typed by the user. In the example, the user added spaces between some of
+the entries. This could lead to an error later in the script where the code expects an exact
+name.
+
+The example shows how you can convert an input string into an array of entries without any
+extra spaces.
+
+```powershell
+$prompt = @(
+    'List the cities you want weather information for.'
+    'When specifying multiple cities, separate them with a semi-colon, like:'
+    "'New York; Osan; Koforidua'"
+) -join ' '
+
+$cities = Read-Host $prompt
+
+"Input cities string: `n`t'$cities'"
+
+$splitCities = $cities -split ';'
+
+"Split cities array:"
+$splitCities | ForEach-Object -Process { "`t'$_'" }
+
+$normalizedCities = $splitCities  | ForEach-Object -Process { $_.Trim() }
+
+"Normalized split cities array:"
+$normalizedCities | ForEach-Object -Process { "`t'$_'" }
+```
+
+```output
+Input cities string:
+        '    New York;  Osan   ;Koforidua   '
+Split cities array:
+        '    New York'
+        '  Osan   '
+        'Koforidua   '
+Normalized split cities array:
+        'New York'
+        'Osan'
+        'Koforidua'
+```
+
+The example uses the `-split` operator to convert the input string into an array of strings. Each
+string in the array includes the name of a different city. However, the split strings include extra
+spaces. The `Trim()` method removes the leading and trailing spaces from each string.
+
 ## PARAMETERS
 
 ### -AsSecureString