diff --git a/README.MD b/README.MD index f89b7a6..3680a40 100644 --- a/README.MD +++ b/README.MD @@ -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` | Represents a matcher for a generic type | -| `IMatchSet` | Represents a set of `IMatch` types | - -#### Matching Classes - -| Class | Implements | Notes | -| --- | --- | --- | -| `ContentMatch` | `IMatch` | Matches contents of a byte array, allowing wildcard bytes using `null` | -| `ContentMatchSet` | `IMatchSet` | Group of logically-linked `ContentMatch` | -| `FilePathMatch` | `IMatch` | Specialization of `PathMatch` that assumes the string is a filename | -| `MatchUtil` | N/A | Utility class for easier invocation of `SabreTools.Matching` functionality | -| `PathMatch` | `IMatch` | Matches a set of strings representing a directory hierarchy | -| `PathMatchSet` | `IMatchSet` | 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`. 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 diff --git a/SabreTools.IO/SabreTools.IO.Compression/README.MD b/SabreTools.IO/SabreTools.IO.Compression/README.MD new file mode 100644 index 0000000..e653019 --- /dev/null +++ b/SabreTools.IO/SabreTools.IO.Compression/README.MD @@ -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 | diff --git a/SabreTools.IO/SabreTools.IO.Extensions/README.MD b/SabreTools.IO/SabreTools.IO.Extensions/README.MD new file mode 100644 index 0000000..6a26e54 --- /dev/null +++ b/SabreTools.IO/SabreTools.IO.Extensions/README.MD @@ -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>` 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`. | diff --git a/SabreTools.IO/SabreTools.IO/README.MD b/SabreTools.IO/SabreTools.IO/README.MD new file mode 100644 index 0000000..103c4c3 --- /dev/null +++ b/SabreTools.IO/SabreTools.IO/README.MD @@ -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 diff --git a/SabreTools.IO/SabreTools.Logging/README.MD b/SabreTools.IO/SabreTools.Logging/README.MD new file mode 100644 index 0000000..c55bb56 --- /dev/null +++ b/SabreTools.IO/SabreTools.Logging/README.MD @@ -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. diff --git a/SabreTools.IO/SabreTools.Matching/README.MD b/SabreTools.IO/SabreTools.Matching/README.MD new file mode 100644 index 0000000..c05d27e --- /dev/null +++ b/SabreTools.IO/SabreTools.Matching/README.MD @@ -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` | Represents a matcher for a generic type | +| `IMatchSet` | Represents a set of `IMatch` types | + +## Matching Classes + +| Class | Implements | Notes | +| --- | --- | --- | +| `ContentMatch` | `IMatch` | Matches contents of a byte array, allowing wildcard bytes using `null` | +| `ContentMatchSet` | `IMatchSet` | Group of logically-linked `ContentMatch` | +| `FilePathMatch` | `IMatch` | Specialization of `PathMatch` that assumes the string is a filename | +| `MatchUtil` | N/A | Utility class for easier invocation of `SabreTools.Matching` functionality | +| `PathMatch` | `IMatch` | Matches a set of strings representing a directory hierarchy | +| `PathMatchSet` | `IMatchSet` | Group of logically-linked `PathMatch` | diff --git a/SabreTools.IO/SabreTools.Numerics/README.MD b/SabreTools.IO/SabreTools.Numerics/README.MD new file mode 100644 index 0000000..dd27891 --- /dev/null +++ b/SabreTools.IO/SabreTools.Numerics/README.MD @@ -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. diff --git a/SabreTools.IO/SabreTools.Security.Cryptography/README.MD b/SabreTools.IO/SabreTools.Security.Cryptography/README.MD new file mode 100644 index 0000000..fa10f8a --- /dev/null +++ b/SabreTools.IO/SabreTools.Security.Cryptography/README.MD @@ -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 | diff --git a/SabreTools.IO/SabreTools.Text.ClrMamePro/README.MD b/SabreTools.IO/SabreTools.Text.ClrMamePro/README.MD new file mode 100644 index 0000000..ef0f16c --- /dev/null +++ b/SabreTools.IO/SabreTools.Text.ClrMamePro/README.MD @@ -0,0 +1,3 @@ +# SabreTools.Text.ClrMamePro + +This library contains reader and writer classes for ClrMamePro-derived Metadata files. diff --git a/SabreTools.IO/SabreTools.Text.Compare/README.MD b/SabreTools.IO/SabreTools.Text.Compare/README.MD new file mode 100644 index 0000000..50c3f1c --- /dev/null +++ b/SabreTools.IO/SabreTools.Text.Compare/README.MD @@ -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". diff --git a/SabreTools.IO/SabreTools.Text.INI/README.MD b/SabreTools.IO/SabreTools.Text.INI/README.MD new file mode 100644 index 0000000..2310aaf --- /dev/null +++ b/SabreTools.IO/SabreTools.Text.INI/README.MD @@ -0,0 +1,3 @@ +# SabreTools.Text.INI + +This library contains the defintion for a key-value pair INI file, implementing `Dictionary`. Includes reader and writer classes for easier access. diff --git a/SabreTools.IO/SabreTools.Text.SeparatedValue/README.MD b/SabreTools.IO/SabreTools.Text.SeparatedValue/README.MD new file mode 100644 index 0000000..432dd57 --- /dev/null +++ b/SabreTools.IO/SabreTools.Text.SeparatedValue/README.MD @@ -0,0 +1,3 @@ +# SabreTools.Text.SeparatedValue + +This library contains reader and writer classes for separated-Value files (e.g. CSV, SSV, TSV). diff --git a/SabreTools.IO/SabreTools.Text.Utilities/README.MD b/SabreTools.IO/SabreTools.Text.Utilities/README.MD new file mode 100644 index 0000000..6748b0b --- /dev/null +++ b/SabreTools.IO/SabreTools.Text.Utilities/README.MD @@ -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.