Merge pull request #1193 from adamhathcock/adam/cleanup-options

Change and clean up options

Author: adamhathcock

docs/API.md

@@ -20,14 +20,18 @@ using (var archive = RarArchive.OpenArchive("file.rar"))
 using (var archive = SevenZipArchive.OpenArchive("file.7z"))
 using (var archive = GZipArchive.OpenArchive("file.gz"))
 
-// With options
-var options = new ReaderOptions
+// With fluent options (preferred)
+var options = ReaderOptions.ForEncryptedArchive("password")
+    .WithArchiveEncoding(new ArchiveEncoding { Default = Encoding.GetEncoding(932) });
+using (var archive = ZipArchive.OpenArchive("encrypted.zip", options))
+
+// Alternative: object initializer
+var options2 = new ReaderOptions
 {
     Password = "password",
     LeaveStreamOpen = true,
     ArchiveEncoding = new ArchiveEncoding { Default = Encoding.GetEncoding(932) }
 };
-using (var archive = ZipArchive.OpenArchive("encrypted.zip", options))
 ```
 
 ### Creating Archives
@@ -44,16 +48,21 @@ using (var archive = ZipArchive.CreateArchive())
 using (var archive = TarArchive.CreateArchive())
 using (var archive = GZipArchive.CreateArchive())
 
-// With options
-var options = new WriterOptions(CompressionType.Deflate)
-{
-    CompressionLevel = 9,
-    LeaveStreamOpen = false
-};
+// With fluent options (preferred)
+var options = WriterOptions.ForZip()
+    .WithCompressionLevel(9)
+    .WithLeaveStreamOpen(false);
 using (var archive = ZipArchive.CreateArchive())
 {
     archive.SaveTo("output.zip", options);
 }
+
+// Alternative: constructor with object initializer
+var options2 = new WriterOptions(CompressionType.Deflate)
+{
+    CompressionLevel = 9,
+    LeaveStreamOpen = false
+};
 ```
 
 ---
@@ -72,16 +81,11 @@ using (var archive = ZipArchive.OpenArchive("file.zip"))
     var entry = archive.Entries.FirstOrDefault(e => e.Key == "file.txt");
 
     // Extract all
-    archive.WriteToDirectory(@"C:\output", new ExtractionOptions
-    {
-        ExtractFullPath = true,
-        Overwrite = true
-    });
+    archive.WriteToDirectory(@"C:\output");
 
     // Extract single entry
     var entry = archive.Entries.First();
     entry.WriteToFile(@"C:\output\file.txt");
-    entry.WriteToFile(@"C:\output\file.txt", new ExtractionOptions { Overwrite = true });
 
     // Get entry stream
     using (var stream = entry.OpenEntryStream())
@@ -95,7 +99,6 @@ using (var asyncArchive = await ZipArchive.OpenAsyncArchive("file.zip"))
 {
     await asyncArchive.WriteToDirectoryAsync(
         @"C:\output",
-        new ExtractionOptions { ExtractFullPath = true, Overwrite = true },
         cancellationToken: cancellationToken
     );
 }
@@ -187,7 +190,6 @@ using (var reader = await ReaderFactory.OpenAsyncReader(stream))
     // Async extraction of all entries
     await reader.WriteAllToDirectoryAsync(
         @"C:\output",
-        new ExtractionOptions { ExtractFullPath = true, Overwrite = true },
         cancellationToken
     );
 }
