Adding example for command validation handler in PSRL docs (#10283)

* Adding example for command validation handler in PSRL docs

* Editorial changes

---------

Co-authored-by: Sean Wheeler <[email protected]>

Author: StevenBucher98

reference/5.1/PSReadLine/Set-PSReadLineOption.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.PSReadLine2.dll-Help.xml
 Locale: en-US
 Module Name: PSReadline
-ms.date: 07/11/2023
+ms.date: 07/19/2023
 online version: https://learn.microsoft.com/powershell/module/psreadline/set-psreadlineoption?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Set-PSReadLineOption
@@ -169,6 +169,36 @@ The scriptblock returns `$false` if the command started with `git`. This has the
 returning the `SkipAdding` **AddToHistory** enum. If the command doesn't start with `git`, the
 handler returns `$true` and PSReadLine saves the command in history.
 
+### Example 8: Use CommandValidationHandler to validate a command before its executed
+
+This example shows how to use the **CommandValidationHandler** parameter to run a validate a command
+before it's executed. The example specifically checks for the command `git` with the sub command
+`cmt` and replaces that with the full name `commit`. This way you can create shorthand aliases for
+subcommands.
+
+```powershell
+# Load the namespace so you can use the [CommandAst] object type
+using namespace System.Management.Automation.Language
+
+Set-PSReadLineOption -CommandValidationHandler {
+    param([CommandAst]$CommandAst)
+
+    switch ($CommandAst.GetCommandName()) {
+        'git' {
+            $gitCmd = $CommandAst.CommandElements[1].Extent
+            switch ($gitCmd.Text) {
+                'cmt' {
+                    [Microsoft.PowerShell.PSConsoleReadLine]::Replace(
+                        $gitCmd.StartOffset, $gitCmd.EndOffset - $gitCmd.StartOffset, 'commit')
+                }
+            }
+        }
+    }
+}
+# This checks the validation script when you hit enter
+Set-PSReadLineKeyHandler -Chord Enter -Function ValidateAndAcceptLine
+```
+
 ## PARAMETERS
 
 ### -AddToHistoryHandler

reference/7.2/PSReadLine/Set-PSReadLineOption.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.PSReadLine2.dll-Help.xml
 Locale: en-US
 Module Name: PSReadLine
-ms.date: 07/11/2023
+ms.date: 07/19/2023
 online version: https://learn.microsoft.com/powershell/module/psreadline/set-psreadlineoption?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Set-PSReadLineOption
@@ -170,6 +170,36 @@ The scriptblock returns `$false` if the command started with `git`. This has the
 returning the `SkipAdding` **AddToHistory** enum. If the command doesn't start with `git`, the
 handler returns `$true` and PSReadLine saves the command in history.
 
+### Example 8: Use CommandValidationHandler to validate a command before its executed
+
+This example shows how to use the **CommandValidationHandler** parameter to run a validate a command
+before it's executed. The example specifically checks for the command `git` with the sub command
+`cmt` and replaces that with the full name `commit`. This way you can create shorthand aliases for
+subcommands.
+
+```powershell
+# Load the namespace so you can use the [CommandAst] object type
+using namespace System.Management.Automation.Language
+
+Set-PSReadLineOption -CommandValidationHandler {
+    param([CommandAst]$CommandAst)
+
+    switch ($CommandAst.GetCommandName()) {
+        'git' {
+            $gitCmd = $CommandAst.CommandElements[1].Extent
+            switch ($gitCmd.Text) {
+                'cmt' {
+                    [Microsoft.PowerShell.PSConsoleReadLine]::Replace(
+                        $gitCmd.StartOffset, $gitCmd.EndOffset - $gitCmd.StartOffset, 'commit')
+                }
+            }
+        }
+    }
+}
+# This checks the validation script when you hit enter
+Set-PSReadLineKeyHandler -Chord Enter -Function ValidateAndAcceptLine
+```
+
 ## PARAMETERS
 
 ### -AddToHistoryHandler

reference/7.3/PSReadLine/Set-PSReadLineOption.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.PSReadLine2.dll-Help.xml
 Locale: en-US
 Module Name: PSReadLine
-ms.date: 07/11/2023
+ms.date: 07/19/2023
 online version: https://learn.microsoft.com/powershell/module/psreadline/set-psreadlineoption?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Set-PSReadLineOption
@@ -170,6 +170,36 @@ The scriptblock returns `$false` if the command started with `git`. This has the
 returning the `SkipAdding` **AddToHistory** enum. If the command doesn't start with `git`, the
 handler returns `$true` and PSReadLine saves the command in history.
 
+### Example 8: Use CommandValidationHandler to validate a command before its executed
+
+This example shows how to use the **CommandValidationHandler** parameter to run a validate a command
+before it's executed. The example specifically checks for the command `git` with the sub command
+`cmt` and replaces that with the full name `commit`. This way you can create shorthand aliases for
+subcommands.
+
+```powershell
+# Load the namespace so you can use the [CommandAst] object type
+using namespace System.Management.Automation.Language
+
+Set-PSReadLineOption -CommandValidationHandler {
+    param([CommandAst]$CommandAst)
+
+    switch ($CommandAst.GetCommandName()) {
+        'git' {
+            $gitCmd = $CommandAst.CommandElements[1].Extent
+            switch ($gitCmd.Text) {
+                'cmt' {
+                    [Microsoft.PowerShell.PSConsoleReadLine]::Replace(
+                        $gitCmd.StartOffset, $gitCmd.EndOffset - $gitCmd.StartOffset, 'commit')
+                }
+            }
+        }
+    }
+}
+# This checks the validation script when you hit enter
+Set-PSReadLineKeyHandler -Chord Enter -Function ValidateAndAcceptLine
+```
+
 ## PARAMETERS
 
 ### -AddToHistoryHandler

reference/7.4/PSReadLine/Set-PSReadLineOption.md

@@ -2,7 +2,7 @@
 external help file: Microsoft.PowerShell.PSReadLine2.dll-Help.xml
 Locale: en-US
 Module Name: PSReadLine
-ms.date: 07/11/2023
+ms.date: 07/19/2023
 online version: https://learn.microsoft.com/powershell/module/psreadline/set-psreadlineoption?view=powershell-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Set-PSReadLineOption
@@ -170,6 +170,36 @@ The scriptblock returns `$false` if the command started with `git`. This has the
 returning the `SkipAdding` **AddToHistory** enum. If the command doesn't start with `git`, the
 handler returns `$true` and PSReadLine saves the command in history.
 
+### Example 8: Use CommandValidationHandler to validate a command before its executed
+
+This example shows how to use the **CommandValidationHandler** parameter to run a validate a command
+before it's executed. The example specifically checks for the command `git` with the sub command
+`cmt` and replaces that with the full name `commit`. This way you can create shorthand aliases for
+subcommands.
+
+```powershell
+# Load the namespace so you can use the [CommandAst] object type
+using namespace System.Management.Automation.Language
+
+Set-PSReadLineOption -CommandValidationHandler {
+    param([CommandAst]$CommandAst)
+
+    switch ($CommandAst.GetCommandName()) {
+        'git' {
+            $gitCmd = $CommandAst.CommandElements[1].Extent
+            switch ($gitCmd.Text) {
+                'cmt' {
+                    [Microsoft.PowerShell.PSConsoleReadLine]::Replace(
+                        $gitCmd.StartOffset, $gitCmd.EndOffset - $gitCmd.StartOffset, 'commit')
+                }
+            }
+        }
+    }
+}
+# This checks the validation script when you hit enter
+Set-PSReadLineKeyHandler -Chord Enter -Function ValidateAndAcceptLine
+```
+
 ## PARAMETERS
 
 ### -AddToHistoryHandler