diff --git a/SabreTools.IO/Compression/Blast/State.cs b/SabreTools.IO/Compression/Blast/State.cs index 5e401a2..0787fad 100644 --- a/SabreTools.IO/Compression/Blast/State.cs +++ b/SabreTools.IO/Compression/Blast/State.cs @@ -164,7 +164,9 @@ namespace SabreTools.IO.Compression.Blast /// /// Ensure there are bytes available, if possible /// - /// + /// + /// Thrown if there are no bytes available from . + /// private void EnsureAvailable() { // If there are bytes diff --git a/SabreTools.IO/Compression/MSZIP/Decompressor.cs b/SabreTools.IO/Compression/MSZIP/Decompressor.cs index 8805644..c25726a 100644 --- a/SabreTools.IO/Compression/MSZIP/Decompressor.cs +++ b/SabreTools.IO/Compression/MSZIP/Decompressor.cs @@ -40,6 +40,9 @@ namespace SabreTools.IO.Compression.MSZIP /// /// Decompress source data to an output stream /// + /// + /// Thrown if the signature does not match 0x4B43. + /// public bool CopyTo(Stream source, Stream dest) { // Ignore unwritable streams diff --git a/SabreTools.IO/Compression/SZDD/Decompressor.cs b/SabreTools.IO/Compression/SZDD/Decompressor.cs index 736fd0b..ee4e3ae 100644 --- a/SabreTools.IO/Compression/SZDD/Decompressor.cs +++ b/SabreTools.IO/Compression/SZDD/Decompressor.cs @@ -26,6 +26,13 @@ namespace SabreTools.IO.Compression.SZDD /// /// Create a SZDD decompressor /// + /// Source data stream + /// + /// Thrown if has a length of 0. + /// + /// + /// Thrown if is not marked as readable. + /// private Decompressor(Stream source) { // Validate the inputs @@ -48,6 +55,12 @@ namespace SabreTools.IO.Compression.SZDD /// /// Create a KWAJ decompressor /// + /// Source data stream + /// Compression type value + /// Decompressor representing the compression type + /// + /// Thrown if is not between 0x0000 and 0x0004. + /// public static Decompressor CreateKWAJ(Stream source, ushort compressionType) { // Create the decompressor diff --git a/SabreTools.IO/Encryption/AESCTR.cs b/SabreTools.IO/Encryption/AESCTR.cs index 9a50a5f..f3f9dd5 100644 --- a/SabreTools.IO/Encryption/AESCTR.cs +++ b/SabreTools.IO/Encryption/AESCTR.cs @@ -15,6 +15,9 @@ namespace SabreTools.IO.Encryption /// Byte array representation of 128-bit encryption key /// AES initial value for counter /// Initialized AES cipher + /// + /// Thrown if does not have a length of 16. + /// public static IBufferedCipher CreateDecryptionCipher(byte[] key, byte[] iv) { if (key.Length != 16) @@ -32,6 +35,9 @@ namespace SabreTools.IO.Encryption /// Byte array representation of 128-bit encryption key /// AES initial value for counter /// Initialized AES cipher + /// + /// Thrown if does not have a length of 16. + /// public static IBufferedCipher CreateEncryptionCipher(byte[] key, byte[] iv) { if (key.Length != 16) diff --git a/SabreTools.IO/Extensions/ByteArrayReaderExtensions.cs b/SabreTools.IO/Extensions/ByteArrayReaderExtensions.cs index c81d2f2..9476571 100644 --- a/SabreTools.IO/Extensions/ByteArrayReaderExtensions.cs +++ b/SabreTools.IO/Extensions/ByteArrayReaderExtensions.cs @@ -1232,6 +1232,15 @@ namespace SabreTools.IO.Extensions /// /// Read a number of bytes from the byte array to a buffer /// + /// + /// Thrown if or + /// is an invalid value. + /// + /// + /// Thrown if the requested and + /// is greater than + /// length. + /// private static byte[] ReadExactlyToBuffer(byte[] content, ref int offset, int length) { // If we have an invalid offset diff --git a/SabreTools.IO/Extensions/ByteArrayWriterExtensions.cs b/SabreTools.IO/Extensions/ByteArrayWriterExtensions.cs index 6825825..0e4ef06 100644 --- a/SabreTools.IO/Extensions/ByteArrayWriterExtensions.cs +++ b/SabreTools.IO/Extensions/ByteArrayWriterExtensions.cs @@ -923,6 +923,10 @@ namespace SabreTools.IO.Extensions /// /// Write an array of bytes to the byte array /// + /// + /// Thrown if into + /// would not accomodate . + /// private static bool WriteFromBuffer(byte[] content, ref int offset, byte[] value) { // Handle the 0-byte case diff --git a/SabreTools.IO/Extensions/StreamReaderExtensions.cs b/SabreTools.IO/Extensions/StreamReaderExtensions.cs index 0987902..a7396f4 100644 --- a/SabreTools.IO/Extensions/StreamReaderExtensions.cs +++ b/SabreTools.IO/Extensions/StreamReaderExtensions.cs @@ -1227,6 +1227,14 @@ namespace SabreTools.IO.Extensions /// /// Read a number of bytes from the stream to a buffer /// + /// + /// Thrown if is an invalid value. + /// + /// + /// Thrown if the requested is greater + /// than the read bytes from . + /// length. + /// private static byte[] ReadExactlyToBuffer(Stream stream, int length) { // If we have an invalid length diff --git a/SabreTools.IO/Extensions/XmlTextWriterExtensions.cs b/SabreTools.IO/Extensions/XmlTextWriterExtensions.cs index e75f06a..363205c 100644 --- a/SabreTools.IO/Extensions/XmlTextWriterExtensions.cs +++ b/SabreTools.IO/Extensions/XmlTextWriterExtensions.cs @@ -15,6 +15,10 @@ namespace SabreTools.IO.Extensions /// Name of the element /// Value to write in the element /// Indicates if an error should be thrown on a missing required value + /// + /// Thrown if is true and + /// is null. + /// public static void WriteRequiredAttributeString(this XmlTextWriter writer, string localName, string? value, bool throwOnError = false) { // Throw an exception if we are configured to @@ -31,6 +35,10 @@ namespace SabreTools.IO.Extensions /// Name of the element /// Value to write in the element /// Indicates if an error should be thrown on a missing required value + /// + /// Thrown if is true and + /// is null. + /// public static void WriteRequiredElementString(this XmlTextWriter writer, string localName, string? value, bool throwOnError = false) { // Throw an exception if we are configured to diff --git a/SabreTools.IO/IniFile.cs b/SabreTools.IO/IniFile.cs index 7bf9907..15ae753 100644 --- a/SabreTools.IO/IniFile.cs +++ b/SabreTools.IO/IniFile.cs @@ -42,6 +42,9 @@ namespace SabreTools.IO /// /// Populate an INI file from path /// + /// + /// Thrown if is not a valid file. + /// public IniFile(string path) { // If we don't have a file, we can't read it diff --git a/SabreTools.IO/Matching/ContentMatch.cs b/SabreTools.IO/Matching/ContentMatch.cs index 0e2cecf..f7f35ca 100644 --- a/SabreTools.IO/Matching/ContentMatch.cs +++ b/SabreTools.IO/Matching/ContentMatch.cs @@ -30,6 +30,13 @@ namespace SabreTools.IO.Matching /// Byte array representing the search /// Optional starting position in the stack, defaults to 0 /// Optional ending position in the stack, defaults to -1 (length of stack) + /// + /// Thrown if has a length of 0. + /// + /// + /// Thrown if either or + /// are invalid. + /// public ContentMatch(byte[] needle, int start = 0, int end = -1) { // Validate the inputs @@ -51,6 +58,13 @@ namespace SabreTools.IO.Matching /// Nullable byte array representing the search /// Optional starting position in the stack, defaults to 0 /// Optional ending position in the stack, defaults to -1 (length of stack) + /// + /// Thrown if has a length of 0. + /// + /// + /// Thrown if either or + /// are invalid. + /// public ContentMatch(byte?[] needle, int start = 0, int end = -1) { // Validate the inputs diff --git a/SabreTools.IO/Matching/ContentMatchSet.cs b/SabreTools.IO/Matching/ContentMatchSet.cs index 5e720bc..45cb96e 100644 --- a/SabreTools.IO/Matching/ContentMatchSet.cs +++ b/SabreTools.IO/Matching/ContentMatchSet.cs @@ -54,6 +54,9 @@ namespace SabreTools.IO.Matching /// /// List of ContentMatch objects representing the comparisons /// Unique name for the set + /// + /// Thrown if is empty. + /// public ContentMatchSet(List needles, string setName) { // Validate the inputs @@ -85,6 +88,9 @@ namespace SabreTools.IO.Matching /// List of ContentMatch objects representing the comparisons /// Delegate for deriving a version on match of an array /// Unique name for the set + /// + /// Thrown if is empty. + /// public ContentMatchSet(List needles, GetArrayVersion getVersion, string setName) { // Validate the inputs @@ -116,6 +122,9 @@ namespace SabreTools.IO.Matching /// List of ContentMatch objects representing the comparisons /// Delegate for deriving a version on match of a Stream /// Unique name for the set + /// + /// Thrown if is empty. + /// public ContentMatchSet(List needles, GetStreamVersion getVersion, string setName) { // Validate the inputs diff --git a/SabreTools.IO/Matching/PathMatch.cs b/SabreTools.IO/Matching/PathMatch.cs index 6e43a39..8f29f65 100644 --- a/SabreTools.IO/Matching/PathMatch.cs +++ b/SabreTools.IO/Matching/PathMatch.cs @@ -30,6 +30,9 @@ namespace SabreTools.IO.Matching /// String representing the search /// True to match exact casing, false otherwise /// True to match the end only, false for contains + /// + /// Thrown if has a length of 0. + /// public PathMatch(string needle, bool matchCase = false, bool useEndsWith = false) { // Validate the inputs diff --git a/SabreTools.IO/Matching/PathMatchSet.cs b/SabreTools.IO/Matching/PathMatchSet.cs index 58a87d5..77d4006 100644 --- a/SabreTools.IO/Matching/PathMatchSet.cs +++ b/SabreTools.IO/Matching/PathMatchSet.cs @@ -41,6 +41,9 @@ namespace SabreTools.IO.Matching /// /// List of PathMatch objects representing the comparisons /// Unique name for the set + /// + /// Thrown if is empty. + /// public PathMatchSet(List needles, string setName) { // Validate the inputs @@ -71,6 +74,9 @@ namespace SabreTools.IO.Matching /// List of PathMatch objects representing the comparisons /// Delegate for deriving a version on match /// Unique name for the set + /// + /// Thrown if is empty. + /// public PathMatchSet(List needles, GetPathVersion getVersion, string setName) { // Validate the inputs diff --git a/SabreTools.IO/Readers/IniReader.cs b/SabreTools.IO/Readers/IniReader.cs index 53291f5..1df026e 100644 --- a/SabreTools.IO/Readers/IniReader.cs +++ b/SabreTools.IO/Readers/IniReader.cs @@ -103,6 +103,10 @@ namespace SabreTools.IO.Readers /// /// Process the current line and extract out values /// + /// + /// Thrown if an invalid line is encountered during processing + /// and is true. + /// private void ProcessLine() { if (CurrentLine is null) diff --git a/SabreTools.IO/Readers/SeparatedValueReader.cs b/SabreTools.IO/Readers/SeparatedValueReader.cs index 4770654..848d17c 100644 --- a/SabreTools.IO/Readers/SeparatedValueReader.cs +++ b/SabreTools.IO/Readers/SeparatedValueReader.cs @@ -102,6 +102,12 @@ namespace SabreTools.IO.Readers /// /// Read the header line /// + /// + /// + /// Thrown if either: + /// - A header line is requested when is false. + /// - A header line has already been read when is true. + /// public bool ReadHeader() { if (!Header) @@ -116,6 +122,10 @@ namespace SabreTools.IO.Readers /// /// Read the next line in the separated value file /// + /// + /// Thrown if an malformed line is encountered during processing + /// and is true. + /// public bool ReadNextLine() { if (_reader.BaseStream is null) @@ -178,36 +188,44 @@ namespace SabreTools.IO.Readers /// /// Get the value for the current line for the current key /// + /// Case-sensitive key based on header values + /// Value associated with the key, null if the key doesn't exist + /// + /// Thrown if any required properties are missing. + /// public string? GetValue(string key) { // No header means no key-based indexing if (!Header) - throw new ArgumentException("No header expected so no keys can be used"); + throw new InvalidDataException("No header expected so no keys can be used"); // If we don't have the key, return null if (HeaderValues is null) - throw new ArgumentException($"Current line doesn't have key {key}"); + throw new InvalidDataException($"Current line doesn't have key {key}"); if (!HeaderValues.Contains(key)) return null; int index = HeaderValues.IndexOf(key); - if (Line is null) - throw new ArgumentException($"Current line doesn't have index {index}"); - if (Line.Count < index) - throw new ArgumentException($"Current line doesn't have index {index}"); - - return Line[index]; + return GetValue(index); } /// /// Get the value for the current line for the current index /// + /// Index into the current line + /// Value associated with the index + /// + /// Thrown if is greater than the line count. + /// + /// + /// Thrown if any required properties are missing. + /// public string GetValue(int index) { if (Line is null) - throw new ArgumentException($"Current line doesn't have index {index}"); + throw new InvalidDataException($"Current line doesn't have index {index}"); if (Line.Count < index) - throw new ArgumentException($"Current line doesn't have index {index}"); + throw new ArgumentOutOfRangeException($"Current line doesn't have index {index}"); return Line[index]; } diff --git a/SabreTools.IO/Streams/ReadOnlyBitStream.cs b/SabreTools.IO/Streams/ReadOnlyBitStream.cs index 8bb3b39..f0142f3 100644 --- a/SabreTools.IO/Streams/ReadOnlyBitStream.cs +++ b/SabreTools.IO/Streams/ReadOnlyBitStream.cs @@ -1,4 +1,4 @@ -using System; +using System.Data; using System.IO; using SabreTools.IO.Extensions; @@ -33,6 +33,11 @@ namespace SabreTools.IO.Streams /// /// Create a new BitStream from a source Stream /// + /// Source stream + /// + /// Thrown if is either marked + /// as unreadable or non-seekable. + /// public ReadOnlyBitStream(Stream source) { _source = source; @@ -41,7 +46,7 @@ namespace SabreTools.IO.Streams // Verify the stream if (!source.CanRead || !source.CanSeek) - throw new ArgumentException($"{nameof(source)} needs to be readable and seekable"); + throw new DataException($"{nameof(source)} needs to be readable and seekable"); } /// diff --git a/SabreTools.IO/Streams/ReadOnlyCompositeStream.cs b/SabreTools.IO/Streams/ReadOnlyCompositeStream.cs index 8d2e2f6..057cffa 100644 --- a/SabreTools.IO/Streams/ReadOnlyCompositeStream.cs +++ b/SabreTools.IO/Streams/ReadOnlyCompositeStream.cs @@ -1,5 +1,6 @@ using System; using System.Collections.Generic; +using System.Data; using System.IO; namespace SabreTools.IO.Streams @@ -42,7 +43,7 @@ namespace SabreTools.IO.Streams #region Instance Variables /// - /// Internal collection of streams to read from + /// Internal set of streams to read from /// private readonly List _streams; @@ -73,7 +74,11 @@ namespace SabreTools.IO.Streams /// /// Create a new ReadOnlyCompositeStream from a single Stream /// - /// + /// Source stream + /// + /// Thrown if is either marked + /// as unreadable or non-seekable. + /// public ReadOnlyCompositeStream(Stream stream) { _streams = [stream]; @@ -82,14 +87,19 @@ namespace SabreTools.IO.Streams // Verify the stream and add to the length if (!stream.CanRead || !stream.CanSeek) - throw new ArgumentException($"{nameof(stream)} needs to be readable and seekable"); + throw new DataException($"{nameof(stream)} needs to be readable and seekable"); _length += stream.Length; } /// - /// Create a new ReadOnlyCompositeStream from an existing collection of Streams + /// Create a new ReadOnlyCompositeStream from an existing set of Streams /// + /// Set of streams + /// + /// Thrown if any stream in is + /// either marked as unreadable or non-seekable. + /// public ReadOnlyCompositeStream(Stream[] streams) { _streams = [.. streams]; @@ -100,15 +110,20 @@ namespace SabreTools.IO.Streams foreach (var stream in streams) { if (!stream.CanRead || !stream.CanSeek) - throw new ArgumentException($"All members of {nameof(streams)} need to be readable and seekable"); + throw new DataException($"All members of {nameof(streams)} need to be readable and seekable"); _length += stream.Length; } } /// - /// Create a new ReadOnlyCompositeStream from an existing collection of Streams + /// Create a new ReadOnlyCompositeStream from an existing set of Streams /// + /// Set of streams + /// + /// Thrown if any stream in is + /// either marked as unreadable or non-seekable. + /// public ReadOnlyCompositeStream(IEnumerable streams) { _streams = [.. streams]; @@ -130,7 +145,7 @@ namespace SabreTools.IO.Streams #region Data /// - /// Add a new stream to the collection + /// Add a new stream to the set /// public bool AddStream(Stream stream) { @@ -262,6 +277,14 @@ namespace SabreTools.IO.Streams /// /// Determines if a stream contains a particular segment /// + /// Index into the backing streams set + /// Offset in the stream to check + /// Length of data requested at the offset + /// True if the offset and length are valid, false otherwise + /// + /// Thrown if , , + /// or are invalid. + /// private bool StreamContains(int streamIndex, long offset, int length) { // Ensure the arguments are valid diff --git a/SabreTools.IO/Streams/ViewStream.cs b/SabreTools.IO/Streams/ViewStream.cs index 78d7d9f..7a596c2 100644 --- a/SabreTools.IO/Streams/ViewStream.cs +++ b/SabreTools.IO/Streams/ViewStream.cs @@ -102,16 +102,24 @@ namespace SabreTools.IO.Streams /// /// Construct a new ViewStream from a Stream /// - public ViewStream(Stream data, long offset) + /// Source stream + /// Offset in the source to use as the starting index + /// + /// Thrown if is not marked as readable. + /// + /// + /// Thrown if is invalid. + /// + public ViewStream(Stream source, long offset) { - if (!data.CanRead) - throw new ArgumentException(nameof(data)); - if (offset < 0 || offset > data.Length) + if (!source.CanRead) + throw new ArgumentException(nameof(source)); + if (offset < 0 || offset > source.Length) throw new ArgumentOutOfRangeException(nameof(offset)); - _source = data; + _source = source; _initialPosition = offset; - _length = data.Length - offset; + _length = source.Length - offset; _source.Seek(_initialPosition, SeekOrigin.Begin); } @@ -119,16 +127,25 @@ namespace SabreTools.IO.Streams /// /// Construct a new ViewStream from a Stream /// - public ViewStream(Stream data, long offset, long length) + /// Source stream + /// Offset in the source to use as the starting index + /// Length of the window + /// + /// Thrown if is not marked as readable. + /// + /// + /// Thrown if or are invalid. + /// + public ViewStream(Stream source, long offset, long length) { - if (!data.CanRead) - throw new ArgumentException(nameof(data)); - if (offset < 0 || offset > data.Length) + if (!source.CanRead) + throw new ArgumentException(nameof(source)); + if (offset < 0 || offset > source.Length) throw new ArgumentOutOfRangeException(nameof(offset)); - if (length < 0 || offset + length > data.Length) + if (length < 0 || offset + length > source.Length) throw new ArgumentOutOfRangeException(nameof(length)); - _source = data; + _source = source; _initialPosition = offset; _length = length; @@ -138,13 +155,18 @@ namespace SabreTools.IO.Streams /// /// Construct a new ViewStream from a byte array /// - public ViewStream(byte[] data, long offset) + /// Source array + /// Offset in the source to use as the starting index + /// + /// Thrown if is invalid. + /// + public ViewStream(byte[] source, long offset) { - if (offset < 0 || offset > data.Length) + if (offset < 0 || offset > source.Length) throw new ArgumentOutOfRangeException(nameof(offset)); - long length = data.Length - offset; - _source = new MemoryStream(data, (int)offset, (int)length); + long length = source.Length - offset; + _source = new MemoryStream(source, (int)offset, (int)length); _initialPosition = 0; _length = length; @@ -154,14 +176,20 @@ namespace SabreTools.IO.Streams /// /// Construct a new ViewStream from a byte array /// - public ViewStream(byte[] data, long offset, long length) + /// Source array + /// Offset in the source to use as the starting index + /// Length of the window + /// + /// Thrown if or are invalid. + /// + public ViewStream(byte[] source, long offset, long length) { - if (offset < 0 || offset > data.Length) + if (offset < 0 || offset > source.Length) throw new ArgumentOutOfRangeException(nameof(offset)); - if (length < 0 || offset + length > data.Length) + if (length < 0 || offset + length > source.Length) throw new ArgumentOutOfRangeException(nameof(length)); - _source = new MemoryStream(data, (int)offset, (int)length); + _source = new MemoryStream(source, (int)offset, (int)length); _initialPosition = 0; _length = length; diff --git a/SabreTools.IO/Transform/Combine.cs b/SabreTools.IO/Transform/Combine.cs index 86fc585..fe2468f 100644 --- a/SabreTools.IO/Transform/Combine.cs +++ b/SabreTools.IO/Transform/Combine.cs @@ -113,6 +113,9 @@ namespace SabreTools.IO.Transform /// Path to the output file /// representing how to process the inputs /// A filled stream on success, null otherwise + /// + /// Thrown if is not a recognized value. + /// public static Stream? Interleave(Stream even, Stream odd, BlockSize type) { // If either stream is unreadable diff --git a/SabreTools.IO/Transform/Split.cs b/SabreTools.IO/Transform/Split.cs index 2619660..d16f827 100644 --- a/SabreTools.IO/Transform/Split.cs +++ b/SabreTools.IO/Transform/Split.cs @@ -69,6 +69,9 @@ namespace SabreTools.IO.Transform /// Even block output stream on success, null otherwise /// Odd block output stream on success, null otherwise /// True if the stream could be split, false otherwise + /// + /// Thrown if is not a recognized value. + /// public static bool BlockSplit(Stream input, BlockSize type, out Stream? even, out Stream? odd) { // Set default values for the outputs diff --git a/SabreTools.IO/Transform/Swap.cs b/SabreTools.IO/Transform/Swap.cs index 98f1fb1..4277dfd 100644 --- a/SabreTools.IO/Transform/Swap.cs +++ b/SabreTools.IO/Transform/Swap.cs @@ -59,6 +59,9 @@ namespace SabreTools.IO.Transform /// Input stream /// Transform operation to carry out /// True if the file was transformed properly, false otherwise + /// + /// Thrown if is not a recognized value. + /// public static Stream? Process(Stream input, Operation operation) { // If the stream is unreadable diff --git a/SabreTools.IO/Writers/ClrMameProWriter.cs b/SabreTools.IO/Writers/ClrMameProWriter.cs index f632bc5..29b79c6 100644 --- a/SabreTools.IO/Writers/ClrMameProWriter.cs +++ b/SabreTools.IO/Writers/ClrMameProWriter.cs @@ -182,10 +182,10 @@ namespace SabreTools.IO.Writers _writer.Write(name); _writer.Write(" ("); } - catch + catch (Exception ex) { _currentState = State.Error; - throw; + throw ex; } } @@ -223,10 +223,10 @@ namespace SabreTools.IO.Writers if ((quoteOverride is null && Quotes) || (quoteOverride == true)) _writer.Write("\""); } - catch + catch (Exception ex) { _currentState = State.Error; - throw; + throw ex; } } @@ -239,10 +239,10 @@ namespace SabreTools.IO.Writers { AutoComplete(Token.EndAttribute, quoteOverride); } - catch + catch (Exception ex) { _currentState = State.Error; - throw; + throw ex; } } @@ -266,6 +266,10 @@ namespace SabreTools.IO.Writers /// Value to write in the attribute /// Non-null to overwrite the writer setting, null otherwise /// Indicates if an error should be thrown on a missing required value + /// + /// Thrown if is true and + /// is null. + /// public void WriteRequiredAttributeString(string name, string? value, bool? quoteOverride = null, bool throwOnError = false) { // Throw an exception if we are configured to @@ -293,6 +297,9 @@ namespace SabreTools.IO.Writers /// Name of the attribute /// Value to write in the attribute /// Non-null to overwrite the writer setting, null otherwise + /// + /// Thrown if is null or empty. + /// public void WriteStandalone(string name, string? value, bool? quoteOverride = null) { try @@ -324,10 +331,10 @@ namespace SabreTools.IO.Writers _writer.Write("\""); } } - catch + catch (Exception ex) { _currentState = State.Error; - throw; + throw ex; } } @@ -338,6 +345,10 @@ namespace SabreTools.IO.Writers /// Value to write in the attribute /// Non-null to overwrite the writer setting, null otherwise /// Indicates if an error should be thrown on a missing required value + /// + /// Thrown if is true and + /// is null. + /// public void WriteRequiredStandalone(string name, string? value, bool? quoteOverride = null, bool throwOnError = false) { // Throw an exception if we are configured to @@ -377,10 +388,10 @@ namespace SabreTools.IO.Writers _writer.Write(value); } } - catch + catch (Exception ex) { _currentState = State.Error; - throw; + throw ex; } } @@ -415,6 +426,11 @@ namespace SabreTools.IO.Writers /// /// Prepare for the next token to be written /// + /// Last token to have been processed + /// Non-null to overwrite the writer setting, null otherwise + /// + /// Thrown if the state of the writer is invalid. + /// private void AutoComplete(Token token, bool? quoteOverride = null) { // Handle the error cases @@ -508,6 +524,7 @@ namespace SabreTools.IO.Writers /// /// Internal helper to write the end of an element /// + /// Determine if a full or truncated end element is written private void InternalWriteEndElement(bool longFormat) { try @@ -516,7 +533,7 @@ namespace SabreTools.IO.Writers throw new InvalidOperationException(); AutoComplete(longFormat ? Token.LongEndElement : Token.EndElement); - if (this._lastToken == Token.LongEndElement) + if (_lastToken == Token.LongEndElement) { Indent(true); _writer.Write(')'); @@ -524,10 +541,10 @@ namespace SabreTools.IO.Writers _topPtr--; } - catch + catch (Exception ex) { _currentState = State.Error; - throw; + throw ex; } } diff --git a/SabreTools.IO/Writers/IniWriter.cs b/SabreTools.IO/Writers/IniWriter.cs index 2f2855e..b6b6fc5 100644 --- a/SabreTools.IO/Writers/IniWriter.cs +++ b/SabreTools.IO/Writers/IniWriter.cs @@ -50,13 +50,17 @@ namespace SabreTools.IO.Writers /// /// Write a section tag /// + /// Value to use as the section tag + /// + /// Thrown if is null or empty. + /// public void WriteSection(string? value) { if (_writer.BaseStream is null) return; if (string.IsNullOrEmpty(value)) - throw new ArgumentException("Section tag cannot be null or empty", nameof(value)); + throw new ArgumentNullException("Section tag cannot be null or empty", nameof(value)); _writer.WriteLine($"[{value!.TrimStart('[').TrimEnd(']')}]"); } @@ -64,13 +68,16 @@ namespace SabreTools.IO.Writers /// /// Write a key value pair /// + /// + /// Thrown if is null or empty. + /// public void WriteKeyValuePair(string key, string? value) { if (_writer.BaseStream is null) return; if (string.IsNullOrEmpty(key)) - throw new ArgumentException("Key cannot be null or empty", nameof(key)); + throw new ArgumentNullException("Key cannot be null or empty", nameof(key)); value ??= string.Empty; _writer.WriteLine($"{key}={value}"); diff --git a/SabreTools.IO/Writers/SeparatedValueWriter.cs b/SabreTools.IO/Writers/SeparatedValueWriter.cs index 1fa03ac..f429177 100644 --- a/SabreTools.IO/Writers/SeparatedValueWriter.cs +++ b/SabreTools.IO/Writers/SeparatedValueWriter.cs @@ -1,4 +1,5 @@ using System; +using System.Data; using System.IO; using System.Text; @@ -96,11 +97,19 @@ namespace SabreTools.IO.Writers /// /// Write a value row /// + /// Array representing the values + /// True to append a newline, false otherwise + /// + /// Thrown if is an invalid character. + /// + /// + /// Thrown if the underlying stream is not marked as writable. + /// public void WriteValues(object?[] values, bool newline = true) { // If the writer can't be used, we error if (!_writer.BaseStream.CanWrite) - throw new ArgumentException(nameof(_writer)); + throw new DataException(nameof(_writer)); // If the separator character is invalid, we error if (Separator == default(char))