SabreTools/SabreTools.IO
1
0
Fork 0
mirror of https://github.com/SabreTools/SabreTools.IO.git synced 2026-07-08 17:57:02 +00:00
Code Issues 1 Packages Projects Releases 20 Wiki Activity

Add readmes per namespace

Browse Source
This commit is contained in:
Matt Nadareski
2026-03-21 12:29:25 -04:00
parent 4c4233cf39
commit bae3090d9d
13 changed files with 178 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

157
README.MD
View File

@@ -2,155 +2,26 @@
[![Build and Test](https://github.com/SabreTools/SabreTools.IO/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/SabreTools/SabreTools.IO/actions/workflows/build_and_test.yml)
This meta-library comprises of I/O and related functionality used by other SabreTools projects.
This meta-library comprises of I/O and related functionality used by other SabreTools projects. Please see the invidual namespace folders for more details.
Find the link to the Nuget package [here](https://www.nuget.org/packages/SabreTools.IO).
## Namespaces
Below are a list of the included namespaces and their overall utility.
Below are a list of the included namespaces with links to their README files:
### `SabreTools.IO`
Generic helper classes that involve custom functionality and utility.
#### Stream Implementations
| Class | Notes |
| --- | --- |
| `BufferedStream` | Not a true stream implementation used for buffered, single-byte reads |
| `ReadOnlyBitStream` | Read-only stream implementation allowing bitwise reading |
| `ReadOnlyCompositeStream` | Read-only stream implementation that wraps multiple source streams in a set order |
| `ViewStream` | Read-only stream implementation representing a view into source data |
#### Utility Classes
| Class | Notes |
| --- | --- |
| `ParentablePath` | Class that represents a path that is rooted by a parent directory |
| `PathTool` | Utility class for common Path-related functions |
| `Transform` | Utility class that allows common data transformations for streams and byte arrays |
`Transform` functionality includes:
- Combine using either ordered concatenation or interleaving
- Split by even/odd chunks or based on block size
- Convert data either by bit-swapping, byte-swapping, word-swapping, or word/byte-swapping
### `SabreTools.IO.Compression`
Various compression implementations that are used across multiple projects. Most of the implementations are be ports of existing C and C++ code.
#### Supported Compressions
| Compression Name | Decompress | Compress | Notes |
| --- | --- | --- | --- |
| Blast | Yes | No | |
| BZip2 | Yes | Yes | Sourced from DotNetZip |
| Deflate | Yes | Yes | Sourced from DotNetZip |
| LZ | Yes | No | KWAJ, QBasic 4.5, and SZDD variants; KWAJ incomplete |
| LZX | No | No | |
| MSZIP | Yes | No | |
| Quantum | Yes* | No | Partial implementation based on standalone archives; not working |
**Note:** If something is marked with a `*` it means that it need testing.
#### External Libraries
| Library Name | Use |
| --- | --- |
| [DotNetZip](https://github.com/DinoChiesa/DotNetZip) | BZip2 and DEFLATE implementations; minor edits have been made |
| [ZLibPort](https://github.com/Nanook/zlib-C-To-CSharp-Port) | Adds zlib code for internal and external use; minor edits have been made |
### `SabreTools.IO.Extensions`
Extensions for `BinaryReader`, `byte[]`, and `Stream` to help with reading and writing various data types. Some data types are locked behind .NET version support.
This namespace also contains other various extensions that help with common functionality and safe access.
Relies on functionality found in `SabreTools.IO.Matching`, `SabreTools.Numerics`, and `SabreTools.Text.Compare`.
### `SabreTools.Logging`
Logic for a logging system, including writing to console and textfile outputs. There are 4 possible log levels for logging statements to be invoked with. There is also a stopwatch implementation included for logging statements with automatic timespan tracking.
### `SabreTools.Matching`
Classes designed to make matching contents and paths easier. These classes allow for both grouped and single matching as well as post-processing of matched information.
#### Interfaces
| Interface | Notes |
| --- | --- |
| `IMatch<T>` | Represents a matcher for a generic type |
| `IMatchSet<T, U>` | Represents a set of `IMatch<T>` types |
#### Matching Classes
| Class | Implements | Notes |
| --- | --- | --- |
| `ContentMatch` | `IMatch<byte?[]>` | Matches contents of a byte array, allowing wildcard bytes using `null` |
| `ContentMatchSet` | `IMatchSet<ContentMatch, byte?[]>` | Group of logically-linked `ContentMatch` |
| `FilePathMatch` | `IMatch<string>` | Specialization of `PathMatch` that assumes the string is a filename |
| `MatchUtil` | N/A | Utility class for easier invocation of `SabreTools.Matching` functionality |
| `PathMatch` | `IMatch<string>` | Matches a set of strings representing a directory hierarchy |
| `PathMatchSet` | `IMatchSet<PathMatch, string>` | Group of logically-linked `PathMatch` |
### `SabreTools.Numerics`
Custom numeric types and related functionality.
#### Supported Numeric Types
| Type Name | Description |
| --- | --- |
| `BothInt8` | Both-endian `Int8` value |
| `BothUInt8` | Both-endian `UInt8` value |
| `BothInt16` | Both-endian `Int16` value |
| `BothUInt16` | Both-endian `UInt16` value |
| `BothInt32` | Both-endian `Int32` value |
| `BothUInt32` | Both-endian `UInt32` value |
| `BothInt64` | Both-endian `Int64` value |
| `BothUInt64` | Both-endian `UInt64` value |
| `Int24` | 24-bit (3 byte) signed value |
| `UInt24` | 24-bit (3 byte) unsigned value |
| `Int48` | 48-bit (3 byte) signed value |
| `UInt48` | 48-bit (3 byte) unsigned value |
**Both-endian** or **bi-endian** numbers are represented by a little-endian value followed by a big-endian value, where both values are the same number.
### `SabreTools.Security.Cryptography`
Various encryption implementations that are used across multiple projects. Most of the implementations are be ports of existing C and C++ code.
Relies on functionality found in `SabreTools.IO.Extensions`.
#### Supported Encryption Schemes
| Encryption Scheme | Encrypt | Decrypt | Notes |
| --- | --- | --- | --- |
| AES/CTR | Yes | Yes | Subset of functionality exposed from [The Bouncy Castle Cryptography Library For .NET](https://github.com/bcgit/bc-csharp) |
| MoPaQ | No | Yes | Used to encrypt and decrypt MoPaQ tables for processing |
### `SabreTools.Text.ClrMamePro`
Reader and writer classes for ClrMamePro-derived Metadata files.
### `SabreTools.Text.Compare`
Classes focused on string comparison by natural sorting. For example, "5" would be sorted before "100".
### `SabreTools.Text.INI`
Key-value pair INI file, implementing `Dictionary<string, string?>`. Includes reader and writer classes for easier access.
### `SabreTools.Text.SeparatedValue`
Reader and writer classes for separated-Value files (e.g. CSV, SSV, TSV).
### `SabreTools.Text.Utilities`
Various helper classes for dealing with strings. This includes special normalization code used by other SabreTools projects.
- [SabreTools.IO](LINKHERE)
- [SabreTools.IO.Compression](LINKHERE)
- [SabreTools.IO.Extensions](LINKHERE)
- [SabreTools.Logging](LINKHERE)
- [SabreTools.Matching](LINKHERE)
- [SabreTools.Numerics](LINKHERE)
- [SabreTools.Security.Cryptography](LINKHERE)
- [SabreTools.Text.ClrMamePro](LINKHERE)
- [SabreTools.Text.Compare](LINKHERE)
- [SabreTools.Text.INI](LINKHERE)
- [SabreTools.Text.SeparatedValue](LINKHERE)
- [SabreTools.Text.Utilities](LINKHERE)
## Releases

24
SabreTools.IO/SabreTools.IO.Compression/README.MD Normal file
View File

@@ -0,0 +1,24 @@
# SabreTools.IO.Compression
This library contains various compression implementations that are used across multiple projects. Most of the implementations are be ports of existing C and C++ code.
## Supported Compressions
| Compression Name | Decompress | Compress | Notes |
| --- | --- | --- | --- |
| Blast | Yes | No | |
| BZip2 | Yes | Yes | Sourced from DotNetZip |
| Deflate | Yes | Yes | Sourced from DotNetZip |
| LZ | Yes | No | KWAJ, QBasic 4.5, and SZDD variants; KWAJ incomplete |
| LZX | No | No | |
| MSZIP | Yes | No | |
| Quantum | Yes* | No | Partial implementation based on standalone archives; not working |
**Note:** If something is marked with a `*` it means that it need testing.
## External Libraries
| Library Name | Use |
| --- | --- |
| [DotNetZip](https://github.com/DinoChiesa/DotNetZip) | BZip2 and DEFLATE implementations; minor edits have been made |
| [ZLibPort](https://github.com/Nanook/zlib-C-To-CSharp-Port) | Adds zlib code for internal and external use; minor edits have been made |

26
SabreTools.IO/SabreTools.IO.Extensions/README.MD Normal file
View File

@@ -0,0 +1,26 @@
# SabreTools.IO.Extensions
This library contains IO-related extensions with some functionality locked behind .NET version support.
Relies on functionality found in `SabreTools.IO.Matching`, `SabreTools.Numerics`, and `SabreTools.Text.Compare`.
| Class | Description |
| --- | --- |
| `BinaryReaderExtensions` | Extensions to `BinaryReader` allowing for endian-specific reads, peeking functionality, and try-read functionality. |
| `BinaryWriterExtensions` | Extensions to `BinaryWriter` allowing for endian-specific writes. |
| `ByteArrayExtensions` | Utility `byte[]` and `byte?[]` extensions commonly used in SabreTools projects. |
| `ByteArrayReaderExtensions` | Extensions to `byte[]` allowing for endian-specific reads, peeking functionality, and try-read functionality, similar to a stream. |
| `ByteArrayWriterExtensions` | Extensions to `byte[]` allowing for endian-specific writes, similar to a stream. |
| `DateTimeExtensions` | `DateTime` conversion, specifically between standard and MS-DOS formats. |
| `DictionaryExtensions` | Utility `Dictionary<string, List<string>>` extensions commonly used in SabreTools projects. |
| `EnumerableExtensions` | Specialized enumeration wrapper functionality. |
| `IOExtensions` | Path, directory, and file extensions. |
| `MarshalHelpers` | Internal-only reflection-based extensions used by some other extension classes. |
| `NumericExtensions` | Common numeric type extensions allowing for endian-specific processing. |
| `ParentablePathExtensions` | Extensions to `SabreTools.IO.ParentablePath` for filtering. |
| `ReadOnlyBitStreamExtensions` | Extensions to `SabreTools.IO.ReadOnlyBitStream` to allow non-bitwise reads. |
| `StreamExtensions` | Utility `Stream` extensions commonly used in other SabreTools projects. |
| `StreamReaderExtensions` | Extensions to `Stream` allowing for endian-specific reads, peeking functionality, and try-read functionality. |
| `StreamWriterExtensions` | Extensions to `Stream` allowing for endian-specific writes. |
| `StringExtensions` | Optional overloads to `string.Contains`, `string.EndsWith`, `string.Equals`, and `string.StartsWith`. |
| `XmlTextWriterExtensions` | Overloads to `XmlTextWriter.WriteAttributeString` and `XmlTextWriter.WriteElementString`. |

26
SabreTools.IO/SabreTools.IO/README.MD Normal file
View File

@@ -0,0 +1,26 @@
# SabreTools.IO
This library contains both custom stream implementations and utility classes for general IO operations.
## Stream Implementations
| Class | Notes |
| --- | --- |
| `BufferedStream` | Not a true stream implementation used for buffered, single-byte reads |
| `ReadOnlyBitStream` | Read-only stream implementation allowing bitwise reading |
| `ReadOnlyCompositeStream` | Read-only stream implementation that wraps multiple source streams in a set order |
| `ViewStream` | Read-only stream implementation representing a view into source data |
## Utility Classes
| Class | Notes |
| --- | --- |
| `ParentablePath` | Class that represents a path that is rooted by a parent directory |
| `PathTool` | Utility class for common Path-related functions |
| `Transform` | Utility class that allows common data transformations for streams and byte arrays |
`Transform` functionality includes:
- Combine using either ordered concatenation or interleaving
- Split by even/odd chunks or based on block size
- Convert data either by bit-swapping, byte-swapping, word-swapping, or word/byte-swapping

18
SabreTools.IO/SabreTools.Logging/README.MD Normal file
View File

@@ -0,0 +1,18 @@
# SabreTools.Logging
[![Build and Test](https://github.com/SabreTools/SabreTools.IO/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/SabreTools/SabreTools.IO/actions/workflows/build_and_test.yml)
This library contains logic for a logging system, including writing to console and textfile outputs. There are 4 possible log levels for logging statements to be invoked with. There is also a stopwatch implementation included for logging statements with automatic timespan tracking.
## Logging Logic
Logging is performed using the `SabreTools.Logging.Logger` class, which by default allows for 4 levels of log statements:
| `LogLevel` | Description |
| --- | --- |
| `VERBOSE` | Verbose or debug logging statements that do not always need to be presented |
| `USER` | Standard logging statements that would be used during normal operation |
| `WARNING` | Non-critical issues, including missing optional parameters or obsolete behavior |
| `ERROR` | Critical issues, usually ones that prevent all operation |
All logging configuration is done with the static `SabreTools.Logging.LoggerImpl` class, which is called internally by `SabreTools.Logging.Logger`. These static configurations allow for writing to file, filtering log levels, and even throwing if an exception is logged. There is also an automatic stopwatch for total logging runtime.

21
SabreTools.IO/SabreTools.Matching/README.MD Normal file
View File

@@ -0,0 +1,21 @@
# SabreTools.Matching
This library contains classes designed to make matching contents and paths easier. These classes allow for both grouped and single matching as well as post-processing of matched information.
## Interfaces
| Interface | Notes |
| --- | --- |
| `IMatch<T>` | Represents a matcher for a generic type |
| `IMatchSet<T, U>` | Represents a set of `IMatch<T>` types |
## Matching Classes
| Class | Implements | Notes |
| --- | --- | --- |
| `ContentMatch` | `IMatch<byte?[]>` | Matches contents of a byte array, allowing wildcard bytes using `null` |
| `ContentMatchSet` | `IMatchSet<ContentMatch, byte?[]>` | Group of logically-linked `ContentMatch` |
| `FilePathMatch` | `IMatch<string>` | Specialization of `PathMatch` that assumes the string is a filename |
| `MatchUtil` | N/A | Utility class for easier invocation of `SabreTools.Matching` functionality |
| `PathMatch` | `IMatch<string>` | Matches a set of strings representing a directory hierarchy |
| `PathMatchSet` | `IMatchSet<PathMatch, string>` | Group of logically-linked `PathMatch` |

22
SabreTools.IO/SabreTools.Numerics/README.MD Normal file
View File

@@ -0,0 +1,22 @@
# SabreTools.Numerics
This library contains custom numeric types and related functionality.
## Supported Numeric Types
| Type Name | Description |
| --- | --- |
| `BothInt8` | Both-endian `Int8` value |
| `BothUInt8` | Both-endian `UInt8` value |
| `BothInt16` | Both-endian `Int16` value |
| `BothUInt16` | Both-endian `UInt16` value |
| `BothInt32` | Both-endian `Int32` value |
| `BothUInt32` | Both-endian `UInt32` value |
| `BothInt64` | Both-endian `Int64` value |
| `BothUInt64` | Both-endian `UInt64` value |
| `Int24` | 24-bit (3 byte) signed value |
| `UInt24` | 24-bit (3 byte) unsigned value |
| `Int48` | 48-bit (3 byte) signed value |
| `UInt48` | 48-bit (3 byte) unsigned value |
**Both-endian** or **bi-endian** numbers are represented by a little-endian value followed by a big-endian value, where both values should be the same number.

12
SabreTools.IO/SabreTools.Security.Cryptography/README.MD Normal file
View File

@@ -0,0 +1,12 @@
# SabreTools.Security.Cryptography
This library contains various encryption implementations that are used across multiple projects. Most of the implementations are be ports of existing C and C++ code.
Relies on functionality found in `SabreTools.IO.Extensions`.
## Supported Encryption Schemes
| Encryption Scheme | Encrypt | Decrypt | Notes |
| --- | --- | --- | --- |
| AES/CTR | Yes | Yes | Subset of functionality exposed from [The Bouncy Castle Cryptography Library For .NET](https://github.com/bcgit/bc-csharp) |
| MoPaQ | No | Yes | Used to encrypt and decrypt MoPaQ tables for processing |

3
SabreTools.IO/SabreTools.Text.ClrMamePro/README.MD Normal file
View File

@@ -0,0 +1,3 @@
# SabreTools.Text.ClrMamePro
This library contains reader and writer classes for ClrMamePro-derived Metadata files.

3
SabreTools.IO/SabreTools.Text.Compare/README.MD Normal file
View File

@@ -0,0 +1,3 @@
# SabreTools.Text.Compare
This library contains classes focused on string comparison by natural sorting. For example, "5" would be sorted before "100".

3
SabreTools.IO/SabreTools.Text.INI/README.MD Normal file
View File

@@ -0,0 +1,3 @@
# SabreTools.Text.INI
This library contains the defintion for a key-value pair INI file, implementing `Dictionary<string, string?>`. Includes reader and writer classes for easier access.

3
SabreTools.IO/SabreTools.Text.SeparatedValue/README.MD Normal file
View File

@@ -0,0 +1,3 @@
# SabreTools.Text.SeparatedValue
This library contains reader and writer classes for separated-Value files (e.g. CSV, SSV, TSV).

3
SabreTools.IO/SabreTools.Text.Utilities/README.MD Normal file
View File

@@ -0,0 +1,3 @@
# SabreTools.Text.Utilities
This library contains various helper classes for dealing with strings. This includes special normalization code used by other SabreTools projects.