Merge pull request #33 from santisq/18-new-zipentry-to-use-files-full…

…name-if-no-entrypath-is-provided

`New-ZipEntry` - Use file's `.FullName` if no `-EntryPath` is provided

docs/en-US/Compress-GzipArchive.md

@@ -17,8 +17,8 @@ Creates a Gzip compressed file from specified paths or input bytes.
 
 ```powershell
 Compress-GzipArchive
-    [-Path] <String[]>
-    [-Destination] <String>
+    -Path <String[]>
+    -Destination <String>
     [-CompressionLevel <CompressionLevel>]
     [-Update]
     [-Force]
@@ -31,7 +31,7 @@ Compress-GzipArchive
 ```powershell
 Compress-GzipArchive
     -LiteralPath <String[]>
-    [-Destination] <String>
+    -Destination <String>
     [-CompressionLevel <CompressionLevel>]
     [-Update]
     [-Force]
@@ -44,7 +44,7 @@ Compress-GzipArchive
 ```powershell
 Compress-GzipArchive
     -InputBytes <Byte[]>
-    [-Destination] <String>
+    -Destination <String>
     [-CompressionLevel <CompressionLevel>]
     [-Update]
     [-Force]

docs/en-US/Compress-ZipArchive.md

@@ -17,7 +17,7 @@ The `Compress-ZipArchive` cmdlet creates a compressed, or zipped, archive file f
 
 ```powershell
 Compress-ZipArchive
-    [-Path] <String[]>
+    -Path <String[]>
     -Destination <String>
     [-CompressionLevel <CompressionLevel>]
     [-Update]

docs/en-US/ConvertFrom-GzipString.md

@@ -15,8 +15,8 @@ Expands Gzip Base64 compressed input strings.
 
 ```powershell
 ConvertFrom-GzipString
-    [-InputObject] <String[]>
-    [[-Encoding] <Encoding>]
+    -InputObject <String[]>
+    [-Encoding <Encoding>]
     [-Raw]
     [<CommonParameters>]
 ```

docs/en-US/ConvertTo-GzipString.md

@@ -15,7 +15,7 @@ Creates a Gzip Base64 compressed string from a specified input string or strings
 
 ```powershell
 ConvertTo-GzipString
-    [-InputObject] <String[]>
+    -InputObject <String[]>
     [-Encoding <Encoding>]
     [-CompressionLevel <CompressionLevel>]
     [-AsByteStream]

docs/en-US/Expand-GzipArchive.md

@@ -17,7 +17,7 @@ Expands a Gzip compressed file from a specified File Path or Paths.
 
 ```powershell
 Expand-GzipArchive
-    [-Path] <String[]>
+    -Path <String[]>
     [-Raw]
     [<CommonParameters>]
 ```
@@ -26,7 +26,7 @@ Expand-GzipArchive
 
 ```powershell
 Expand-GzipArchive
-    [-Path] <String[]>
+    -Path <String[]>
     -Destination <String>
     [-Encoding <Encoding>]
     [-PassThru]

docs/en-US/Expand-ZipEntry.md

@@ -16,7 +16,7 @@ Expands Zip Archive Entries to a destination directory.
 ```powershell
 Expand-ZipEntry
     -InputObject <ZipEntryBase[]>
-    [[-Destination] <String>]
+    [-Destination <String>]
     [-Force]
     [-PassThru]
     [<CommonParameters>]

docs/en-US/Get-ZipEntry.md

@@ -17,7 +17,7 @@ Lists zip entries from one or more specified Zip Archives.
 
 ```powershell
 Get-ZipEntry
