v2.24.0

Author: jdhitsolutions

PSScriptTools.psd1

@@ -9,7 +9,7 @@ Get-ChildItem -path $PSScriptRoot\functions\*.ps1 | ForEach-Object -process {
     . $_.FullName
 }
 
-#define the global PSAnsiFileMap variable
+Write-Verbose "Define the global PSAnsiFileMap variable"
 $json = "psansifilemap.json"
 #test for user version
 $userjson = Join-Path -path $HOME -ChildPath $json
@@ -24,7 +24,34 @@ else {
 
 Set-Variable -Name PSAnsiFileMap -value (Get-Content -path $map | ConvertFrom-Json) -Scope Global
 
-#add ToDo options to the ISE or VS Code
+Write-Verbose "Define special character map"
+$global:PSSpecialChar = @{
+    FullBlock        = ([char]0x2588)
+    LightShade       = ([char]0x2591)
+    MediumShade      = ([char]0x2592)
+    DarkShade        = ([char]0x2593)
+    BlackSquare      = ([char]0x25A0)
+    WhiteSquare      = ([char]0x25A1)
+    BlackSmallSquare = ([char]0x25AA)
+    WhiteSmallSquare = ([char]0x25AB)
+    UpTriangle       = ([char]0x25B2)
+    DownTriangle     = ([char]0x25BC)
+    Lozenge          = ([char]0x25CA)
+    WhiteCircle      = ([char]0x25CB)
+    BlackCircle      = ([char]0x25CF)
+    WhiteFace        = ([char]0x263A)
+    BlackFace        = ([char]0x263B)
+    SixPointStar     = ([char]0x2736)
+    Diamond          = ([char]0x2666)
+    Club             = ([char]0x2663)
+    Heart            = ([char]0x2665)
+    Spade            = ([char]0x2660)
+}
+
+Write-Verbose "Defining the variable `$PSSamplePath to the samples folder for this module"
+$global:PSSamplePath = Join-Path -path $PSScriptroot -ChildPath Samples
+
+Write-Verbose "Add ToDo options to the ISE or VS Code"
 if ($psEditor) {
     #This may not be working in newer versions of the PowerShell extension under PowerShell 7
     Write-Verbose "Defining VSCode additions"
@@ -35,7 +62,7 @@ if ($psEditor) {
 
         $prompt = "What do you need to do?"
         $title = "To Do"
-        $item = Invoke-Inputbox -Title $title -Prompt $prompt
+        $item = Invoke-InputBox -Title $title -Prompt $prompt
         $todo = "# [$(Get-Date)] TODO: $item"
         $context.CurrentFile.InsertText($todo)
     }
@@ -55,7 +82,7 @@ elseif ($psise) {
         $action = {
             $prompt = "What do you need to do?"
             $title = "To Do"
-            $item = Invoke-Inputbox -Title $title -Prompt $prompt
+            $item = Invoke-InputBox -Title $title -Prompt $prompt
             $todo = "# [$(Get-Date)] TODO: $item"
             $psise.CurrentFile.Editor.InsertText($todo)
             #jump cursor to the end

PSScriptTools.psm1

@@ -2,7 +2,7 @@
 
 [![PSGallery Version](https://img.shields.io/powershellgallery/v/PSScripttools.png?style=for-the-badge&logo=powershell&label=PowerShell%20Gallery)](https://www.powershellgallery.com/packages/PSScripttools/) [![PSGallery Downloads](https://img.shields.io/powershellgallery/dt/PSScripttools.png?style=for-the-badge&label=Downloads)](https://www.powershellgallery.com/packages/PSScripttools/)
 
-This PowerShell module contains a number of functions you might use to enhance your own functions and scripts. The [Samples](./samples) folder contains demonstration script files.
+This module contains a collection of functions, variables and format files that you can use to enhance your PowerShell scripting work. Or get more done from a PowerShell prompt with less typing. Most of the commands are designed to work cross-platform.
 
 ## Current Release
 
@@ -51,8 +51,7 @@ PS C:\> Get-ModuleCommand PSCalendar
     Show-GuiCalendar               gcal            Function  Display a WPF-based calendar
 ```
 
-Get module commands using the default formatted view.
-There is also a default view for `Format-List`.
+Get module commands using the default formatted view. There is also a default view for `Format-List`.
 
 ### [Get-PSScriptTools](docs/Get-PSScriptTools.md)
 
@@ -324,6 +323,10 @@ ExecutionPolicy : RemoteSigned
 Culture         : English (United States)
 ```
 
+You can also turn this into a text block using the `AsString` parameter. This is helpful when you want to include the output in some type of report.
+
+![PSWho Report](images/add-border-ansi2.png)
+
 ### [Find-CimClass](docs/Find-CimClass.md)
 
 This function is designed to search an entire CIM repository for a class name. Sometimes, you may have a guess about a class name but not know the full name or even the correct namespace. `Find-CimClass` will recursively search for a given classname. You can use wildcards and search remote computers.
@@ -392,6 +395,25 @@ You can also get detailed information.
 
 Results will vary depending on whether you are running PowerShell on Windows nor non-Windows systems.
 
+### [Get-PathVariable](docs/Get-PathVariable.md)
+
+Over time, as you add and remove programs, your `%PATH%` might change. An application may add a location but not remove it when you uninstall the application. This command makes it easier to identify locations and whether they are still good.
+
+```powershell
+PS C:\> Get-PathVariable
+
+Scope   UserName Path                                                                     Exists
+-----   -------- ----                                                                     ------
+User    Jeff     C:\Program Files\kdiff3                                                  True
+User    Jeff     C:\Program Files (x86)\Bitvise SSH Client                                True
+User    Jeff     C:\Program Files\OpenSSH                                                 True
+User    Jeff     C:\Program Files\Intel\WiFi\bin\                                         True
+User    Jeff     C:\Program Files\Common Files\Intel\WirelessCommon\                      True
+User    Jeff     C:\Users\Jeff\AppData\Local\Programs\Microsoft VS Code\bin               True
+User    Jeff     C:\Program Files (x86)\Vale\                                             True
+...
+```
+
 ## File Tools
 
 ### [Test-EmptyFolder](docs/Test-EmptyFolder.md)
@@ -1125,6 +1147,50 @@ C:\work\Alpha\
 
 This example is using parameter and command aliases. You can display a tree listing with files including user specified properties. Use a value of * to show all properties.
 
+### [New-ANSIBar](docs/New-ANSIBar.md)
+
+You can use this command to create colorful bars using ANSI escape sequences based on a 256 color scheme. The default behavior is to create a gradient bar that goes from first to last values in the range and then back down again. Or you can create a single gradient that runs from the beginning of the range to the end. You can use one of the default characters or specify a custom one.
+
+![New-ANSIBar](images/ansibar.png)
+
+### [New-RedGreenGradient](docs/New-RedGreenGradient.md)
+
+A related command is `New-RedGreenGradient` which displays a bar going from red to green. This might be handy when you want to present a visual indicator.
+
+![New-RedGreenGradient](images/redgreen.png)
+
+### [Write-ANSIProgress](docs/Write-ANSIProgress.md)
+
+You could also use `Write-ANSIProgress` to show a custom ANSI bar.
+
+![Write-ANSIProgress simple](images/write-ansprogress-1.png)
+
+![write-ANSIProgress in code](images/write-ansprogress-2.png)
+
+Or you can use it in your code to display a console progress bar.
+
+```powershell
+$sb = {
+        Clear-Host
+        $top = Get-ChildItem c:\scripts -Directory
+        $i = 0
+        $out=@()
+        $pos = $host.ui.RawUI.CursorPosition
+        Foreach ($item in $top) {
+            $i++
+            $pct = [math]::round($i/$top.count,2)
+            Write-ANSIProgress -PercentComplete $pct -position $pos
+            Write-Host "  Processing $(($item.fullname).padright(80))" -ForegroundColor Yellow -NoNewline
+            $out+= Get-ChildItem -path $item -Recurse -file | Measure-Object -property length -sum |
+            Select-Object @{Name="Path";Expression={$item.fullname}},Count,@{Name="Size";Expression={$_.Sum}}
+        }
+        Write-Host ""
+        $out | Sort-object -property Size -Descending
+    }
+```
+
+![Write-ANSIProgress script](images/write-ansprogress-3.png)
+
 ## Format-Functions
 
 A set of simple commands to make it easier to format values.
@@ -1385,7 +1451,7 @@ You will need to manually install the file.
 
 ## Other
 
-From time to time I will include additional items that you might find useful. One item that you get when you import this module is a custom format.ps1xml file for services. If you are running PowerShell 7, you can run `Get-Service` and pipe it to the table view.
+From time to time I will include additional items that you might find useful. One item that you get when you import this module is a custom format.ps1xml file for services. You can run `Get-Service` and pipe it to the table view.
 
 ```powershell
 PS C:\> Get-Service | Format-Table -view ansi
@@ -1395,6 +1461,8 @@ This will display the service status color-coded.
 
 ![ServiceAnsi](images/serviceansi.png)
 
+This will not work in the PowerShell ISE as it is not ANSI aware.
+
 ### PSAnsiMap
 
 I have done something similar for output from `Get-ChildItem`. The module includes json file that is exported as a global variable called `PSAnsiFileMap`.
@@ -1417,7 +1485,7 @@ ChildContainer
 
 The map includes ANSI settings for different file types. You won't see the ANSI value in the output. The module will add a custom table view called `ansi` which you can use to display file results colorized in PowerShell 7.
 
-![](images/ansi-file-format.png)
+![ANSI File listing](images/ansi-file-format.png)
 
 The mapping file is user customizable. Copy the `psansifilemap.json` file from the module's root directory to $HOME. When you import this module, if the file is found, it will be imported and used as `psansifilemap`, otherwise the module's file will be used.
 
@@ -1475,6 +1543,26 @@ The file will look like this:
 
 You can create or modify file groups. The Pattern value should be a regular expression pattern to match on the filename. Don't forget you will need to escape characters for the json format. The Ansi value will be an ANSI escape sequence. You can use `\u001b` for the \``e` character.
 
+### PSSpecialChar
+
+A number of the commands in this module can use special characters. To make it easier, when you import the module it will create a global variable that is a hash table of common special characters. Because it is a hashtable you can add ones you also use.
+
+![PSSpecialChar](images/psspecialchar.png)
+
+The names are the same as used in CharMap.exe. Don't let the naming confuse you. It may say `BlackSquare` but the color will depend on how you use it.
+
+```powershell
+Get-WindowsVersionString | Add-Border -border $PSSpecialChar.BlackSmallSquare -ANSIBorder "$([char]0x1b)[38;5;214m"
+```
+
+![PSSpecialChar Border](images/psspecialchar-border.png)
+
+### Sample scripts
+
+This PowerShell module contains a number of functions you might use to enhance your own functions and scripts. The [Samples](./samples) folder contains demonstration script files. You can access the folder in PowerShell using the `$PSSamplePath`. The samples provide suggestions on how you might use some of the commands in this module. The scripts are offered AS-IS and are for demonstration purposes only.
+
+![ProcessPercent.ps1](images/processpercent.png)
+
 ## Related Modules
 
 If you find this module useful, you might also want to look at my tools for [creating and managing custom type extensions](https://github.com/jdhitsolutions/PSTypeExtensionTools), [managing scheduled jobs](https://github.com/jdhitsolutions/ScheduledJobTools) and [running remote commands outside of PowerShell Remoting](https://github.com/jdhitsolutions/PSRemoteOperations).
@@ -1483,4 +1571,4 @@ If you find this module useful, you might also want to look at my tools for [cre
 
 Where possible these commands have been tested with PowerShell 7, but not every platform. If you encounter problems, have suggestions or other feedback, please post an [issue](https://github.com/jdhitsolutions/PSScriptTools/issues). It is assumed you will __not__ be running this commands on any edition of PowerShell Core or any beta releases of PowerShell 7.
 
-> Last Updated *2020-05-14 18:42:52Z UTC*
+> Last Updated *2020-05-21 20:11:54Z UTC*

README.md

@@ -1,11 +1,43 @@
 # Change Log for PSScriptTools
 
+## v2.24.0
+
+### Add
+
++ Added parameter alias of `tb` for `-TextBlock` in `Add-Border`.
++ Added parameter alias of `border` for `-Character` in `Add-Border`.
++ Added `New-ANSIBar` command.
++ Added `New-RedGreenGradient` command.
++ Added `Write-ANSIProgress` command with an alias of `wap`.
++ Defined a global variable called `$PSSpecialChar` which is a hash table select special characters you might want to use with `Add-Border` or `New-AnsiBar`.
++ Added a table view to `modulecommand.format.ps1xml` and made it the default.
++ Added a new table view called `verb` to `modulecommand.format.ps1xml`.
++ Added `Get-PathVariable` with its own custom format file. (Issue #74)
++ Added sample script `Get-Status.ps1`.
++ Added global variable `$PSSamplePath` to point to the sample script location
+
+### Change
+
++ Modified `Add-Border` to adjust line length when ANSI escapes are part of the text. (Issue #79)
++ Modified `Get-PSWho` to trim when using `-AsString`.
++ Fixed bug in `New-PSFormatXML` what was writing an XML element to the pipeline when using `-Wrap`.
++ Updated `Get-ModuleCommand` output to include the module name.
++ Updated `serviceansi.format.ps1xml` and `filesystem-ansi.format.ps1xml` to use an escape sequence available to both Windows PowerShell and PowerShell 7.
++ Fixed wrong type name in `serviceansi.format.ps1xml`.
++ Help updates.
++ Updated sample scripts.
++ Updated `README.md`.
+
+### Delete
+
++ Removed duplicate line of code in `New-PSFormatXML`.
+
 ## v2.23.0
 
 + Updated `New-PSFormatXML` to include an option to wrap tables. (Issue #78)
 + Updated `Add-Border` to include parameters to specify an ANSI sequence for the border and one for the text.
 + Revised `Add-Border` to better support inserting blank lines.
-+ Updated `README.md`
++ Updated `README.md`.
 
 ## v2.22.0
 

changelog.md

@@ -98,6 +98,28 @@ PS C:\> add-border -Text $t -ANSIBorder "$([char]0x1b)[38;5;47m" -ANSIText "$([c
 
 This will write a color version of the text and border. You would this type of ANSI syntax for Windows PowerShell. In PowerShell 7, you can use the same syntax or the much easier "`e[38;5;47m".
 
+### EXAMPLE 6
+
+```powershell
+PS C:\scripts> add-border -textblock (Get-PSWho -AsString ).trim() -ANSIBorder "`e[38;5;214m" -Character ([char]0x25CA) -ANSIText "`e[38;5;225m"
+
+◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊
+◊ User            : BOVINE320\Jeff                    ◊
+◊ Elevated        : True                              ◊
+◊ Computername    : BOVINE320                         ◊
+◊ OperatingSystem : Microsoft Windows 10 Pro [64-bit] ◊
+◊ OSVersion       : 10.0.18363                        ◊
+◊ PSVersion       : 7.0.1                             ◊
+◊ Edition         : Core                              ◊
+◊ PSHost          : ConsoleHost                       ◊
+◊ WSMan           : 3.0                               ◊
+◊ ExecutionPolicy : RemoteSigned                      ◊
+◊ Culture         : English (United States)           ◊
+◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊
+```
+
+This example requires PowerShell 7 because of the escape sequence.
+
 ## PARAMETERS
 
 ### -Text
@@ -123,7 +145,7 @@ A multi-line block of text. You might want to trim blank lines from the beginnin
 ```yaml
 Type: String[]
 Parameter Sets: block
-Aliases:
+Aliases: tb
 
 Required: True
 Position: 1
@@ -139,7 +161,7 @@ The character to use for the border. It must be a single character.
 ```yaml
 Type: String
 Parameter Sets: (All)
-Aliases:
+Aliases: border
 
 Required: False
 Position: Named