#Requires -version 2.0

# -----------------------------------------------------------------------------
# Script: Set-Pause.ps1
# Version: 2.0
# Author: Jeffery Hicks
#    http://jdhitsolutions.com/blog
#    http://twitter.com/JeffHicks
# Date: 1/17/2011
# Keywords: 
# Comments: This will not work with the ISE.
#
# "Those who neglect to script are doomed to repeat their work."
#
#  ****************************************************************
#  * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED *
#  * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK.  IF   *
#  * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, *
#  * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING.             *
#  ****************************************************************
# -----------------------------------------------------------------------------

Function Set-Pause {

<#
   .Synopsis
    Force PowerShell to pause. 
    .Description
    Use this function to insert a pause command into your PowerShell script. The
    default is to wait for the user to press any key. Or you can specify a value
    in seconds. Once the interval is passed, the pause ends. You can customize the
    message as well as the color using the same foreground colors that you can use
    with Write-Host.
    
    NOTE: This function is designed to work with the PowerShell console. It won't
    work with the PowerShell ISE nor is there any guarantee it will work as written
    for other PowerShell hosts.
    .Parameter Message
    The message prompt to display. The default is "Press any key to continue..."
    .Parameter Foregroundcolor
    The font color for your message. This parameter uses the same values as the
    foregroundcolor parameter for Write-Host.
    
    "Black","DarkMagenta","DarkRed","DarkBlue","DarkGreen","DarkCyan","DarkYellow","Red",
    "Blue","Green","Cyan","Magenta","Yellow","DarkGray","Gray","White"
    .Parameter Sleep
    The number of seconds to pause. You must enter a value greater than 0. If not
    specified, the function waits for a key press. The parameter has an alias of Seconds.
    .Parameter Clear
    Clear the screen after each prompt or pause. This parameter has an alias of CLS.
   .Example
 PS S:\> Write-Host "$(get-date) starting"
01/17/2011 11:48:01 starting
PS S:\>  Pause -ForegroundColor Yellow
Press any key to continue...
PS S:\> Write-Host "$(get-date) continuing"
01/17/2011 11:48:02 continuing
PS S:\>
    .Example
 PS S:\> get-service lanman*

Status   Name               DisplayName
------   ----               -----------
Running  LanmanServer       Server
Running  LanmanWorkstation  Workstation


PS S:\>  pause -ForegroundColor Cyan -sleep 3 -message "Waiting for 3 seconds"
Waiting for 3 seconds
PS S:\>  write-host "$(get-date) finished"
01/17/2011 11:49:09 finished 

    .Example
    PS S:\> $sb={Pause "Waiting for Godot" -ForegroundColor Yellow;"Now we die."}
PS S:\> &$sb
Waiting for Godot
Now we die.
  
   .Notes
    NAME: Set-Pause
    AUTHOR: Jeffery Hicks
    VERSION: 1.0
    LASTEDIT: 01/17/2011 11:36:56
    
    Learn more with a copy of Windows PowerShell 2.0: TFM (SAPIEN Press 2010)
    
   .Link
    http://jdhitsolutions.com/blog/2011/01/we-pause-a-moment/
    .Link
    Write-Host
    
    .Inputs
    None
    
    .Outputs
    None
#>
 
 Param(
  [Parameter(Position=0)]
  [string]$Message="Press any key to continue...",
  
  [ValidateSet("Black","DarkMagenta","DarkRed","DarkBlue",
    "DarkGreen","DarkCyan","DarkYellow","Red",
    "Blue","Green","Cyan","Magenta","Yellow",
    "DarkGray","Gray","White" )]
  [string]$ForegroundColor="Green",
  
  [ValidateScript({$_ -gt 0})]
  [Alias("seconds")]
  [int32]$Sleep,
  
  [Alias("cls")]
  [switch]$Clear
  )
 
    Write-Host $Message -foregroundcolor $foregroundcolor
    
    #pause for specified number of seconds
    if ($Sleep)
    {
        Start-Sleep -Seconds $sleep
    }
    else
    {
        #wait for a key press
        $Running=$true
        
        While ($Running)
        {
    	 if ($host.ui.RawUi.KeyAvailable) {
             $key = $host.ui.RawUI.ReadKey("NoEcho,IncludeKeyDown")
                if ($key) {
                 $Running=$False          
                }
          }
          sleep -millisecond 100
        } #end While
    }
    
    if ($Clear)
    {
        Clear-Host
    }
} #end function

#set an alias
Set-Alias -Name Pause -Value Set-Pause