-   [-Path] <String[]>
+   -Path <String[]>
    [-Type <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
@@ -68,7 +68,7 @@ The `-Type` parameter supports filtering by `Archive` or `Directory`.
 ```powershell
 PS ..\pwsh> Get-ZipEntry .\PSCompression.zip -Include PSCompression/docs/en-us*
 
-   Directory: PSCompression/docs/en-US/
+   Directory: /PSCompression/docs/en-US/
 
 Type                    LastWriteTime  CompressedSize            Size Name
 ----                    -------------  --------------            ---- ----
@@ -89,7 +89,7 @@ Archive            2/22/2024  1:19 PM         1.55 KB         5.35 KB Set-ZipEnt
 
 PS ..\pwsh> Get-ZipEntry .\PSCompression.zip -Include PSCompression/docs/en-us* -Exclude *en-US/Compress*, *en-US/Remove*
 
-   Directory: PSCompression/docs/en-US/
+   Directory: /PSCompression/docs/en-US/
 
 Type                    LastWriteTime  CompressedSize            Size Name
 ----                    -------------  --------------            ---- ----
@@ -106,8 +106,10 @@ Archive            2/22/2024  1:19 PM       741.00  B         2.16 KB Rename-Zip
 Archive            2/22/2024  1:19 PM         1.55 KB         5.35 KB Set-ZipEntryContent.md
 ```
 
-Inclusion and Exclusion patterns are applied to the entries relative path.
-Exclusions are applied after the inclusions.
+> [!NOTE]
+>
+> - Inclusion and Exclusion patterns are applied to the entries relative path.
+> - Exclusions are applied after the inclusions.
 
 ## PARAMETERS
 

docs/en-US/New-ZipEntry.md

@@ -17,9 +17,9 @@ Creates zip entries from one or more specified entry relative paths.
 
 ```powershell
 New-ZipEntry
-   [-Value <String[]>]
    -Destination <String>
    -EntryPath <String[]>
+   [-Value <String[]>]
    [-CompressionLevel <CompressionLevel>]
    [-Encoding <Encoding>]
    [-Force]
@@ -31,8 +31,8 @@ New-ZipEntry
 ```powershell
 New-ZipEntry
    -Destination <String>
-   -EntryPath <String[]>
-   [-SourcePath <String>]
+   -SourcePath <String>
+   [-EntryPath <String[]>]
    [-CompressionLevel <CompressionLevel>]
    [-Force]
    [<CommonParameters>]
@@ -46,12 +46,12 @@ Entry paths, _arguments of the `-EntryPath` parameter_, are always normalized, a
 
 | Input                          | Normalized As               |
 | ------------------------------ | --------------------------- |
-| `path\to\mynewentry.ext`       | `path/to/mynewentry.ext`    |
-| `\path\to\newdirectory\`       | `path/to/newdirectory/`     |
+| `C:\path\to\mynewentry.ext`    | `path/to/mynewentry.ext`    |
+| `\\path\to\newdirectory\`      | `path/to/newdirectory/`     |
 | `path\to\very/\random\/path\\` | `path/to/very/random/path/` |
 
 > [!TIP]
-> The `[PSCompression.Extensions.PathExtensions]::NormalizePath(string path)` static method is available as a public API if you would like to normalize your paths before creating new entries.
+> The `[PSCompression.Extensions.PathExtensions]::NormalizePath(string path)` static method is available as a public API if you want to normalize your paths before creating new entries.
 
 In addition, `New-ZipEntry` can set the content of the entries that it creates from string input or by specifying a source file path.
 
@@ -62,13 +62,13 @@ In addition, `New-ZipEntry` can set the content of the entries that it creates f
 ```powershell
 PS ..\pwsh> New-ZipEntry .\test.zip -EntryPath test\entry, newfolder\
 
-   Directory: newfolder/
+   Directory: /newfolder/
 
 Type                    LastWriteTime  CompressedSize            Size Name
 ----                    -------------  --------------            ---- ----
 Directory          2/24/2024  3:22 PM         0.00  B         0.00  B newfolder
 
-   Directory: test/
+   Directory: /test/
 
 Type                    LastWriteTime  CompressedSize            Size Name
 ----                    -------------  --------------            ---- ----
@@ -89,36 +89,40 @@ world
 !
 ```
 
-The cmdlet prevents creating entries in a destination Zip archive if an entry with the same relative path already exists. You can use the `-Force` parameter to overwrite them.
+> [!TIP]
+> The cmdlet prevents creating entries in a destination Zip archive if an entry with the same relative path already exists. You can use the `-Force` parameter to overwrite them.
 
 ### Example 3: Create entries with content from a source file path
 
 ```powershell
 PS ..\pwsh> $file = 'hello world!' | New-Item mytestfile.txt
-PS ..\pwsh> New-ZipEntry .\test.zip -EntryPath newentry.txt -SourcePath $file.FullName
+PS ..\pwsh> New-ZipEntry .\test.zip -SourcePath $file.FullName -EntryPath newentry.txt
 ```
 
 ### Example 4: Archive all files in a specified location
 
 ```powershell
 PS ..\pwsh> $files = Get-ChildItem -File -Recurse
-PS ..\pwsh> $files | ForEach-Object {
-   New-ZipEntry .\test.zip -EntryPath $_.FullName.Remove(0, $pwd.Path.Length) -SourcePath $_.FullName
-}
+PS ..\pwsh> $files | ForEach-Object { New-ZipEntry .\test.zip -SourcePath $_.FullName }
 ```
 
-In this example `$_.FullName.Remove(0, $pwd.Path.Length)` is used to get the file paths relative to the current location. Using `-EntryPath $_.FullName` without getting the relative paths would work too however this would cause issues while attempting to extract the files later.
+> [!TIP]
+> The `-EntryPath` parameter is optional when creating an entry from a source file.
+> If the entry path isn't specified, the cmdlet will using the file's `.FullName` in its normalized form.
 
 ### Example 5: Archive all `.txt` files in a specified location using a specified encoding
 
 ```powershell
 PS ..\pwsh> $files = Get-ChildItem -File -Recurse -Filter *.txt
 PS ..\pwsh> $files | ForEach-Object {
    $_ | Get-Content -Encoding ascii |
-      New-ZipEntry .\test.zip -EntryPath $_.FullName.Remove(0, $pwd.Path.Length) -Encoding ascii
+      New-ZipEntry .\test.zip -EntryPath $_.FullName -Encoding ascii
 }
 ```
 
+> [!NOTE]
+> As opposed to previous example, when creating entries from input values, __the `-EntryPath` parameter is mandatory__. In this case, when using an absolute path as `-EntryPath` the cmdlet will always create the entries using their normalized form as explained in [__Description__](#description).
+
 ## PARAMETERS
 
 ### -CompressionLevel

docs/en-US/Rename-ZipEntry.md

@@ -15,8 +15,8 @@ Renames zip entries from one or more zip archives.
 
 ```powershell
 Rename-ZipEntry
-    [-ZipEntry] <ZipEntryBase>
-    [-NewName] <String>
+    -ZipEntry <ZipEntryBase>
+    -NewName <String>
     [-PassThru]
     [-WhatIf]
     [-Confirm]
@@ -63,7 +63,7 @@ PS ..pwsh\> Get-ZipEntry .\myZip.zip -Type Archive -Include *.ext |
 ```powershell
 PS ..\pwsh> Get-ZipEntry .\PSCompression.zip -Include PSCompression/docs/en-US/*
 
-   Directory: PSCompression/docs/en-US/
+   Directory: /PSCompression/docs/en-US/
 
 Type                    LastWriteTime  CompressedSize            Size Name
 ----                    -------------  --------------            ---- ----
@@ -85,7 +85,7 @@ Archive            2/22/2024  1:19 PM         1.55 KB         5.35 KB Set-ZipEnt
 PS ..\pwsh> Get-ZipEntry .\PSCompression.zip -Include PSCompression/docs/en-US/ | Rename-ZipEntry -NewName 'en-US123'
 PS ..\pwsh> Get-ZipEntry .\PSCompression.zip -Include PSCompression/docs/en-US123/*
 
-   Directory: PSCompression/docs/en-US123/
+   Directory: /PSCompression/docs/en-US123/
 
 Type                    LastWriteTime  CompressedSize            Size Name
 ----                    -------------  --------------            ---- ----
@@ -123,7 +123,7 @@ Performing the operation "Rename" on target "PSCompression/docs/en-US123/".
 Specifies the new name of the zip entry. Enter only a name, not a path and name.
 
 > [!TIP]
-> [Delay-bind scriptblock](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_script_blocks?view=powershell-7.4#using-delay-bind-script-blocks-with-parameters) is supported for this parameter. See [Example 2](./Rename-ZipEntry.md#example-2-rename-all-entries-with-ext-extension-using-a-delay-bind-scriptblock).
+> [Delay-bind scriptblock](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_script_blocks?view=powershell-7.4#using-delay-bind-script-blocks-with-parameters) is supported for this parameter. See [Example 2](#example-2-rename-all-entries-with-ext-extension-using-a-delay-bind-scriptblock).
 
 ```yaml
 Type: String

docs/en-US/Set-ZipEntryContent.md

@@ -18,7 +18,7 @@ Sets or appends content to an existing zip entry.
 ```powershell
 Set-ZipEntryContent
     -Value <Object[]>
-    [-SourceEntry] <ZipEntryFile>
+    -SourceEntry <ZipEntryFile>
     [-Encoding <Encoding>]
     [-Append]
     [-PassThru]
@@ -30,7 +30,7 @@ Set-ZipEntryContent
 ```powershell
 Set-ZipEntryContent
     -Value <Object[]>
-    [-SourceEntry] <ZipEntryFile>
+    -SourceEntry <ZipEntryFile>
     [-AsByteStream]
     [-Append]
     [-BufferSize <Int32>]
@@ -131,6 +131,7 @@ Accept wildcard characters: False
 ### -BufferSize
 
 For efficiency purposes this cmdlet buffers bytes before writing them to the Zip Archive Entry. This parameter determines how many bytes are buffered before being written to the stream.
+
 > [!NOTE]
 >
 > - __This parameter is applicable only when `-AsByteStream` is used.__

module/PSCompression.psd1

@@ -11,7 +11,7 @@
     RootModule         = 'bin/netstandard2.0/PSCompression.dll'
 
     # Version number of this module.
-    ModuleVersion      = '2.0.7'
+    ModuleVersion      = '2.0.8'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()

src/PSCompression/Commands/CompressGzipArchiveCommand.cs

@@ -3,9 +3,9 @@
 using System.IO.Compression;
 using System.Management.Automation;
 using PSCompression.Extensions;
-using static PSCompression.Exceptions.ExceptionHelpers;
+using PSCompression.Exceptions;
 
-namespace PSCompression;
+namespace PSCompression.Commands;
 
 [Cmdlet(VerbsData.Compress, "GzipArchive", DefaultParameterSetName = "Path")]
 [OutputType(typeof(FileInfo))]
@@ -14,7 +14,7 @@ public sealed class CompressGzipArchive : PSCmdlet, IDisposable
 {
     private bool _isLiteral;
 
-    private string[] _paths = Array.Empty<string>();
+    private string[] _paths = [];
 
     private FileStream? _destination;
 
@@ -83,7 +83,6 @@ protected override void BeginProcessing()
         try
         {
             Destination = Destination.NormalizePath(isLiteral: true, this);
-
             string parent = Destination.GetParent();
 
             if (!Directory.Exists(parent))
@@ -93,13 +92,9 @@ protected override void BeginProcessing()
 
             _destination = File.Open(Destination, GetMode());
         }
-        catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
-        {
-            throw;
-        }
-        catch (Exception e)
+        catch (Exception exception)
         {
-            ThrowTerminatingError(StreamOpenError(Destination, e));
+            ThrowTerminatingError(exception.ToStreamOpenError(Destination));
         }
     }
 
@@ -113,13 +108,9 @@ protected override void ProcessRecord()
             {
                 _destination.Write(InputBytes, 0, InputBytes.Length);
             }
-            catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
+            catch (Exception exception)
             {
-                throw;
-            }
-            catch (Exception e)
-            {
-                WriteError(ZipWriteError(InputBytes, e));
+                WriteError(exception.ToWriteError(InputBytes));
             }
 
             return;
@@ -131,7 +122,7 @@ protected override void ProcessRecord()
         {
             if (!path.IsArchive())
             {
-                WriteError(NotArchivePathError(
+                WriteError(ExceptionHelpers.NotArchivePathError(
                     path,
                     _isLiteral ? nameof(LiteralPath) : nameof(Path)));
 
@@ -143,13 +134,9 @@ protected override void ProcessRecord()
                 using FileStream stream = File.OpenRead(path);
                 stream.CopyTo(_gzip);
             }
-            catch (Exception e) when (e is PipelineStoppedException or FlowControlException)
-            {
-                throw;
-            }
-            catch (Exception e)
+            catch (Exception exception)
             {
-                WriteError(ZipWriteError(path, e));
+                WriteError(exception.ToWriteError(path));
             }
         }
     }