Get-MenuChoice - 2017.04.05.02.49

function Send-Beep
    {
    #region - Comment Based Help

    <#
    .SYNOPSIS
        Sends a beep via either "[console]::Beep()" or "[char]7' [aka - the ASCII BEL character].

    .DESCRIPTION
        Sends a beep to the user using the BEL character if NOT in the ISE,
            otherwise it uses the [console]::Beep() method.
    .EXAMPLE
        Send-Beep

        If in the ISE, uses [console]::Beep() with the default frequency of 1000 Hertz
            for the default duration of 100 milliseconds.
        If not in the ISE, sends a BEL character [aka - [char]7, ctrl-g] to the console.

    .EXAMPLE
        Send-Beep -BeepFrequency 500 -BeepDuration 500

        If not in the ISE, sends a BEL character to the console.
        If in the ISE, uses [console]::Beep() with Frequency = 500 Hertz & Duration = 500 milliseconds.

    .NOTES
        Author = Lee Dailey
        Contact = find me on Reddit
        Version = 2017.04.07.03.29.00
    #>

    #endregion

    #region - Parameters
    [CmdletBinding()]
    Param (
        # Optional beep frequency in Hertz.
        [Parameter(
            Position = 0
            )]
            [ValidateRange(40, 4000)]
            [int]
            $BeepFrequency = 1000,

        # Optional beep duration in milliseconds.
        [Parameter(
            Position = 1
            )]
            [ValidateRange(10, 2000)]
            [int]
            $BeepDuration = 100
        )
    #endregion

    # The bell char doesn't work in the ISE
    if ($Host.Name -match 'ISE')
        {
        [console]::Beep($BeepFrequency, $BeepDuration)
        }
        else
        {
        Write-Host ([char]7)
        }
    } # end >> function Send-Beep

function Get-MenuChoice
    {
    #region - Comment Based Help [CBH]

    <#
    .SYNOPSIS
        Displays a text menu & returns a valid response.

    .DESCRIPTION
        Displays a string array as a menu & returns a valid response character by ...
            - testing for 2 to 9 items in the array
            - testing for a unique 1st character for each array item
            - showing the array
            - getting a response that matches one of the unique 1st characters
            - returning that character as a string

    .EXAMPLE
        Get-MenuChoice -MenuItems $TopMenu_Items

        - Displays the strings in the $TopMenu_Items array.
        - Shows no menu title.
        - Shows the default prompt.
        - Returns [as a string] the first single-character input that matches the first character
            of one of the menu items.

    .EXAMPLE
        Get-MenuChoice -MenuItems ('1 - First thing', '2 - Second thing', 'x - Exit') -MenuTitle 'Top Menu' -MenuPrompt 'Pick one '

        - Displays the strings in the input array.
        - Shows a title of "Top Menu".
        - Shows a prompt of "Pick one ".
        - Returns [as a string] the first single-character input that matches the first character
            of one of the menu items.

    .NOTES
        Author = Lee Dailey
        Contact = find me on Reddit
        Version = 2017.04.05.02.49

    #>

    #endregion

    #region - Parameters
    # For some unknown reason, parameter help comments will not work without a CBH.
    [CmdletBinding()]
    [OutputType([String])]
    Param (
        # Required string array of menu items to display.
        [Parameter(
            Mandatory,
            Position = 0
            )]
            [ValidateNotNullOrEmpty()]
            [ValidateCount(2,9)]
            [string[]]
            $MenuItems,

        # Optional menu title.
        [Parameter(
            Position = 1
            )]
            [string]
            $MenuTitle = '',

        # Optional user prompt.
        [Parameter(
            Position = 2
            )]
            [string]
            $MenuPrompt = 'Please enter a choice from the above items '
        )
    #endregion

    #region - Init & test variables
    $MenuChoice = ''
    $ValidMenuChoices = $MenuItems | ForEach-Object {$_[0]}

    # check for dupe 1st chars in menu items list
    if ($ValidMenuChoices.Count -ne ($ValidMenuChoices | Sort-Object | Get-Unique).Count)
        {
        Write-Error "The `$MenuItems variable has at least two items with identical first characters. >> $ValidMenuChoices <<" -ErrorAction Stop
        }
    #endregion

    while ($MenuChoice -notin $ValidMenuChoices)
        {
        Clear-Host
        if (-not [string]::IsNullOrEmpty($MenuTitle))
            {
            $MenuTitle | Out-Host
            }
        $MenuItems | Out-Host
        Write-host ''
        $MenuChoice = (Read-Host $MenuPrompt).ToLower()
        if ($MenuChoice -notin $ValidMenuChoices)
            {
            Send-Beep
            }
        }

    return $MenuChoice

    } # end >> function Get-MenuChoice


#region - Testing section - comment out or remove when finished
#region - Menu data

# used to trigger duplicate menu item 1st char error
$BadTopMenu_Items = (
    '1 - First submenu',
    '2 - Second submenu',
    '3 - Third submenu',
    '2 - <<<< Dupe 1st char! <<<<<',
    'x - Exit')
$BadTopMenu_Title = 'Bad Top Menu Title'
# the following line will trigger a stop error and show a Write-Error message
#Get-MenuChoice -MenuItems $BadTopMenu_Items -MenuTitle $BadTopMenu_Title


