From a233e04eb372c52ce130a255ec2bfb1b1d4506df Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 29 Aug 2024 14:48:48 -0500 Subject: [PATCH] Add cmdlet documentation --- docs/Compare-Text.md | 121 ++++++++++ docs/ConvertFrom-Base64.md | 120 ++++++++++ docs/ConvertFrom-TextTable.md | 290 +++++++++++++++++++++++ docs/ConvertTo-Base64.md | 171 +++++++++++++ docs/Microsoft.PowerShell.TextUtility.md | 32 +++ 5 files changed, 734 insertions(+) create mode 100644 docs/Compare-Text.md create mode 100644 docs/ConvertFrom-Base64.md create mode 100644 docs/ConvertFrom-TextTable.md create mode 100644 docs/ConvertTo-Base64.md create mode 100644 docs/Microsoft.PowerShell.TextUtility.md diff --git a/docs/Compare-Text.md b/docs/Compare-Text.md new file mode 100644 index 0000000..aa423ac --- /dev/null +++ b/docs/Compare-Text.md @@ -0,0 +1,121 @@ +--- +external help file: Microsoft.PowerShell.TextUtility.dll-Help.xml +Module Name: Microsoft.PowerShell.TextUtility +online version: +ms.date: 08/29/2024 +schema: 2.0.0 +--- + +# Compare-Text + +## SYNOPSIS + +This cmdlet compares two text strings using diff-match-patch. + +## SYNTAX + +``` +Compare-Text [-LeftText] [-RightText] [-View ] + [] +``` + +## DESCRIPTION + +This cmdlet compares two text strings using the **diff-match-patch** library. + +The [diff-match-patch](https://github.com/google/diff-match-patch) library provides methods used for +synchronizing plain text, similar to the diff functions of `git`. + +## EXAMPLES + +### Example 1 - Compare two multiline strings + +This example shows how to compare two multiline strings using the `Compare-Text` cmdlet. The cmdlet +uses ANSI escape codes to highlight the differences between the two strings. + +```powershell +$leftText = @("This is some", "example text.") -join [Environment]::NewLine +$rightText = @(" This is other", "example text used!") -join [Environment]::NewLine +Compare-Text -LeftText $leftText -RightText $rightText -View SideBySide +``` + +```Output +1 | This is some | This is other +2 | example text. | example text… +``` + +This example output shows the differences in red with strikethrough characters on the left and +additions in green on the right. + +## PARAMETERS + +### -LeftText + +The source string to be compared. This can be a single line or a multiline string. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RightText + +The difference string to be compared. This can be a single line or a multiline string. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -View + +The view mode to display the comparison. The possible values are: + +- `Inline` - (Default) Shows the differences, side-by-side on the same line. +- `SideBySide` - Shows the differences, side-by-side in separate columns. + +```yaml +Type: Microsoft.PowerShell.TextUtility.CompareTextView +Parameter Sets: (All) +Aliases: +Accepted values: Inline, SideBySide + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.PowerShell.TextUtility.CompareTextDiff + +## NOTES + +## RELATED LINKS diff --git a/docs/ConvertFrom-Base64.md b/docs/ConvertFrom-Base64.md new file mode 100644 index 0000000..49f6c3f --- /dev/null +++ b/docs/ConvertFrom-Base64.md @@ -0,0 +1,120 @@ +--- +external help file: Microsoft.PowerShell.TextUtility.dll-Help.xml +Module Name: Microsoft.PowerShell.TextUtility +online version: +ms.date: 08/29/2024 +schema: 2.0.0 +--- + +# ConvertFrom-Base64 + +## SYNOPSIS + +Converts a Base64-encoded string back to its original form. + +## SYNTAX + +``` +ConvertFrom-Base64 [-EncodedText] [-AsByteArray] [] +``` + +## DESCRIPTION + +The command converts a Base64-encoded string back to its original form. The original form can be a +string or any arbitrary binary data. + +## EXAMPLES + +### Example 1 - Convert a Base64-encoded string to its original form + +```powershell +ConvertFrom-Base64 -EncodedText "SGVsbG8gV29ybGQh" +``` + +```output +Hello World! +``` + +### Example 1 - Convert a Base64-encoded string to its original form as a byte array + +```powershell +ConvertFrom-Base64 -EncodedText "SGVsbG8gV29ybGQh" -AsByteArray +``` + +```output +72 +101 +108 +108 +111 +32 +87 +111 +114 +108 +100 +33 +``` + +## PARAMETERS + +### -AsByteArray + +Returns the converted output as an array of bytes. This is useful when the original form is binary +data. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -EncodedText + +The Base64-encoded string to convert back to its original form. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### System.String + +By default, this command returns the converted data as a string. + +### System.Byte + +When you use the **AsByteArray** parameter, this command returns the converted data as an array of +bytes. + +## NOTES + +## RELATED LINKS + +[ConvertTo-Base64](ConvertTo-Base64.md) diff --git a/docs/ConvertFrom-TextTable.md b/docs/ConvertFrom-TextTable.md new file mode 100644 index 0000000..9f3b5e5 --- /dev/null +++ b/docs/ConvertFrom-TextTable.md @@ -0,0 +1,290 @@ +--- +external help file: Microsoft.PowerShell.TextUtility.dll-Help.xml +Module Name: Microsoft.PowerShell.TextUtility +online version: +ms.date: 08/29/2024 +schema: 2.0.0 +--- + +# ConvertFrom-TextTable + +## SYNOPSIS + +Converts tabular data to a **PSObject**. + +## SYNTAX + +``` +ConvertFrom-TextTable [-MaximumWidth ] [-AnalyzeRowCount ] [-Line] + [-Skip ] [-NoHeader] [-AsJson] [-ColumnOffset ] [-ConvertPropertyValue] + [-HeaderLine ] [-TypeName ] [] +``` + +## DESCRIPTION + +This command converts text data that is formatted as a table into a custom **PSObject**. The command +analyzes the input text to determine the column layout. The command can also accept an array of +column offsets to define the column layout. + +## EXAMPLES + +### Example 1 - Convert the output of `getmac.exe` to a **PSObject** + +The `getmac.exe` command outputs the MAC addresses of the network adapters. This example converts +the output to a **PSObject**. The `Where-Object` cmdlet filters out the separates the header from +the data. + +```powershell +getmac.exe | ConvertFrom-TextTable | Where-Object Physical_Address -NotMatch '===========' +``` + +```Output +Physical_Address Transport_Name +---------------- -------------- +A4-AE-11-11-6A-B4 \Device\Tcpip_{1437A0C9-2898-450E-B49D-72B7D5946E21} +00-1A-7D-DA-71-13 Media disconnected +Disabled Disconnected +``` + +### Example 2 - Convert the output of `getmac.exe` to a JSON string + +The `getmac.exe` command outputs the MAC addresses of the network adapters. This example converts +the output to a **PSObject**. The `Where-Object` cmdlet filters out the separates the header from +the data. + +```powershell +getmac.exe | ConvertFrom-TextTable -AsJson +``` + +```Output +{ "Physical_Address": "===================", "Transport_Name": "==========================================================" } +{ "Physical_Address": "A4-AE-11-11-6A-B4", "Transport_Name": "\\Device\\Tcpip_{1437A0C9-2898-450E-B49D-72B7D5946E21}" } +{ "Physical_Address": "00-1A-7D-DA-71-13", "Transport_Name": "Media disconnected" } +{ "Physical_Address": "Disabled", "Transport_Name": "Disconnected" } +``` + +Each row of the table is deserialized to a separate JSON object. + +### Example 3 - Convert a table with non-string data values + +This example converts the output of the `dir` from the Windows Command Shell to a **PSObject**. The +`Where-Object` cmdlet is used to filter out only the lines that contain data values. Using the +**ColumnOffset** parameter, `ConvertFrom-TextTable` splits the rows into columns at the specified +offsets. The **ConvertPropertyValue** parameter is used to convert the property values to the types +other than strings. + +```powershell +$object = cmd /c dir | + Where-Object {$_ -match '\d{2}:\d{2}'} | + ConvertFrom-TextTable -NoHeader -ConvertPropertyValue -ColumnOffset 0,24,30,39 +$object[3] | Get-Member +``` + +```Output + TypeName: System.Management.Automation.PSCustomObject + +Name MemberType Definition +---- ---------- ---------- +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +ToString Method string ToString() +Property_01 NoteProperty datetime Property_01=8/29/2024 10:08:00 AM +Property_02 NoteProperty int Property_02=0 +Property_03 NoteProperty int Property_03=2323 +Property_04 NoteProperty string Property_04=ConvertFrom-Base64.md +``` + +## PARAMETERS + +### -AnalyzeRowCount + +The maximum number of rows of input to analyze before deciding on the column layout. The default +value is 0, which means that all rows are analyzed. For large data sets, use a non-zero value to +speed up the analysis. + +```yaml +Type: System.Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AsJson + +Outputs the result as a JSON string. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ColumnOffset + +An array of integers that specify the column offset for each column. When provided, the command +splits the rows into columns at the column offset values, rather than doing analysis. + +```yaml +Type: System.Int32[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ConvertPropertyValue + +When this parameter is specified, the command attempts to convert the property values to one of the +data types: int, int64, decimal, datetime, or timespan. Values that can't be converted are returned +as strings. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -HeaderLine + +Specifies the line number to use as the header. The default is 0 (the first line). + +```yaml +Type: System.Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Line + +A string array that contains the text table to be converted. + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -MaximumWidth + +The maximum width of the tabular text to be converted. The default is 200 characters. + +```yaml +Type: System.Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 200 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoHeader + +Specifies that the input text has no header row. The command generates column names as +`Property_01`, `Property_02`, and so on. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TypeName + +Adds the type name to **TypesNames** property of the resulting object. If you provide more than one +type name, the names are inserted in reverse order, putting the last type name at the beginning of +list. + +Adding type a custom type name allows you to create type-specific formatting for the object output. + +```yaml +Type: System.String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Skip + +Ignores the specified number of objects and then gets the remaining objects. +Enter the number of objects to skip. The default is 0. + +```yaml +Type: System.Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String[] + +You can pipe table-formatted text to the command. + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS diff --git a/docs/ConvertTo-Base64.md b/docs/ConvertTo-Base64.md new file mode 100644 index 0000000..e0e1db7 --- /dev/null +++ b/docs/ConvertTo-Base64.md @@ -0,0 +1,171 @@ +--- +external help file: Microsoft.PowerShell.TextUtility.dll-Help.xml +Module Name: Microsoft.PowerShell.TextUtility +online version: +ms.date: 08/29/2024 +schema: 2.0.0 +--- + +# ConvertTo-Base64 + +## SYNOPSIS + +Converts the input object to a Base64-encoded string. + +## SYNTAX + +### Text (Default) + +``` +ConvertTo-Base64 [-Text] [-InsertBreakLines] [] +``` + +### ByteArray + +``` +ConvertTo-Base64 [-ByteArray] [-InsertBreakLines] [] +``` + +## DESCRIPTION + +This command converts a string or an array of bytes to a Base64-encoded string. + +## EXAMPLES + +### Example 1 - Convert a plaintext string to a Base64-encoded string + +This examples shows the plaintext string used for Basic authentication in an HTTP request. + +```powershell +ConvertTo-Base64 -Text 'Basic Username:Password' +``` + +```Output +QmFzaWMgVXNlcm5hbWU6UGFzc3dvcmQ= +``` + +### Example 2 - Convert a binary file to a Base64-encoded string + +This example converts the contents of a binary file to a Base64-encoded string. When you use the +**Raw**, `Get-Content` reads the content as byte data rather than strings. The **AsByteStream** +parameter write the data to the pipeline as a singe continuous stream of bytes. When the data is +converted to a Base64-encoded string, the **InsertBreakLines** parameter adds line breaks output +into 77-character lines. + +```powershell +Get-Content -AsByteStream -Raw icon.png | ConvertTo-Base64 -InsertBreakLines +``` + +```Output +iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJ +bWFnZVJlYWR5ccllPAAAAyRpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdp +bj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6 +eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0 +NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJo +dHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlw +dGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAv +IiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RS +ZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpD +cmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNiAoTWFjaW50b3NoKSIgeG1wTU06SW5zdGFu +Y2VJRD0ieG1wLmlpZDpFNTE3OEEyQTk5QTAxMUUyOUExNUJDMTA0NkE4OTA0RCIgeG1wTU06RG9j +dW1lbnRJRD0ieG1wLmRpZDpFNTE3OEEyQjk5QTAxMUUyOUExNUJDMTA0NkE4OTA0RCI+IDx4bXBN +TTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAuaWlkOkU1MTc4QTI4OTlBMDExRTI5 +QTE1QkMxMDQ2QTg5MDREIiBzdFJlZjpkb2N1bWVudElEPSJ4bXAuZGlkOkU1MTc4QTI5OTlBMDEx +RTI5QTE1QkMxMDQ2QTg5MDREIi8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4 +bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+m4QGuQAAAyRJREFUeNrEl21ojWEYx895TDPbMNlB +K46IUiNmPvHBSUjaqc0H8pF5+aDUKPEBqU2NhRQpX5Rv5jWlDIWlMCv7MMSWsWwmb3tpXub4XXWd +PHvc9/Gc41nu+nedc7/8r/99PffLdYdDPsvkwsgkTBwsA/PADJCnzX2gHTwBt8Hl7p537/3whn04 +XoDZDcpBlk+9P8AFcAghzRkJwPF4zGGw0Y9QS0mAM2AnQj77FqCzrtcwB1Hk81SYojHK4DyGuQ6m +hIIrBWB9Xm7ug/6B/nZrBHBegrkFxoVGpnwBMSLR9EcEcC4qb8pP14BWcBcUgewMnF3T34VqhWMF +kThLJAalwnENOAKiHpJq1FZgI2AT6HZtuxZwR9GidSHtI30jOrbawxlVX78/AbNfhHlomEUJJI89 +O2MqeE79T8/nk8nMBm/dK576hZgmA3cp/R4l9/UeSxiHLVIlNm4nFfT0bxyuIj7LHRTKai+zdJob +wMKzcZSJb0ePV5PKN+BqAAKE47UlMnERELMM3EdYP/yrd+XYb2mOiYBiQ8OQnoRBlXrl9JZix7D1 +pHTazu4MoyBcnYamqAjIMTR8G4FT8LuhLsexXYYjICBiqhQBvYb6fLZIJCjPypVvaOoVAW2WcasC +nL2Nq82xHJNSqlCeFcDshaPK0twkAhosjZL31QYw+1rlMpWGMArl23SBsZZO58F2tlJXmjOXS+s4 +WGvpMiBJT/I2PInZ6lIs9/hBsNS1hS6BG0DSqmYEDRlCXQrmy50P1oDRKTSegmNbUsA0zDMwRhPJ +XeCE3vWLPQMvan6X8AgIa1vcR4AkGZkDR4ejJ1UHpsaVI0g2LInpOsNFUud1rhxSV+fzC9Woz2EZ +kWQuja7/B+jUrgtIMpy9YCW4n4K41YfzRneW5E1KJTe4B2Zq1Q5EHEtj4U3AfEzR5SVY4l7QYQPJ +dN2as7RKBF0BPZqqH4VgMAMBL8Byxr7y8zCZiDlnOcEKIPmUpgB5Z2ww5RdOiiRiNajUmWda5IG6 +WbhsyY2fx6m8gLcoJDJFkH219M3We1+cnda93pfycZpIJEL/s/wSYADmOAwAQgdpBAAAAABJRU5E +rkJggg== +``` + +## PARAMETERS + +### -ByteArray + +An array of bytes to convert to a Base64-encoded string. Use this parameter to convert binary data. + +```yaml +Type: System.Byte[] +Parameter Sets: ByteArray +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -InsertBreakLines + +Limits the length of the output lines to 77 characters. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Text + +The string to convert to a Base64-encoded string. + +```yaml +Type: System.String +Parameter Sets: Text +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +You can pipe strings to this command. Each string in the pipeline is converted to a separate +Base64-encoded string. + +### System.Byte[] + +You can pipe binary data as a stream of bytes to this command. + +## OUTPUTS + +### System.String + +The Base64-encoded string. + +## NOTES + +## RELATED LINKS + +[ConvertFrom-Base64](ConvertFrom-Base64.md) diff --git a/docs/Microsoft.PowerShell.TextUtility.md b/docs/Microsoft.PowerShell.TextUtility.md new file mode 100644 index 0000000..cce5022 --- /dev/null +++ b/docs/Microsoft.PowerShell.TextUtility.md @@ -0,0 +1,32 @@ +--- +Module Name: Microsoft.PowerShell.TextUtility +Module Guid: 5cb64356-cd04-4a18-90a4-fa4072126155 +Download Help Link: '' +Help Version: 1.0.0.0 +ms.date: 08/29/2024 +Locale: en-US +--- + +# Microsoft.PowerShell.TextUtility Module + +## Description + +This module is a collection of cmdlets for working with text content. + +## Microsoft.PowerShell.TextUtility Cmdlets + +### [Compare-Text](Compare-Text.md) + +This cmdlet compares two text strings using diff-match-patch. + +### [ConvertFrom-Base64](ConvertFrom-Base64.md) + +Converts a Base64-encoded string back to its original form. + +### [ConvertFrom-TextTable](ConvertFrom-TextTable.md) + +Converts tabular data to a **PSObject**. + +### [ConvertTo-Base64](ConvertTo-Base64.md) + +Converts the input object to a Base64-encoded string.