@@ -229,43 +231,91 @@ using (var writer = WriterFactory.OpenWriter(stream, ArchiveType.Zip, Compressio
 
 ### ReaderOptions
 
+Use factory presets and fluent helpers for common configurations:
+
 ```csharp
-var options = new ReaderOptions
-{
-    Password = "password",                          // For encrypted archives
-    LeaveStreamOpen = true,                         // Don't close wrapped stream
-    ArchiveEncoding = new ArchiveEncoding          // Custom character encoding
-    {
-        Default = Encoding.GetEncoding(932)
-    }
-};
+// External stream with password and custom encoding
+var options = ReaderOptions.ForExternalStream()
+    .WithPassword("password")
+    .WithArchiveEncoding(new ArchiveEncoding { Default = Encoding.GetEncoding(932) });
+
 using (var archive = ZipArchive.OpenArchive("file.zip", options))
 {
     // ...
 }
+
+// Common presets
+var safeOptions = ReaderOptions.SafeExtract;      // No overwrite
+var flatOptions = ReaderOptions.FlatExtract;      // No directory structure
+
+// Factory defaults:
+// - file path / FileInfo overloads use LeaveStreamOpen = false
+// - stream overloads use LeaveStreamOpen = true
+```
+
+Alternative: traditional object initializer:
+
+```csharp
+var options = new ReaderOptions
+{
+    Password = "password",
+    LeaveStreamOpen = true,
+    ArchiveEncoding = new ArchiveEncoding { Default = Encoding.GetEncoding(932) }
+};
 ```
 
 ### WriterOptions
 
+Factory methods provide a clean, discoverable way to create writer options:
+
+```csharp
+// Factory methods for common archive types
+var zipOptions = WriterOptions.ForZip()                           // ZIP with Deflate
+    .WithCompressionLevel(9)                                      // 0-9 for Deflate
+    .WithLeaveStreamOpen(false);                                  // Close stream when done
+
+var tarOptions = WriterOptions.ForTar(CompressionType.GZip)       // TAR with GZip
+    .WithLeaveStreamOpen(false);
+
+var gzipOptions = WriterOptions.ForGZip()                         // GZip file
+    .WithCompressionLevel(6);
+
+archive.SaveTo("output.zip", zipOptions);
+```
+
+Alternative: traditional constructor with object initializer:
+
 ```csharp
 var options = new WriterOptions(CompressionType.Deflate)
 {
-    CompressionLevel = 9,                           // 0-9 for Deflate
-    LeaveStreamOpen = true,                         // Don't close stream
+    CompressionLevel = 9,
+    LeaveStreamOpen = true,
 };
 archive.SaveTo("output.zip", options);
 ```
 
-### ExtractionOptions
+### Extraction behavior
 
 ```csharp
-var options = new ExtractionOptions
+var options = new ReaderOptions
 {
     ExtractFullPath = true,                         // Recreate directory structure
     Overwrite = true,                               // Overwrite existing files
     PreserveFileTime = true                         // Keep original timestamps
 };
-archive.WriteToDirectory(@"C:\output", options);
+
+using (var archive = ZipArchive.OpenArchive("file.zip", options))
+{
+    archive.WriteToDirectory(@"C:\output");
+}
+```
+
+### Options matrix
+
+```text
+ReaderOptions: open-time behavior (password, encoding, stream ownership, extraction defaults)
+WriterOptions: write-time behavior (compression type/level, encoding, stream ownership)
+ZipWriterEntryOptions: per-entry ZIP overrides (compression, level, timestamps, comments, zip64)
 ```
 
 ---
@@ -317,13 +367,9 @@ ArchiveType.ZStandard
 try
 {
     using (var archive = ZipArchive.Open("archive.zip", 
-        new ReaderOptions { Password = "password" }))
+        ReaderOptions.ForEncryptedArchive("password")))
     {
-        archive.WriteToDirectory(@"C:\output", new ExtractionOptions
-        {
-            ExtractFullPath = true,
-            Overwrite = true
-        });
+        archive.WriteToDirectory(@"C:\output");
     }
 }
 catch (PasswordRequiredException)
@@ -348,7 +394,7 @@ var progress = new Progress<ProgressReport>(report =>
     Console.WriteLine($"Extracting {report.EntryPath}: {report.PercentComplete}%");
 });
 