# these are for the multi-level menu test
$TopMenu_Items = (
    '1 - First submenu',
    '2 - Second submenu',
    '3 - Third submenu',
    'x - Exit')
$TopMenu_Title = 'Top Menu Title'

$SubMenu_1_Items = (
    '1 - Do the 1st SM_1 thing',
    '2 - Show a WScript Popup message',
    'r - Return to Top Menu')
$SubMenu_1_Title = 'Sub Menu One Title'
$SubMenu_1_Prompt = 'Prompt for Sub Menu One'

$SubMenu_2_Items = (
    'A - Perform action A',
    'B - Do action B',
    'C - Take action C',
    'D - Display the 1st level contents of the current users temp folder.',
    'r - Return to Top Menu')
$SubMenu_2_Title = 'Sub Menu Two Title'
$SubMenu_2_Prompt = 'Prompt for Sub Menu Two'

$SubMenu_3_Items = (
    '1 - Item 3.1',
    '2 - Item 3.2',
    '3 - Start Notepad and load exit instructions.',
    '4 - Item 3.4',
    'r - Return to Top Menu')
$SubMenu_3_Title = 'Sub Menu Three Title'
$SubMenu_3_Prompt = 'Prompt for Sub Menu Three'
#endregion


$Choice = ''
$CurrentMenu = 'TopMenu'

# ===== note >>>>> should i add an automatic `x - Exit` menu item to Get-MenuChoice?
while ($Choice -ne 'x')
    {
    switch ($CurrentMenu)
        {
        'TopMenu'
            {
            $Choice = Get-MenuChoice -MenuItems $TopMenu_Items -MenuTitle $TopMenu_Title
            switch ($Choice)
                {
                '1' {$CurrentMenu = 'SubMenu_1'; break}
                '2' {$CurrentMenu = 'SubMenu_2'; break}
                '3' {$CurrentMenu = 'SubMenu_3'; break}
                }
            }
        'SubMenu_1'
            {
            $ParamSplat = @{
                MenuItems = $SubMenu_1_Items
                MenuTitle = $SubMenu_1_Title
                MenuPrompt = $SubMenu_1_Prompt
                }
            $Choice = Get-MenuChoice @ParamSplat
            Write-Output ''
            switch ($Choice)
                {
                '1' {Write-Output 'Doing the >> 1st << thing from Sub Menu ONE.'; pause; break}
                '2' {
                    $PopupMessage = "You chose item $Choice from $CurrentMenu." +
                        "`n" +
                        "`n" +
                        "This dialog will auto-close in $PopupTimeout seconds."
                    $PopupTimeout = 10
                    $PopupTitle = $SubMenu_1_Title
                    (New-Object -ComObject "Wscript.Shell").Popup($PopupMessage, $PopupTimeout, $PopupTitle) |
                        Out-Null
                    break
                    }
                'r' {$CurrentMenu = 'TopMenu'; break}
                }
            }
        'SubMenu_2'
            {
            $ParamSplat = @{
                MenuItems = $SubMenu_2_Items
                MenuTitle = $SubMenu_2_Title
                MenuPrompt = $SubMenu_2_Prompt
                }
            $Choice = Get-MenuChoice @ParamSplat
            Write-Output '';
            switch ($Choice)
                {
                'a' {Write-Output 'Performing action >> A << from Sub Menu TWO.'; pause; break}
                'b' {Write-Output 'Doing action >> B << from Sub Menu TWO.'; pause; break}
                'c' {Write-Output 'Taking action >> C << from Sub Menu TWO.'; pause; break}
                'd' {
                    Get-ChildItem $env:TEMP |
                        Out-GridView
                    }
                'r' {$CurrentMenu = 'TopMenu'; break}
                }
            }
        'SubMenu_3'
            {
            $ParamSplat = @{
                MenuItems = $SubMenu_3_Items
                MenuTitle = $SubMenu_3_Title
                MenuPrompt = $SubMenu_3_Prompt
                }
            $Choice = Get-MenuChoice @ParamSplat
            Write-Output '';
            switch ($Choice)
                {
                '1' {Write-Output 'Item >> 3.1 << from Sub Menu THREE is what this is.'; pause; break}
                '2' {Write-Output 'This is item >> 3.2 << from Sub Menu THREE.'; pause; break}
                '3' {
                    $NotepadMessage = "You selected item 3.$Choice from $CurrentMenu." +
                        "`r`n" +
                        "`r`n" +
                        "Close Notepad to return to $CurrentMenu."
                    $NotepadMessageFile = Join-Path -Path $env:TEMP -ChildPath 'NotepadMessage.txt'
                    Add-Content -Value $NotepadMessage -Path $env:TEMP\NotepadMessage.txt
                    Start-Process Notepad.exe -ArgumentList $NotepadMessageFile -Wait
                    break
                    }
                '4' {Write-Output 'The fourth item is >> 3.4 << from Sub Menu THREE.'; pause; break}
                'r' {$CurrentMenu = 'TopMenu'; break}
                }
            }
        } # end >> switch ($CurrentMenu)
    } # end >> while ($Choice -ne 'x')

#endregion