Merge pull request #22 from santisq/20-add-rename-zipentry-command

20 add rename zipentry command

CHANGELOG.md

@@ -0,0 +1,18 @@
+# 02/25/2024
+
+- `ZipEntryBase` Type:
+    - Renamed Property `EntryName` to `Name`.
+    - Renamed Property `EntryRelativePath` to `RelativePath`.
+    - Renamed Property `EntryType` to `Type`.
+    - Renamed Method `RemoveEntry()` to `Remove()`.
+    - Added Property `CompressionRatio`.
+- `ZipEntryFile` Type:
+    - Added Property `Extension`.
+    - Added Property `BaseName`.
+- `ZipEntryDirectory` Type:
+    - `.Name` Property now reflects the directory entries name instead of an empty string.
+- Added command `Rename-ZipEntry`.
+- `NormalizePath` Method:
+    - Moved from `[PSCompression.ZipEntryExtensions]::NormalizePath` to `[PSCompression.Extensions.PathExtensions]::NormalizePath`.
+- `Get-ZipEntry` command:
+    - Renamed Parameter `-EntryType` to `-Type`.

README.md

@@ -1,7 +1,7 @@
 <h1 align="center">PSCompression</h1>
 <div align="center">
-    <sub>Zip and GZip utilities for PowerShell</sub>
-    <br/><br/>
+<sub>Zip and GZip utilities for PowerShell</sub>
+<br/><br/>
 
 [![build](https://github.com/santisq/PSCompression/actions/workflows/ci.yml/badge.svg)](https://github.com/santisq/PSCompression/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/santisq/PSCompression/branch/main/graph/badge.svg)](https://codecov.io/gh/santisq/PSCompression)

build.ps1

@@ -59,7 +59,7 @@ end {
     $dotnetTools = @(dotnet tool list --global) -join "`n"
     if (-not $dotnetTools.Contains('coverlet.console')) {
         Write-Host 'Installing dotnet tool coverlet.console'
-        dotnet tool install --global coverlet.console
+        dotnet tool install --global coverlet.console --version 6.0.0
     }
 
     $invokeBuildSplat = @{

docs/en-US/Compress-GzipArchive.md

@@ -9,34 +9,55 @@ schema: 2.0.0
 
 ## SYNOPSIS
 
-Creates a Gzip compressed file from specified File Paths or input Bytes.
+Creates a Gzip compressed file from specified paths or input bytes.
 
 ## SYNTAX
 
 ### Path (Default)
 
 ```powershell
-Compress-GzipArchive [-Path] <String[]> [-Destination] <String> [-CompressionLevel <CompressionLevel>]
- [-Update] [-Force] [-PassThru] [<CommonParameters>]
+Compress-GzipArchive
+    [-Path] <String[]>
+    [-Destination] <String>
+    [-CompressionLevel <CompressionLevel>]
+    [-Update]
+    [-Force]
+    [-PassThru]
+    [<CommonParameters>]
 ```
 
 ### LiteralPath
 
 ```powershell
-Compress-GzipArchive -LiteralPath <String[]> [-Destination] <String> [-CompressionLevel <CompressionLevel>]
- [-Update] [-Force] [-PassThru] [<CommonParameters>]
+Compress-GzipArchive
+    -LiteralPath <String[]>
+    [-Destination] <String>
+    [-CompressionLevel <CompressionLevel>]
+    [-Update]
+    [-Force]
+    [-PassThru]
+    [<CommonParameters>]
 ```
 
 ### InputBytes
 
 ```powershell
-Compress-GzipArchive -InputBytes <Byte[]> [-Destination] <String> [-CompressionLevel <CompressionLevel>]
- [-Update] [-Force] [-PassThru] [<CommonParameters>]
+Compress-GzipArchive
+    -InputBytes <Byte[]>
+    [-Destination] <String>
+    [-CompressionLevel <CompressionLevel>]
+    [-Update]
+    [-Force]
+    [-PassThru]
+    [<CommonParameters>]
 ```
 
 ## DESCRIPTION
 
-The `Compress-GzipArchive` cmdlet can compress one or more specified file paths into a single Gzip archive using the [`GzipStream` Class](https://learn.microsoft.com/en-us/dotnet/api/system.io.compression.gzipstream). For expansion see [`Expand-GzipArchive`](Expand-ZipEntry.md).
+The `Compress-GzipArchive` cmdlet can compress one or more specified file paths into a single Gzip archive using the [`GzipStream` Class](https://learn.microsoft.com/en-us/dotnet/api/system.io.compression.gzipstream).
+
+> [!TIP]
+> For expansion see [`Expand-GzipArchive`](Expand-ZipEntry.md).
 
 ## EXAMPLES
 
@@ -93,7 +114,8 @@ PS ..\pwsh> (Compress-GzipArchive .\files\lorem*.txt -Destination .\files\merged
 27.6982421875
 ```
 
-Due to the nature of Gzip without Tar, all file contents are merged into a single file.
+> [!NOTE]
+> Due to the nature of Gzip without Tar, all file contents are merged into a single file.
 
 ## PARAMETERS
 
@@ -117,9 +139,12 @@ Accept wildcard characters: False
 
 ### -Destination
 
-The path where to store the Gzip compressed file. The parent directory is created if it does not exist.
+The path where to store the Gzip compressed file.
 
-> __NOTE:__ If the path does not end with `.gz`, the cmdlet appends the `.gz` file name extension.
+> [!NOTE]
+>
+> - The parent directory is created if it does not exist.
+> - If the path does not have an extension, the cmdlet appends the `.gz` file name extension.
 
 ```yaml
 Type: String
@@ -137,7 +162,8 @@ Accept wildcard characters: False
 
 Overwrites the Gzip archive if exists, otherwise it creates it.
 
-> __NOTE:__ If `-Force` and `-Update` are used together this cmdlet will append content to the destination file.
+> [!NOTE]
+> If `-Force` and `-Update` are used together this cmdlet will append content to the destination file.
 
 ```yaml
 Type: SwitchParameter
@@ -155,7 +181,8 @@ Accept wildcard characters: False
 
 This cmdlet can take input bytes from pipeline to create the output `.gz` archive file.
 
-> __NOTE:__ This parameter is meant to be used exclusively in combination with `ConvertTo-GzipString -AsByteStream`.
+> [!NOTE]
+> This parameter is meant to be used exclusively in combination with [`ConvertTo-GzipString -AsByteStream`](./ConvertTo-GzipString.md#example-2-create-a-gzip-compressed-file-from-a-string).
 
 ```yaml
 Type: Byte[]
@@ -227,7 +254,8 @@ Accept wildcard characters: True
 
 Appends content to the existing Gzip file if exists, otherwise it creates it.
 
-> __NOTE:__ If `-Force` and `-Update` are used together this cmdlet will append content to the destination file.
+> [!NOTE]
+> If `-Force` and `-Update` are used together this cmdlet will append content to the destination file.
 
 ```yaml
 Type: SwitchParameter

docs/en-US/Compress-ZipArchive.md

@@ -16,15 +16,27 @@ The `Compress-ZipArchive` cmdlet creates a compressed, or zipped, archive file f
 ### Path
 
 ```powershell
-Compress-ZipArchive [-Path] <String[]> -Destination <String> [-CompressionLevel <CompressionLevel>] [-Update]
- [-Force] [-PassThru] [<CommonParameters>]
+Compress-ZipArchive
+    [-Path] <String[]>
+    -Destination <String>
+    [-CompressionLevel <CompressionLevel>]
+    [-Update]
+    [-Force]
+    [-PassThru]
+    [<CommonParameters>]
 ```
 
 ### LiteralPath
 
 ```powershell
-Compress-ZipArchive -LiteralPath <String[]> -Destination <String> [-CompressionLevel <CompressionLevel>]
- [-Update] [-Force] [-PassThru] [<CommonParameters>]
+Compress-ZipArchive
+    -LiteralPath <String[]>
+    -Destination <String>
+    [-CompressionLevel <CompressionLevel>]
+    [-Update]
+    [-Force]
+    [-PassThru]
+    [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -33,13 +45,15 @@ PowerShell cmdlet that overcomes the limitation that the built-in cmdlet `Compre
 
 > The `Compress-Archive` cmdlet uses the Microsoft .NET API [`System.IO.Compression.ZipArchive`](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.ziparchive?view=net-6.0) to compress files. The maximum file size is 2 GB because there's a limitation of the underlying API.
 
-The easy workaround would be to use the [`ZipFile.CreateFromDirectory` Method](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.zipfile.createfromdirectory?view=net-6.0#system-io-compression-zipfile-createfromdirectory(system-string-system-string)). However, there are 3 limitations while using this static method:
+The easy workaround would be to use the [`ZipFile.CreateFromDirectory` Method](https://docs.microsoft.com/en-us/dotnet/api/system.io.compression.zipfile.createfromdirectory?view=net-6.0#system-io-compression-zipfile-createfromdirectory(system-string-system-string)).
+
+However, there are 3 limitations while using this method:
 
    1. The source __must be a directory__, a single file cannot be compressed.
    2. All files (recursively) on the source folder __will be compressed__, we can't pick / filter files to compress.
    3. It's not possible to __Update__ the entries of an existing Zip Archive.
 
-This function should be able to handle compression same as `ZipFile.CreateFromDirectory` Method but also allow filtering files and folders to compress while keeping the __file / folder structure untouched__.
+This cmdlet should be able to handle compression same as `ZipFile.CreateFromDirectory` Method but also allow filtering files and folders to compress while keeping the __file / folder structure untouched__.
 
 ## EXAMPLES
 
@@ -100,11 +114,12 @@ Specifies the path or paths to the files that you want to add to the archive zip
 
 This parameter accepts wildcard characters. Wildcard characters allow you to add all files in a directory to your archive file.
 
-Using wildcards with a root directory affects the archive's contents:
-
-  - To create an archive that includes the root directory, and all its files and subdirectories, specify the root directory in the Path without wildcards. For example: `-Path C:\Reference`
-  - To create an archive that excludes the root directory, but zips all its files and subdirectories, use the asterisk (`*`) wildcard. For example: `-Path C:\Reference\*`
-  - To create an archive that only zips the files in the root directory, use the star-dot-star (`*.*`) wildcard. Subdirectories of the root aren't included in the archive. For example: `-Path C:\Reference\*.*`
+> [!TIP]
+> Using wildcards with a root directory affects the archive's contents:
+>
+>  - To create an archive that includes the root directory, and all its files and subdirectories, specify the root directory in the Path without wildcards. For example: `-Path C:\Reference`
+>  - To create an archive that excludes the root directory, but zips all its files and subdirectories, use the asterisk (`*`) wildcard. For example: `-Path C:\Reference\*`
+>  - To create an archive that only zips the files in the root directory, use the star-dot-star (`*.*`) wildcard. Subdirectories of the root aren't included in the archive. For example: `-Path C:\Reference\*.*`
 
 ```yaml
 Type: String[]
@@ -138,9 +153,10 @@ Accept wildcard characters: False
 
 ### -Destination
 
-This parameter is required and specifies the path to the archive output file. The DestinationPath should include the name of the zipped file, and either the absolute or relative path to the zipped file.
+This parameter is required and specifies the path to the archive output file. The destination should include the name of the zipped file, and either the absolute or relative path to the zipped file.
 
-If the file name in DestinationPath doesn't have a `.zip` file name extension, the cmdlet adds the `.zip` file name extension.
+> [!NOTE]
+> If the file name does not have an extension, the cmdlet appends the `.zip` file name extension.
 
 ```yaml
 Type: String
@@ -173,9 +189,10 @@ Accept wildcard characters: False
 
 ### -Update
 
-Updates the specified archive by replacing older file versions in the archive with newer file versions that have the same names. You can also add this parameter to add files to an existing archive.
+Updates the specified archive by replacing older file versions in the archive with newer file versions that have the same names. You can also use this parameter to add files to an existing archive.
 
-> __NOTE:__ If `-Force` and `-Update` are used together this cmdlet will add or update entries.
+> [!NOTE]
+> If `-Force` and `-Update` are used together this cmdlet will add or update entries.
 
 ```yaml
 Type: SwitchParameter
@@ -193,7 +210,8 @@ Accept wildcard characters: False
 
 Overwrites the destination archive if exists otherwise it creates a new one. All Zip entries are lost.
 
-> __NOTE:__ If `-Force` and `-Update` are used together this cmdlet will add or update entries.
+> [!NOTE]
+> If `-Force` and `-Update` are used together this cmdlet will add or update entries.
 
 ```yaml
 Type: SwitchParameter
@@ -245,4 +263,4 @@ When the `-PassThru` switch is used this cmdlet outputs the `FileInfo` instance
 
 ## NOTES
 
-This function was initially posted to address [this Stack Overflow question](https://stackoverflow.com/a/72611161/15339544). [Another question](https://stackoverflow.com/q/74129754/15339544) in the same site pointed out another limitation with the native cmdlet, it can't compress if another process has a handle on a file. To overcome this issue, and also to emulate explorer's behavior when compressing files used by another process, the function posted below will default to __[`[FileShare] 'ReadWrite, Delete'`](https://learn.microsoft.com/en-us/dotnet/api/system.io.fileshare?view=net-6.0)__ when opening a [`FileStream`](https://learn.microsoft.com/en-us/dotnet/api/system.io.file.open?view=net-7.0).
+This cmdlet was initially posted to address [this Stack Overflow question](https://stackoverflow.com/a/72611161/15339544). [Another question](https://stackoverflow.com/q/74129754/15339544) in the same site pointed out another limitation with the native cmdlet, it can't compress if another process has a handle on a file. To overcome this issue, and also to emulate explorer's behavior when compressing files used by another process, the cmdlet defaults to __[`FileShare 'ReadWrite, Delete'`](https://learn.microsoft.com/en-us/dotnet/api/system.io.fileshare?view=net-6.0)__ when opening a [`FileStream`](https://learn.microsoft.com/en-us/dotnet/api/system.io.file.open?view=net-7.0).

docs/en-US/ConvertFrom-GzipString.md

@@ -14,7 +14,11 @@ Expands Base64 Gzip compressed input strings.
 ## SYNTAX
 
 ```powershell
-ConvertFrom-GzipString [-InputObject] <String[]> [[-Encoding] <Encoding>] [-Raw] [<CommonParameters>]
+ConvertFrom-GzipString
+    [-InputObject] <String[]>
+    [[-Encoding] <Encoding>]
+    [-Raw]
+    [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -55,7 +59,10 @@ helloworld!
 
 ### -Encoding
 
-Determines the character encoding used when expanding the input strings. The default encoding is __`utf8NoBOM`__.
+Determines the character encoding used when expanding the input strings.
+
+> [!NOTE]
+> The default encoding is __`utf8NoBOM`__.
 
 ```yaml
 Type: Encoding

docs/en-US/ConvertTo-GzipString.md

@@ -14,8 +14,13 @@ Creates a Gzip Base64 compressed string from a specified input string or strings
 ## SYNTAX
 
 ```powershell
-ConvertTo-GzipString [-InputObject] <String[]> [-Encoding <Encoding>] [-CompressionLevel <CompressionLevel>]
- [-AsByteStream] [-NoNewLine] [<CommonParameters>]
+ConvertTo-GzipString
+    [-InputObject] <String[]>
+    [-Encoding <Encoding>]
+    [-CompressionLevel <CompressionLevel>]
+    [-AsByteStream]
+    [-NoNewLine]
+    [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -83,7 +88,8 @@ PS ..\pwsh> (Get-Content .\files\lorem*.txt | ConvertTo-GzipString).Length / 1kb
 
 Outputs the compressed byte array to the Success Stream.
 
-> __NOTE:__ This parameter is meant to be used in combination with `Compress-GzipArchive`.
+> [!NOTE]
+> This parameter is meant to be used in combination with [`Compress-GzipArchive`](./Compress-GzipArchive.md).
 
 ```yaml
 Type: SwitchParameter
@@ -117,7 +123,10 @@ Accept wildcard characters: False
 
 ### -Encoding
 
-Determines the character encoding used when compressing the input strings. The default encoding is __`utf8NoBOM`__.
+Determines the character encoding used when compressing the input strings.
+
+> [!NOTE]
+> The default encoding is __`utf8NoBOM`__.
 
 ```yaml
 Type: Encoding