From 26c3eef595f47cabab5d06c3eb138abd259f6ab0 Mon Sep 17 00:00:00 2001 From: rameel Date: Wed, 4 Nov 2026 00:14:26 +0500 Subject: [PATCH 1/2] docs: clarify XML comments and parser contracts --- src/Ramstack.Parsing/Argument.cs | 8 ++-- .../Literal.EscapeSequence.cs | 2 +- src/Ramstack.Parsing/Parser.Repeat.cs | 42 +++++++++---------- src/Ramstack.Parsing/Parser.Set.cs | 2 +- src/Ramstack.Parsing/Parser.Void.cs | 8 +++- src/Ramstack.Parsing/Parser`1.cs | 9 ++++ 6 files changed, 43 insertions(+), 28 deletions(-) diff --git a/src/Ramstack.Parsing/Argument.cs b/src/Ramstack.Parsing/Argument.cs index 11427b6..1d1bc5e 100644 --- a/src/Ramstack.Parsing/Argument.cs +++ b/src/Ramstack.Parsing/Argument.cs @@ -61,7 +61,7 @@ public static void ThrowIfGreaterThanOrEqual(T value, T other, [CallerArgumen /// /// Throws an if is negative. /// - /// The type of the value being checked, which implements . + /// The type of the value being checked, which implements . /// The value to check. /// The name of the parameter being checked. Automatically supplied by the compiler. public static void ThrowIfNegative(T value, [CallerArgumentExpression("value")] string? paramName = null) where T : struct, System.Numerics.INumberBase @@ -73,7 +73,7 @@ public static void ThrowIfNegative(T value, [CallerArgumentExpression("value" /// /// Throws an if is negative or zero. /// - /// The type of the value being checked, which implements . + /// The type of the value being checked, which implements . /// The value to check. /// The name of the parameter being checked. Automatically supplied by the compiler. public static void ThrowIfNegativeOrZero(T value, [CallerArgumentExpression("value")] string? paramName = null) where T : struct, System.Numerics.INumberBase @@ -85,7 +85,7 @@ public static void ThrowIfNegativeOrZero(T value, [CallerArgumentExpression(" /// /// Throws an if is equal to . /// - /// The type of the values being compared, which implements . + /// The type of the values being compared, which implements . /// The value to check. /// The reference value to compare against. /// The name of the parameter being checked. Automatically supplied by the compiler. @@ -98,7 +98,7 @@ public static void ThrowIfEqual(T value, T other, [CallerArgumentExpression(" /// /// Throws an if is not equal to . /// - /// The type of the values being compared, which implements . + /// The type of the values being compared, which implements . /// The value to check. /// The reference value to compare against. /// The name of the parameter being checked. Automatically supplied by the compiler. diff --git a/src/Ramstack.Parsing/Literal.EscapeSequence.cs b/src/Ramstack.Parsing/Literal.EscapeSequence.cs index e4f19b2..28cf9e4 100644 --- a/src/Ramstack.Parsing/Literal.EscapeSequence.cs +++ b/src/Ramstack.Parsing/Literal.EscapeSequence.cs @@ -146,7 +146,7 @@ partial class Literal ]; /// - /// Gets a parser that matches the escape sequence. + /// Gets a parser that matches an escape sequence and returns the decoded character. /// public static Parser EscapeSequence { get; } = new EscapeSequenceParser(); diff --git a/src/Ramstack.Parsing/Parser.Repeat.cs b/src/Ramstack.Parsing/Parser.Repeat.cs index b637b4c..1ade547 100644 --- a/src/Ramstack.Parsing/Parser.Repeat.cs +++ b/src/Ramstack.Parsing/Parser.Repeat.cs @@ -71,47 +71,47 @@ public static Parser Many(this Parser parser) => Repeat(parser, 0, int.MaxValue); /// - /// Creates a parser that applies the specified parser at least the defined number of times. + /// Creates a parser that applies the specified parser at least times. /// /// The type of the value produced by the specified parser. - /// The to apply at least the specified number of times. - /// The minimum number of repetitions. + /// The to apply at least times. + /// The minimum number of repetitions. Must be non-negative. /// - /// A parser that applies the specified parser at least a defined number of times. + /// A parser that applies the specified parser at least times. /// public static Parser> AtLeast(this Parser parser, int count) => Repeat(parser, count, int.MaxValue); /// - /// Creates a parser that applies the specified parser at least the specified number of times. + /// Creates a parser that applies the specified parser at least times. /// - /// The to apply at least the specified number of times. - /// The minimum number of repetitions. + /// The to apply at least times. + /// The minimum number of repetitions. Must be non-negative. /// - /// A parser that applies the specified parser at least a defined number of times. + /// A parser that applies the specified parser at least times. /// public static Parser AtLeast(this Parser parser, int count) => Repeat(parser, count, int.MaxValue); /// - /// Creates a parser that applies the specified parser a defined number of times. + /// Creates a parser that applies the specified parser exactly times. /// /// The type of the value produced by the specified parser. /// The to apply the specified number of times. - /// The number of repetitions. + /// The number of repetitions. Must be greater than zero. /// - /// A parser that applies the specified parser a defined number of times. + /// A parser that applies the specified parser exactly times. /// public static Parser> Repeat(this Parser parser, int count) => Repeat(parser, count, count); /// - /// Creates a parser that applies the specified parser a defined number of times. + /// Creates a parser that applies the specified parser exactly times. /// /// The to apply the specified number of times. - /// The number of repetitions. + /// The number of repetitions. Must be greater than zero. /// - /// A parser that applies the specified parser a defined number of times. + /// A parser that applies the specified parser exactly times. /// public static Parser Repeat(this Parser parser, int count) => Repeat(parser, count, count); @@ -121,8 +121,8 @@ public static Parser Repeat(this Parser parser, int count) => /// /// The type of the value produced by the specified parser. /// The parser to apply repeatedly. - /// The minimum number of repetitions. - /// The maximum number of repetitions. + /// The minimum number of repetitions. Must be non-negative and no greater than . + /// The maximum number of repetitions. Must be greater than zero. /// /// A parser that applies the specified parser between and times, inclusive. /// @@ -141,8 +141,8 @@ public static Parser> Repeat(this Parser parser, int min, int max) /// Creates a parser that applies the specified parser between and times, inclusive. /// /// The parser to apply repeatedly. - /// The minimum number of repetitions. - /// The maximum number of repetitions. + /// The minimum number of repetitions. Must be non-negative and no greater than . + /// The maximum number of repetitions. Must be greater than zero. /// /// A parser that applies the specified parser between and times, inclusive. /// @@ -291,7 +291,7 @@ private static Parser> CreateRepeatParser(CharClass @class, int min, #region Inner type: RepeatParser /// - /// Represents a parser that applies the specified parser a defined number of times. + /// Represents a parser that applies another parser within specified repetition limits. /// /// The type of the value produced by the specified parser. private sealed class RepeatParser : Parser> @@ -301,7 +301,7 @@ private sealed class RepeatParser : Parser> private readonly int _max; /// - /// Represents a parser that applies the specified parser a defined number of times. + /// Initializes a new instance of the class. /// /// The to be applied a specified number of times. /// The minimum number of repetitions. @@ -367,7 +367,7 @@ protected internal override Parser ToVoidParser() => /// /// Represents a specialized parser used as an optimization that discards the parsed result, - /// while applying the specified parser a defined number of times. + /// while applying another parser within specified repetition limits. /// private sealed class VoidRepeatParser : Parser { diff --git a/src/Ramstack.Parsing/Parser.Set.cs b/src/Ramstack.Parsing/Parser.Set.cs index be58430..b40ed4f 100644 --- a/src/Ramstack.Parsing/Parser.Set.cs +++ b/src/Ramstack.Parsing/Parser.Set.cs @@ -89,7 +89,7 @@ public static Parser Set(char lo, char hi) /// /// /// - /// The following features are **not supported**: + /// The following features are not supported: /// /// Named Unicode blocks (e.g., \p{Cyrillic}). /// Negation within ranges (e.g., ^0-9). diff --git a/src/Ramstack.Parsing/Parser.Void.cs b/src/Ramstack.Parsing/Parser.Void.cs index 53a54f6..89681c1 100644 --- a/src/Ramstack.Parsing/Parser.Void.cs +++ b/src/Ramstack.Parsing/Parser.Void.cs @@ -8,8 +8,14 @@ partial class Parser /// The type of the value produced by the parser. /// The parser to convert. /// - /// A parser instance that performs the same parsing as the original parser, but does not capture the result. + /// A parser that matches the input while discarding the parsed value. /// + /// + /// Transformations whose results are discarded may be skipped, including callbacks passed to + /// Map, Do, FoldL, FoldR, and Prefixed. + /// Side effects and exceptions in skipped callbacks do not occur. + /// This also applies when a combinator discards a parser's result internally. + /// public static Parser Void(this Parser parser) => parser as Parser ?? parser.ToVoidParser(); diff --git a/src/Ramstack.Parsing/Parser`1.cs b/src/Ramstack.Parsing/Parser`1.cs index b2d14da..eef1622 100644 --- a/src/Ramstack.Parsing/Parser`1.cs +++ b/src/Ramstack.Parsing/Parser`1.cs @@ -40,6 +40,10 @@ protected Parser(string? name) => /// through or . /// /// + /// A successful match may consume only a prefix of the source text. + /// To require the entire input to match, append using ThenIgnore. + /// + /// /// Exceptions thrown by user-provided functions, such as the callbacks passed to /// Map, Do, or FoldL, are not suppressed and propagate to the caller. /// Use to capture them in @@ -74,6 +78,11 @@ public bool TryParse(ReadOnlySpan source, [NotNullWhen(true)] out T? value /// /// A containing the parsed result or error information. /// + /// + /// A successful match may consume only a prefix of the source text. + /// To require the entire input to match, append using ThenIgnore, + /// for example, parser.ThenIgnore(Parser.Eof).Parse(source). + /// public ParseResult Parse(ReadOnlySpan source) { var context = new ParseContext(source); From f85ab67fafbc5cdc162ab3b01c9c9e5f26307b49 Mon Sep 17 00:00:00 2001 From: rameel Date: Wed, 4 Nov 2026 00:29:21 +0500 Subject: [PATCH 2/2] parsers: report the invalid count argument in Repeat and AtLeast --- src/Ramstack.Parsing/Parser.Repeat.cs | 33 +++++++++++++++++++-------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/src/Ramstack.Parsing/Parser.Repeat.cs b/src/Ramstack.Parsing/Parser.Repeat.cs index 1ade547..bd09577 100644 --- a/src/Ramstack.Parsing/Parser.Repeat.cs +++ b/src/Ramstack.Parsing/Parser.Repeat.cs @@ -79,8 +79,12 @@ public static Parser Many(this Parser parser) => /// /// A parser that applies the specified parser at least times. /// - public static Parser> AtLeast(this Parser parser, int count) => - Repeat(parser, count, int.MaxValue); + public static Parser> AtLeast(this Parser parser, int count) + { + Argument.ThrowIfNegative(count); + + return Repeat(parser, count, int.MaxValue); + } /// /// Creates a parser that applies the specified parser at least times. @@ -90,8 +94,12 @@ public static Parser> AtLeast(this Parser parser, int count) => /// /// A parser that applies the specified parser at least times. /// - public static Parser AtLeast(this Parser parser, int count) => - Repeat(parser, count, int.MaxValue); + public static Parser AtLeast(this Parser parser, int count) + { + Argument.ThrowIfNegative(count); + + return Repeat(parser, count, int.MaxValue); + } /// /// Creates a parser that applies the specified parser exactly times. @@ -102,8 +110,12 @@ public static Parser AtLeast(this Parser parser, int count) => /// /// A parser that applies the specified parser exactly times. /// - public static Parser> Repeat(this Parser parser, int count) => - Repeat(parser, count, count); + public static Parser> Repeat(this Parser parser, int count) + { + Argument.ThrowIfNegativeOrZero(count); + + return Repeat(parser, count, count); + } /// /// Creates a parser that applies the specified parser exactly times. @@ -113,8 +125,12 @@ public static Parser> Repeat(this Parser parser, int count) => /// /// A parser that applies the specified parser exactly times. /// - public static Parser Repeat(this Parser parser, int count) => - Repeat(parser, count, count); + public static Parser Repeat(this Parser parser, int count) + { + Argument.ThrowIfNegativeOrZero(count); + + return Repeat(parser, count, count); + } /// /// Creates a parser that applies the specified parser between and times, inclusive. @@ -287,7 +303,6 @@ private static Parser> CreateRepeatParser(CharClass @class, int min, .parser; } - #region Inner type: RepeatParser ///