v2.32.0

Author: jdhitsolutions

Archive-ChangeLog.md

@@ -1,5 +1,143 @@
 # Archived ChangeLog for PSScriptTools
 
+This file contains older change history. It is maintained for reference purposes.
+
+## v2.29.0
+
++ Modified `Get-WindowsVersion` to not use remoting when connecting to the local computer. (Issue #90)
++ Updated help documentation for `Get-WindowsVersion` and `Get-WindowsVersionString`.
++ Added command `Copy-PSFunction` with an alias of `cpfun`.
+
+## v2.28.0
+
++ Added `Compare-Script` thanks to @cohdjn.
++ Added `Get-PSProfile` and a related formatting file, `psprofilepath.format.ps1xml`.
++ Updated `README.md`.
+
+## v2.27.0
+
++ Added a new command called `Get-MyAlias` with an alias of `gma`.
++ Added a custom formatting file for alias objects with new views of `Options` and `Source`.
++ Revised the help PDF to include command help.
++ Help documentation cleanup.
++ Updated `README.md`
++ Fixed bug in `Test-Expression` that was importing the wrong module.
++ Modified `New-PSDriveHere` to not write the new PSDrive object to the pipeline. Added a `-Passthru` parameter. This is a BREAKING change to the command.
++ Modified `Get-ParameterInfo` to write a custom `PSParameterInfo` object to the pipeline and added a default list formatted view.
++ Modified `psscripttool.format.ps1xml` to display Verb in color using ANSI.
+
+## v2.26.2
+
++ Cleaned up bad links and code fence re-formatting in `README.md`.
++ Created new base version of `PSScriptToolsHelp.md`.
++ Generated a new help manual with a table of contents and nicer formatting. (Issue #87)
++ Renamed help pdf to `PSScriptToolsManual.pdf`.
+
+## v2.26.1
+
++ Replaced links in `PSScriptToolsHelp` (Issue #86)
++ Updated PDF style when exporting `PSScriptToolsHelp`
++ Removed Table of Contents from `PSScriptToolsHelp.md`. There is a bug when rendering to PDF that doesn't follow the relative links in the document. Hopefully I can add this back in the future.
++ Minor changes to `README.md`.
+
+## v2.26.0
+
++ Added a Documents type to `PSAnsiFileMap.json`.
++ Added a parameter to `Convert-HashtableToCode` to output an inline string. (Issue #85)
++ Added an alias `chc` for `Convert-HashtableToCode`.
++ Added `Copy-HelpExample` command with an alias of `che`.
++ Added `Open-PSScriptToolsHelp` to open a PDF version of `README.md` as a help manual.
++ Fixed duplicate entry in `PSAnsiFileMap.json`.
++ Revised regex patterns in `PSAnsiFileMap.json`. (Issue #83)
++ Cleaned up code in `filesystem-ansi.format.ps1xml`.
++ Modified `Convert-HashtableToCode` to (hopefully) better handle scriptblocks. (Issue #84)
++ Updated `README.md`
+
+## v2.25.1
+
++ Fixed incorrect sequence for BlackRectangle in `$PSSpecialChar`. (Issue #82)
++ Fixed incorrect ANSI for System files in `PSAnsiFileMap.json`.
+
+## v2.25.0
+
++ Added a set of ANSI mappings for temporary files and system files in `psansifilemap.json`.
++ Added additional file extensions to `psansifilemap.json`.
++ Added pointers, section sign, and black rectangle to PSSpecialChars hashtable.
++ Modified `Show-Tree` to make the `InColor` parameter always available. (Issue #80)
++ Modified `Add-Border` to use ANSI escape codes that will work in both Windows PowerShell and PowerShell 7.
++ Updated `New-PSFormatXML` to better handle empty or null property values. (Issue #81)
++ Help Updates
+
+## v2.24.0
+
++ 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
++ 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`.
++ 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`.
+
+## v2.22.0
+
++ Modified `Set-ConsoleTitle` to move parameter validation into the `Process` script block. (Issue #75)
++ Modified `Get-FolderSizeInfo` to fix an enumeration bug when used in Windows PowerShell. (Issue #77)
++ Added online help links for `Get-GitSize`, `Get-ModuleCommand` and `Remove-MergedBranch`.
++ Updated `foldersizeinfo.format.ps1xml` to include a view called `TB` to display values in TB.
+
+## v2.21.0
+
++ Updated `Set-ConsoleTitle` and `Set-ConsoleColor` to display a warning if not in a console session. (Issue #75)
++ Added `Get-GitSize` and format file `gitsize.format.ps1xml`
++ Added a default ANSI color map file `psansimap.json`.
++ Modified module to use a copy of `psansimap.json` in $HOME if detected. Otherwise, use the module's version.
++ Create a global variable called `PSAnsiFileMap` from importing the `psansimap.json` file.
++ Updated `Show-Tree` to use an ANSI color map. (Issue #69)
++ Added `FileSystem-ansi.format.ps1xml` which adds a custom view called `ansi`. This colorizes files based on `$PSAnsiMap`.
++ Updated `Show-Tree` to resolve child paths using `-LiteralPath`.
++ Updated `README.md`
+
+## v2.20.0
+
++ Restructured `Get-FileSizeInfo` to better handle Windows PowerShell. (Issue #70)
++ Added `Remove-MergedBranch` with an alias of `rmb`. (Issue #71)
++ Added `Get-ModuleCommand` with an alias of `gmc`.
++ Added `modulecommand.format.ps1xml` to format `Get-ModuleCommand` results.
++ Added an alias of `shtree` for `Show-Tree` because `pstree` is a Linux command.
++ Added parameter alias `files` for `-ShowItem` in `Show-Tree`.
++ Added parameter alias `properties` for `-ShowProperties` in `Show-Tree`.
++ Added parameter alias `ansi` for dynamic parameter `InColor` in `Show-Tree`. (Issue #73)
++ Set the default parameter value for `-Path` in `Show-Tree` to the current directory.
++ Modified `Show-Tree` to allow the user to specify an array of properties. This is a __breaking change__ as the parameter has been changed from a `switch` to `string[]`. (Issue #72)
++ Removed `PROPERTY` label in `Show-Tree` output when displaying properties.
++ Corrected errors in the module manifest.
++ Added auto completer for `Runspace` parameter in `Remove-Runspace`.
++ Added alias `rfn` for `New-RandomFileName`.
++ Added alias `cfn` for `New-CustomFileName`.
++ Updated `README.md`.
++ `ChangeLog.md` clean up.
+
 ## v2.19.0
 
 + Modified `Get-FolderSizeInfo` to use [system.collections.arraylist]` to improve performance. (Issue #68)

PSScriptTools.psd1

@@ -96,16 +96,17 @@ elseif ($psise) {
     }
 }
 
-#define a function to open the PDF version of the README as a help file
-
+#define a function to open the PDF version of the README and other documentation
 Function Open-PSScriptToolsHelp {
     [cmdletbinding()]
     Param()
-
+    Write-Verbose "Starting $($myinvocation.mycommand)"
     $pdf = Join-Path -path $PSScriptRoot -ChildPath PSScriptToolsManual.pdf
+    Write-Verbose "Testing the path $pdf"
     if (Test-Path -Path $pdf) {
         Try {
-            Start-Process -FilePath $pdf -ErrorAction Stop
+            write-Verbose "Invoking the PDF"
+            Invoke-Item -Path $pdf -ErrorAction Stop
         }
         Catch {
             Write-Warning "Failed to automatically open the PDF. You will need to manually open $pdf."
@@ -114,4 +115,5 @@ Function Open-PSScriptToolsHelp {
     else {
         Write-Warning "Can't find $pdf."
     }
+    Write-Verbose "Ending $($myinvocation.MyCommand)"
 }

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 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. Please post any questions, problems or feedback in [Issues](https://github.com/jdhitsolutions/PSScriptTools/issues). Any feedback is greatly appreciated.
+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. Please post any questions, problems, or feedback in [Issues](https://github.com/jdhitsolutions/PSScriptTools/issues). Any feedback is greatly appreciated.
 
 *Please note that code samples have been formatted to fit an 80 character width. Some example code breaks lines without using line continuation characters. I'm trusting that you can figure out how to run the example.*
 
@@ -25,7 +25,7 @@ This module contains a collection of functions, variables and format files that
 
 ## Installation
 
-You can get the current release from this repository or install this the [PowerShell Gallery](https://powershellgallery.com):
+You can get the current release from this repository or install this from the [PowerShell Gallery](https://powershellgallery.com):
 
 ```powershell
 Install-Module PSScriptTools
@@ -37,7 +37,9 @@ or in PowerShell 7:
 Install-Module PSScriptTools [-scope CurrentUser] [-force]
 ```
 
-> Starting in v2.2.0, the module was restructured to better support `Desktop` and `Core` editions. But starting with version 2.13.0, the module design has reverted. All commands will be exported. Anything that is platform-specific should be handled on a per-command basis. It is assumed you will be running this module in Windows PowerShell 5.1 or PowerShell 7.
+Starting in v2.2.0, the module was restructured to better support `Desktop` and `Core` editions. However, starting with v2.13.0, the module design has reverted. All module commands will be exported. Anything that is platform-specific should be handled on a per-command basis. It is assumed you will be running this module in Windows PowerShell 5.1 or PowerShell 7.
+
+It is recommended to install this module from the PowerShell Gallery and not GitHub.
 
 ### Uninstall the Module
 
@@ -50,6 +52,20 @@ Uninstall-Module PSScriptTools -allversions
 
 ## General Tools
 
+### [Get-DirectoryInfo](docs/Get-DirectoryInfo.md)
+
+This command, which has an alias of *dw*, is designed to provide quick access to top-level directory information. The default behavior is to show the total number of files in the immediate directory. Although the command will also capture the total file size in the immediate directory. You can use the Depth parameter to recurse through a specified number of levels. The default displays use ANSI escape sequences.
+
+![Get-DirectoryInfo](images/dw-1.png)
+
+The command output will use a wide format by default. However, other wide views are available.
+
+![Get-DirectoryInfo MB](images/dw-2.png)
+
+You can use the object in other ways.
+
+![Get-DirectoryInfo table](images/dw-3.png)
+
 ### [Get-FormatView](docs/Get-FormatView.md)
 
 PowerShell's formatting system includes a number of custom views that display objects in different ways. Unfortunately, this information is not readily available to a typical PowerShell user. This command displays the available views for a given object type.
@@ -1177,6 +1193,53 @@ These functions were first described at [https://jdhitsolutions.com/blog/powersh
 
 ## Console Utilities
 
+### [ConvertTo-ASCIIArt](docs/ConvertTo-ASCIIArt.md)
+
+`ConvertTo-ASCIIArt` can be used to transform a string of text into ASCII art. It utilizes the web service at https://artii.herokuapp.com which allows you to transform text. You might use this to create headers for your scripts or PowerShell profile.
+
+![ConvertTo-ASCIIArt](images/cart.png)
+
+I used this command to convert a string that I'm using with `Get-PSScriptTools` to display a "splash" header.
+
+```powershell
+    $h = @"
+ ___ ___ ___        _      _  _____        _
+| _ \ __/ __|__ _ _(_)_ __| |__   _|__ ___| |___
+|  _\__ \__ \ _| '_| | '_ \  _|| |/ _ \ _ \ (_-<
+|_| |___/___\__|_| |_| .__/\__||_|\___\___/_/__/
+                     |_|
+"@
+    "$([char]0x1b)[1;38;5;177m$h$([char]0x1b)[0m" | Write-Host
+```
+
+![PSScriptTools Splash](images/psscripttools-splash.png)
+
+Expect a period of trial and error to find a good font that works with your text. The shorter your text, the better.
+
+### [Out-Copy](docs/Out-Copy.md)
+
+This command is intended for writers and those who need to document with PowerShell. You can pipe any command to this function and you will get the regular output in your PowerShell session.Simultaneously a copy of the output will be sent to the Windows clipboard. The copied output will include a prompt constructed from the current location unless you use the CommandOnly parameter.
+
+You can run this a command like this:
+
+```powershell
+Get-Process | Sort WS -Descending | Select -first 5 | Out-Copy
+```
+
+And this text will be copied to the clipboard.
+
+```text
+PS C:\> Get-Process | Sort WS -Descending | Select -first 5
+
+Handles  NPM(K)    PM(K)      WS(K)     CPU(s)     Id  SI ProcessName
+-------  ------    -----      -----     ------     --  -- -----------
+   1849     253   810320     820112     445.38  17860   1 firefox
+    765      61   949028     758200      23.36   6052   0 sqlservr
+    446     115   441860     471032      28.59  18204   1 Teams
+   2307     192   313204     459616     325.23  15748   1 firefox
+   2050     163   451744     433772      94.63  19780   1 thunderbird
+```
+
 ### [Out-More](docs/Out-More.md)
 
 This command provides a PowerShell alternative to the cmd.exe **MORE** command, which doesn't work in the PowerShell ISE. When you have screens of information, you can page it with this function.
@@ -1399,6 +1462,22 @@ TotalMemGB FreeMemGB PctFree
 
 ## Scripting Tools
 
+### [Get-CommandSyntax](docs/Get-CommandSyntax.md)
+
+Some PowerShell commands are provider aware and may have special syntax or parameters depending on what PSDrive you are using when you run the command. In Windows PowerShell, the help system could show you syntax based on a given path. However, this no longer appears to work. `Get-CommandSyntax` is intended as an alternative and should work in both Windows PowerShell and PowerShell 7.
+
+Specify a cmdlet or function name, and the output will display the syntax detected when using different providers.
+
+```powershell
+Get-CommandSyntax -Name Get-Item
+```
+
+Dynamic parameters will be highlighted with an ANSI-escape sequence.
+
+![Get-CommandSyntax](images/get-commandsyntax.png)
+
+This command has an alias of *gsyn*.
+
 ### [Test-Expression](docs/Test-Expression.md)
 
 The primary command can be used to test a PowerShell expression or scriptblock for a specified number of times and calculate the average runtime, in milliseconds, over all the tests.
@@ -1901,4 +1980,4 @@ If you find this module useful, you might also want to look at my PowerShell too
 
 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 these commands on any edition of PowerShell Core or any beta releases of PowerShell 7.
 
-Last Updated *2020-10-12 16:08:05Z*
+Last Updated *2020-10-26 19:37:54Z*