-var options = new ReaderOptions { Progress = progress };
+var options = ReaderOptions.ForOwnedFile().WithProgress(progress);
 using (var archive = ZipArchive.OpenArchive("archive.zip", options))
 {
     archive.WriteToDirectory(@"C:\output");
@@ -367,7 +413,6 @@ try
     {
         await archive.WriteToDirectoryAsync(
             @"C:\output",
-            new ExtractionOptions { ExtractFullPath = true, Overwrite = true },
             cancellationToken: cts.Token
         );
     }

docs/ARCHITECTURE.md

@@ -90,7 +90,7 @@ Common types, options, and enumerations used across formats.
 - `ArchiveType.cs` - Enum for archive formats
 - `CompressionType.cs` - Enum for compression methods
 - `ArchiveEncoding.cs` - Character encoding configuration
-- `ExtractionOptions.cs` - Extraction configuration
+- `IExtractionOptions.cs` - Extraction configuration exposed through `ReaderOptions`
 - Format-specific headers: `Zip/Headers/`, `Tar/Headers/`, `Rar/Headers/`, etc.
 
 #### `Compressors/` - Compression Algorithms
@@ -215,13 +215,13 @@ using (var compressor = new DeflateStream(nonDisposingStream))
 public abstract class AbstractArchive : IArchive
 {
     // Template methods
-    public virtual void WriteToDirectory(string destinationDirectory, ExtractionOptions options)
+    public virtual void WriteToDirectory(string destinationDirectory)
     {
         // Common extraction logic
         foreach (var entry in Entries)
         {
             // Call subclass method
-            entry.WriteToFile(destinationPath, options);
+            entry.WriteToFile(destinationPath);
         }
     }
 
@@ -267,8 +267,7 @@ public interface IArchive : IDisposable
 {
     IEnumerable<IEntry> Entries { get; }
 
-    void WriteToDirectory(string destinationDirectory, 
-                         ExtractionOptions options = null);
+    void WriteToDirectory(string destinationDirectory);
 
     IEntry FirstOrDefault(Func<IEntry, bool> predicate);
 
@@ -287,8 +286,7 @@ public interface IReader : IDisposable
 
     bool MoveToNextEntry();
 
-    void WriteEntryToDirectory(string destinationDirectory,
-                              ExtractionOptions options = null);
+    void WriteEntryToDirectory(string destinationDirectory);
 
     Stream OpenEntryStream();
 
@@ -327,7 +325,7 @@ public interface IEntry
     DateTime? LastModifiedTime { get; }
     CompressionType CompressionType { get; }
 
-    void WriteToFile(string fullPath, ExtractionOptions options = null);
+    void WriteToFile(string fullPath);
     void WriteToStream(Stream destinationStream);
     Stream OpenEntryStream();
 

docs/ENCODING.md

@@ -18,14 +18,9 @@ Most archive formats store filenames and metadata as bytes. SharpCompress must c
 using SharpCompress.Common;
 using SharpCompress.Readers;
 
-// Configure encoding before opening archive
-var options = new ReaderOptions
-{
-    ArchiveEncoding = new ArchiveEncoding 
-    { 
-        Default = Encoding.GetEncoding(932)  // cp932 for Japanese
-    }
-};
+// Configure encoding using fluent factory method (preferred)
+var options = ReaderOptions.ForEncoding(
+    new ArchiveEncoding { Default = Encoding.GetEncoding(932) });  // cp932 for Japanese
 
 using (var archive = ZipArchive.OpenArchive("japanese.zip", options))
 {
@@ -34,6 +29,12 @@ using (var archive = ZipArchive.OpenArchive("japanese.zip", options))
         Console.WriteLine(entry.Key);  // Now shows correct characters
     }
 }
+
+// Alternative: object initializer
+var options2 = new ReaderOptions
+{
+    ArchiveEncoding = new ArchiveEncoding { Default = Encoding.GetEncoding(932) }
+};
 ```
 
 ### ArchiveEncoding Properties
@@ -47,10 +48,8 @@ using (var archive = ZipArchive.OpenArchive("japanese.zip", options))
 
 **Archive API:**
 ```csharp
-var options = new ReaderOptions
-{
-    ArchiveEncoding = new ArchiveEncoding { Default = Encoding.GetEncoding(932) }
-};
+var options = ReaderOptions.ForEncoding(
+    new ArchiveEncoding { Default = Encoding.GetEncoding(932) });
 using (var archive = ZipArchive.OpenArchive("file.zip", options))
 {
     // Use archive with correct encoding
@@ -59,10 +58,8 @@ using (var archive = ZipArchive.OpenArchive("file.zip", options))
 
 **Reader API:**
 ```csharp
-var options = new ReaderOptions
-{
-    ArchiveEncoding = new ArchiveEncoding { Default = Encoding.GetEncoding(932) }
-};
+var options = ReaderOptions.ForEncoding(
+    new ArchiveEncoding { Default = Encoding.GetEncoding(932) });
 using (var stream = File.OpenRead("file.zip"))
 using (var reader = ReaderFactory.OpenReader(stream, options))
 {
@@ -390,11 +387,7 @@ var options = new ReaderOptions
 
 using (var archive = ZipArchive.OpenArchive("japanese_files.zip", options))
 {
-    archive.WriteToDirectory(@"C:\output", new ExtractionOptions
-    {
-        ExtractFullPath = true,
-        Overwrite = true
-    });
+    archive.WriteToDirectory(@"C:\output");
 }
 // Files extracted with correct Japanese names
 ```

docs/PERFORMANCE.md

@@ -213,11 +213,7 @@ using (var archive = RarArchive.OpenArchive("solid.rar"))
 using (var archive = RarArchive.OpenArchive("solid.rar"))
 {
     // Method 1: Use WriteToDirectory (recommended)
-    archive.WriteToDirectory(@"C:\output", new ExtractionOptions
-    {
-        ExtractFullPath = true,
-        Overwrite = true
-    });
+    archive.WriteToDirectory(@"C:\output");
 
     // Method 2: Use ExtractAllEntries
     archive.ExtractAllEntries();
@@ -337,7 +333,6 @@ using (var archive = ZipArchive.OpenArchive("archive.zip"))
 {
     await archive.WriteToDirectoryAsync(
         @"C:\output",
-        new ExtractionOptions { ExtractFullPath = true, Overwrite = true },
         cancellationToken
     );
 }
@@ -355,10 +350,7 @@ Async doesn't improve performance for:
 // Sync extraction (simpler, same performance on fast I/O)
 using (var archive = ZipArchive.OpenArchive("archive.zip"))
 {
-    archive.WriteToDirectory(
-        @"C:\output",
-        new ExtractionOptions { ExtractFullPath = true, Overwrite = true }
-    );
+    archive.WriteToDirectory(@"C:\output");
 }
 // Simple and fast - no async needed
 ```
@@ -377,7 +369,6 @@ try
     {
         await archive.WriteToDirectoryAsync(
             @"C:\output",
-            new ExtractionOptions { ExtractFullPath = true, Overwrite = true },
             cts.Token
         );
     }