Oakrey.Files 3.0.0

Oakrey.Files

1. Overview

The Files project provides utilities for file naming and compression. It simplifies the generation of unique file names based on various policies and offers methods for compressing and decompressing files and byte arrays.

2. Feature

File Naming Utilities:

FileNameGenerator:

• Generates file names based on policies like date-time, GUID, incremental, and user-defined formats.
• Supports creating file paths by combining folder paths, file names, and extensions.

FileNameSource:

• Encapsulates file naming parameters and provides methods to generate file names and paths dynamically.

FileNamingPolicy:

• Enum defining supported naming policies (e.g., DateTime, GUID, Incremental).

Compression and Decompression:

ZipCompression:

• Provides methods to compress and decompress byte arrays and files using GZip.

Thread-Safe Operations:

Ensures thread safety for file name generation using locks.

Extensibility:

Designed to support additional file naming policies and compression algorithms.

INI File Management

IniFile class:

• Represents an INI configuration file with support for sections and key-value pairs.
• Provides typed value accessors (GetBool, GetInt, GetDouble) with default value fallback.
• Supports global (unnamed) section for entries outside named sections.
• Offers both direct and try-pattern methods for safe value and section access.
• Enables section and value manipulation (add, remove, check existence).
• Thread-safe section and value lookups using normalized section names.

IniReader:

• Loads INI files from disk with automatic encoding detection or custom encoding.
• Parses INI content from StreamReader for flexible input sources.
• Recognizes section headers ([SectionName]) and key-value pairs (key=value).
• Supports comments starting with ; or #.
• Handles whitespace normalization and empty lines.

IniWriter:

• Saves INI files atomically using temp-file-and-replace pattern to prevent corruption.
• Writes INI content to StreamWriter with optional global section control.
• Supports custom text encoding (default UTF-8).
• Ensures data integrity during save operations with automatic cleanup.

Extended INI File Management

IniExtendedFile class:

• Full-featured INI file representation with complete comment and formatting preservation.
• Supports preamble comments (comments before first section).
• Maintains leading comments (blank lines and comments above sections/entries).
• Supports inline comments on section headers and key-value entries.
• Provides case-insensitive section and key lookups.
• Offers both direct and try-pattern methods for safe value and section access.
• Enables dynamic section and entry manipulation while preserving formatting.

IniReader (Extended):

• Loads INI files with full preservation of comments, blank lines, and formatting.
• Parses section headers with optional inline comments: [SectionName] ; comment.
• Parses key-value pairs with inline comments: key=value ; comment.
• Supports customizable comment start characters (default: ; and #).
• Handles quoted values with embedded comment characters correctly.
• Preserves document structure including preamble, leading comments, and blank lines.
• Automatic encoding detection or custom encoding support.

IniExtendedWriter:

• Writes INI files with complete formatting and comment preservation.
• Atomic save operation using temp-file-and-replace pattern to prevent corruption.
• Customizable key-value separator (default: =).
• Customizable section header format (default: [{0}]).
• Preserves all comments (preamble, leading, and inline).
• Maintains blank lines for readability.
• Ensures data integrity during save with automatic cleanup.

Supporting classes:

Entry:

• Represents a key-value pair with optional inline comment.
• Maintains collection of leading comments and blank lines.
• Supports full formatting preservation during read/write cycles.

Section:

• Represents a named section with its entries.
• Supports optional inline comment on section header.
• Maintains leading comments and blank lines before section declaration.
• Provides FindEntry method for case-insensitive entry lookup.

Item, Comment, Blank:

• Base types for representing INI file elements.
• Comment - stores comment text including the comment character.
• Blank - represents empty lines for formatting preservation.
• Item - abstract base for all line types in INI file.

PendingItems:

• Internal helper collection for managing comments and blanks during parsing.
• Ensures proper association of comments with following sections/entries.

3. Installation

You can install the package via NuGet Package Manager, Package Manager Console or the .NET CLI.

NuGet Package Manager

1. Open your project in Visual Studio.
2. Navigate to Tools > NuGet Package Manager > Manage NuGet Packages for Solution....
3. Search for Oakrey.Files and click Install.

.NET CLI

Run the following command in your terminal:

dotnet add package Oakrey.Files

Package Manager Console

Run the following command in your Package Manager Console:

Install-Package Oakrey.Files

4. Requirements

• .NET 8 or higher

5. Project Information

• Author: Oakrey
• Company: Oakrey (Website Link)
• License: MIT
• Repository: Git Repository
• Project URL: Project Website

6. Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to improve the package.

7. License

This project is licensed under the MIT License. See the LICENSE file for details.