From c7537bd780dbf5ccd98c97bd0eca9a07ce7c41b2 Mon Sep 17 00:00:00 2001 From: rameel Date: Sat, 19 Sep 2026 23:29:24 +0500 Subject: [PATCH 1/3] docs: clarify descriptions and error messages --- README.md | 10 +-- src/Ramstack.Parsing/Character.cs | 4 +- .../GeneralUnicodeCategory.cs | 20 +++--- src/Ramstack.Parsing/Literal.Number.cs | 6 +- src/Ramstack.Parsing/Literal.cs | 2 +- src/Ramstack.Parsing/NumberKind.cs | 2 +- src/Ramstack.Parsing/ParseContext.cs | 4 +- src/Ramstack.Parsing/Parser.Between.cs | 4 +- src/Ramstack.Parsing/Parser.DefaultOnFail.cs | 10 +-- src/Ramstack.Parsing/Parser.Do.Generated.cs | 18 ++--- src/Ramstack.Parsing/Parser.Do.tt | 2 +- src/Ramstack.Parsing/Parser.Eol.cs | 4 +- src/Ramstack.Parsing/Parser.Fold.cs | 6 +- src/Ramstack.Parsing/Parser.Repeat.cs | 20 +++--- src/Ramstack.Parsing/Parser.Separated.cs | 12 ++-- src/Ramstack.Parsing/Parser.Seq.Generated.cs | 72 +++++++++---------- src/Ramstack.Parsing/Parser.Seq.tt | 8 +-- src/Ramstack.Parsing/Parser.Set.cs | 4 +- src/Ramstack.Parsing/Parser.Then.cs | 6 +- src/Ramstack.Parsing/Parser.ThenIgnore.cs | 6 +- .../Parser.UnicodeCategory.cs | 10 +-- src/Ramstack.Parsing/Parser.Until.cs | 26 +++---- src/Ramstack.Parsing/Parser.cs | 2 +- src/Ramstack.Parsing/Ramstack.Parsing.csproj | 2 +- src/Ramstack.Parsing/Utilities/BitVector`1.cs | 4 +- .../Utilities/CharClassExtensions.cs | 4 +- .../Utilities/CharClassParser.cs | 7 +- .../Utilities/CharClassParserTests.cs | 8 +-- 28 files changed, 134 insertions(+), 149 deletions(-) diff --git a/README.md b/README.md index d0c7dd8..6e4e25f 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ [![NuGet](https://img.shields.io/nuget/v/Ramstack.Parsing.svg)](https://nuget.org/packages/Ramstack.Parsing) [![MIT](https://img.shields.io/github/license/rameel/ramstack.parsing)](https://github.com/rameel/ramstack.parsing/blob/main/LICENSE) -A blazing-fast, lightweight, and intuitive parser combinator library for .NET. +A fast, lightweight parser combinator library for .NET. ## Getting Started -To install the `Ramstack.Parsing` [NuGet package](https://www.nuget.org/packages/Ramstack.Parsing) to your project, run the following command: +To add the `Ramstack.Parsing` [NuGet package](https://www.nuget.org/packages/Ramstack.Parsing) to your project, run: ```shell dotnet add package Ramstack.Parsing ``` @@ -59,7 +59,7 @@ private static Parser CreateParser() } ``` -As you can see, the parser is highly readable and easy to define. Using it is just as simple: +Use the parser as follows: ```csharp var result = Calc.Parse(expression); @@ -73,8 +73,8 @@ else Console.WriteLine(result.ErrorMessage); // - // result.ToString() prints the parsed value or an error message - // depending on the parsing status + // result.ToString() returns the parsed value as a string, + // or an error message if parsing fails. // // Console.WriteLine(result); // diff --git a/src/Ramstack.Parsing/Character.cs b/src/Ramstack.Parsing/Character.cs index c7112e8..77b5d41 100644 --- a/src/Ramstack.Parsing/Character.cs +++ b/src/Ramstack.Parsing/Character.cs @@ -13,12 +13,12 @@ public static class Character public static Parser Letter => L(GeneralUnicodeCategory.Letter).As("letter"); /// - /// Gets a parser that matches a single upper letter character. + /// Gets a parser that matches a single uppercase letter. /// public static Parser Uppercase => L(GeneralUnicodeCategory.UppercaseLetter).As("uppercase letter"); /// - /// Gets a parser that matches a single lower letter character. + /// Gets a parser that matches a single lowercase letter. /// public static Parser Lowercase => L(GeneralUnicodeCategory.LowercaseLetter).As("lowercase letter"); diff --git a/src/Ramstack.Parsing/GeneralUnicodeCategory.cs b/src/Ramstack.Parsing/GeneralUnicodeCategory.cs index 80e6982..99dcc43 100644 --- a/src/Ramstack.Parsing/GeneralUnicodeCategory.cs +++ b/src/Ramstack.Parsing/GeneralUnicodeCategory.cs @@ -36,7 +36,7 @@ public enum GeneralUnicodeCategory TitlecaseLetter = 1 << UnicodeCategory.TitlecaseLetter, /// - /// Modifier letter character, which is free-standing spacing character + /// Modifier letter character, which is a free-standing spacing character /// that indicates modifications of a preceding letter. /// Signified by the Unicode designation "Lm" (letter, modifier). /// @@ -70,20 +70,20 @@ public enum GeneralUnicodeCategory EnclosingMark = 1 << UnicodeCategory.EnclosingMark, /// - /// Decimal digit character, that is, a character in the range 0 through 9. + /// A decimal digit with a value from 0 to 9, including digits from non-Latin scripts. /// Signified by the Unicode designation "Nd" (number, decimal digit). /// DecimalDigitNumber = 1 << UnicodeCategory.DecimalDigitNumber, /// /// Number represented by a letter, instead of a decimal digit, - /// for example, the Roman numeral for five, which is "V". + /// for example, the Roman numeral five, "Ⅴ" (U+2164). /// The indicator is signified by the Unicode designation "Nl" (number, letter). /// LetterNumber = 1 << UnicodeCategory.LetterNumber, /// - /// Number that is neither a decimal digit nor a letter number, for example, the fraction 1/2. + /// Number that is neither a decimal digit nor a letter number, for example, the fraction "½" (U+00BD). /// The indicator is signified by the Unicode designation "No" (number, other). /// OtherNumber = 1 << UnicodeCategory.OtherNumber, @@ -178,7 +178,7 @@ public enum GeneralUnicodeCategory OtherPunctuation = 1 << UnicodeCategory.OtherPunctuation, /// - /// Mathematical symbol character, such as "+" or "= ". + /// Mathematical symbol character, such as "+" or "=". /// Signified by the Unicode designation "Sm" (symbol, math). /// MathSymbol = 1 << UnicodeCategory.MathSymbol, @@ -190,9 +190,7 @@ public enum GeneralUnicodeCategory CurrencySymbol = 1 << UnicodeCategory.CurrencySymbol, /// - /// Modifier symbol character, which indicates modifications of surrounding characters. - /// For example, the fraction slash indicates that the number to the left is the numerator - /// and the number to the right is the denominator. + /// Modifier symbol character, such as the circumflex accent "^" (U+005E). /// The indicator is signified by the Unicode designation "Sk" (symbol, modifier). /// ModifierSymbol = 1 << UnicodeCategory.ModifierSymbol, @@ -204,7 +202,7 @@ public enum GeneralUnicodeCategory OtherSymbol = 1 << UnicodeCategory.OtherSymbol, /// - /// Character that is not assigned to any Unicode category. + /// A code point that has not been assigned to a character. /// Signified by the Unicode designation "Cn" (other, not assigned). /// OtherNotAssigned = 1 << UnicodeCategory.OtherNotAssigned, @@ -263,7 +261,7 @@ public enum GeneralUnicodeCategory /// /// Represents any symbol category, including math, currency, modifier, and other symbols. - /// Signified by the Unicode designation "S" ("Sm", "Sc", "Sk", "So", ). + /// Signified by the Unicode designation "S" ("Sm", "Sc", "Sk", "So"). /// Symbol = MathSymbol @@ -272,7 +270,7 @@ public enum GeneralUnicodeCategory | OtherSymbol, /// - /// Represents any control category, including control, format, surrogate, private use, and other not assigned characters. + /// Includes control, format, surrogate, private-use, and unassigned code points. /// Signified by the Unicode designation "C" ("Cc", "Cf", "Cs", "Co", "Cn"). /// Other = diff --git a/src/Ramstack.Parsing/Literal.Number.cs b/src/Ramstack.Parsing/Literal.Number.cs index 7e4e972..2907ea8 100644 --- a/src/Ramstack.Parsing/Literal.Number.cs +++ b/src/Ramstack.Parsing/Literal.Number.cs @@ -41,7 +41,7 @@ public static Parser Number(string? name, NumberKind kind = NumberKind.Aut { return kind is NumberKind.Auto or NumberKind.Float ? new NumberLiteral(name ?? "floating-point number", NumberStyles.Float) - : throw new ArgumentException($"The number kind {kind} are not supported on floating-point types.", nameof(kind)); + : throw new ArgumentException($"Number kind {kind} is not supported for floating-point types.", nameof(kind)); } if (typeof(T) == typeof(sbyte) @@ -72,11 +72,11 @@ public static Parser Number(string? name, NumberKind kind = NumberKind.Aut #endif throw new ArgumentException( - $"The number kind {kind} are not supported on integer numeric types.", + $"Number kind {kind} is not supported for integer types.", nameof(kind)); } - throw new InvalidOperationException($"The specified type {typeof(T)} are not supported."); + throw new InvalidOperationException($"Type {typeof(T)} is not supported."); } private static int TryParseNumber(ref char span, int length, int p) diff --git a/src/Ramstack.Parsing/Literal.cs b/src/Ramstack.Parsing/Literal.cs index 199971c..5bfecde 100644 --- a/src/Ramstack.Parsing/Literal.cs +++ b/src/Ramstack.Parsing/Literal.cs @@ -1,6 +1,6 @@ namespace Ramstack.Parsing; /// -/// Provides parsers for parsing literal values such as booleans, numbers, strings, and characters. +/// Provides parsers for numbers, strings, characters, and escape sequences. /// public static partial class Literal; diff --git a/src/Ramstack.Parsing/NumberKind.cs b/src/Ramstack.Parsing/NumberKind.cs index 885866d..977f64e 100644 --- a/src/Ramstack.Parsing/NumberKind.cs +++ b/src/Ramstack.Parsing/NumberKind.cs @@ -6,7 +6,7 @@ namespace Ramstack.Parsing; public enum NumberKind { /// - /// Automatically determines the numeric type that can be parsed. + /// Selects the numeric format based on the target type. /// Auto, diff --git a/src/Ramstack.Parsing/ParseContext.cs b/src/Ramstack.Parsing/ParseContext.cs index b9df527..fc0d77d 100644 --- a/src/Ramstack.Parsing/ParseContext.cs +++ b/src/Ramstack.Parsing/ParseContext.cs @@ -217,7 +217,7 @@ public DiagnosticState SuppressDiagnostics() /// "Expected digit" or "Expected '.'". However, all these messages are eventually /// discarded in favor of a single top-level error from the float parser.

/// - /// By suppressing sub-parsers diagnostics and only producing a concise top-level message + /// By suppressing diagnostics from sub-parsers and only producing a concise top-level message /// like "(1:5) Expected float" we avoid unnecessary memory allocations and generally /// do less work, which ultimately improves performance. /// @@ -226,7 +226,7 @@ public DiagnosticState SuppressDiagnostics() /// /// var previousState = context.SuppressDiagnosticsIfNamed(Name); /// // ... parsing logic ... - /// context.RestoreDiagnostics(previousState); + /// context.RestoreDiagnosticState(previousState); /// /// public DiagnosticState SuppressDiagnosticsIfNamed(string? name) diff --git a/src/Ramstack.Parsing/Parser.Between.cs b/src/Ramstack.Parsing/Parser.Between.cs index 848299c..29f5a20 100644 --- a/src/Ramstack.Parsing/Parser.Between.cs +++ b/src/Ramstack.Parsing/Parser.Between.cs @@ -22,8 +22,8 @@ public static Parser Between(this Parser parser, Parser /// The type of the value produced by the main parser. - /// The type of the parser applied before the main parser (ignored in the final result). - /// The type of the parser applied after the main parser (ignored in the final result). + /// The type of value produced by the parser applied before the main parser (ignored in the final result). + /// The type of value produced by the parser applied after the main parser (ignored in the final result). /// The main parser whose result will be returned. /// The parser to apply before the main parser. /// The parser to apply after the main parser. diff --git a/src/Ramstack.Parsing/Parser.DefaultOnFail.cs b/src/Ramstack.Parsing/Parser.DefaultOnFail.cs index 8de6c32..691d0cd 100644 --- a/src/Ramstack.Parsing/Parser.DefaultOnFail.cs +++ b/src/Ramstack.Parsing/Parser.DefaultOnFail.cs @@ -4,14 +4,14 @@ partial class Parser { /// /// Creates an optional parser that always succeeds, returning the parsed value if successful, - /// or a default value of the if the specified parser fails. + /// or the default value of if the specified parser fails. /// /// The type of value produced by the initial parser. /// The parser to be treated as optional. - /// If this parser fails to parse, the method will return the default value of the type. + /// If parsing fails, the resulting parser returns the default value of . /// /// A parser that always succeeds, either by producing a value from the original parser - /// or by returning the default value of the . + /// or by returning the default value of . /// public static Parser DefaultOnFail(this Parser parser) => parser.DefaultOnFail(default!)!; @@ -22,7 +22,7 @@ partial class Parser /// /// The type of value produced by the initial parser. /// The parser to be treated as optional. - /// If this parser fails to parse, the method will return the default value of the type. + /// If parsing fails, the resulting parser returns . /// The default value to return if the specified parser fails to parse. /// /// A parser that always succeeds, either by producing a value from the initial parser @@ -44,7 +44,7 @@ public static Parser DefaultOnFail(this Parser parser, T defaultValue) /// /// The type of value produced by the initial parser. /// The parser to be treated as optional. - /// If this parser fails to parse, the method will return the default value of the type. + /// If parsing fails, the resulting parser returns . /// The default value to return if the initial parser fails to parse. private sealed class DefaultOnFailParser(Parser parser, T defaultValue) : Parser { diff --git a/src/Ramstack.Parsing/Parser.Do.Generated.cs b/src/Ramstack.Parsing/Parser.Do.Generated.cs index c369861..fb4ccc3 100644 --- a/src/Ramstack.Parsing/Parser.Do.Generated.cs +++ b/src/Ramstack.Parsing/Parser.Do.Generated.cs @@ -118,7 +118,7 @@ public static Parser Do /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser(Parser<(T1, T2)> parser, Func func) : Parser { /// @@ -151,7 +151,7 @@ protected internal override Parser ToVoidParser() => /// Represents a parser that applies a transformation function to the value produced by the specified parser. /// /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser(Parser<(T1, T2, T3)> parser, Func func) : Parser { /// @@ -184,7 +184,7 @@ protected internal override Parser ToVoidParser() => /// Represents a parser that applies a transformation function to the value produced by the specified parser. /// /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser(Parser<(T1, T2, T3, T4)> parser, Func func) : Parser { /// @@ -217,7 +217,7 @@ protected internal override Parser ToVoidParser() => /// Represents a parser that applies a transformation function to the value produced by the specified parser. /// /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser(Parser<(T1, T2, T3, T4, T5)> parser, Func func) : Parser { /// @@ -250,7 +250,7 @@ protected internal override Parser ToVoidParser() => /// Represents a parser that applies a transformation function to the value produced by the specified parser. /// /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser(Parser<(T1, T2, T3, T4, T5, T6)> parser, Func func) : Parser { /// @@ -283,7 +283,7 @@ protected internal override Parser ToVoidParser() => /// Represents a parser that applies a transformation function to the value produced by the specified parser. /// /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser(Parser<(T1, T2, T3, T4, T5, T6, T7)> parser, Func func) : Parser { /// @@ -316,7 +316,7 @@ protected internal override Parser ToVoidParser() => /// Represents a parser that applies a transformation function to the value produced by the specified parser. /// /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser(Parser<(T1, T2, T3, T4, T5, T6, T7, T8)> parser, Func func) : Parser { /// @@ -349,7 +349,7 @@ protected internal override Parser ToVoidParser() => /// Represents a parser that applies a transformation function to the value produced by the specified parser. /// /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser(Parser<(T1, T2, T3, T4, T5, T6, T7, T8, T9)> parser, Func func) : Parser { /// @@ -382,7 +382,7 @@ protected internal override Parser ToVoidParser() => /// Represents a parser that applies a transformation function to the value produced by the specified parser. /// /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser(Parser<(T1, T2, T3, T4, T5, T6, T7, T8, T9, T10)> parser, Func func) : Parser { /// diff --git a/src/Ramstack.Parsing/Parser.Do.tt b/src/Ramstack.Parsing/Parser.Do.tt index 3e63a3e..ff0b647 100644 --- a/src/Ramstack.Parsing/Parser.Do.tt +++ b/src/Ramstack.Parsing/Parser.Do.tt @@ -39,7 +39,7 @@ partial class Parser /// Represents a parser that applies a transformation function to the value produced by the specified parser. /// /// The parser whose output will be transformed. - /// The function used to transform the parser's output. + /// The function used to transform the parser's output. private sealed class DoParser<<#=GenerateGenericParameters(arity)#>, TResult>(Parser<(<#=GenerateGenericParameters(arity)#>)> parser, Func<<#=GenerateGenericParameters(arity)#>, TResult> func) : Parser { /// diff --git a/src/Ramstack.Parsing/Parser.Eol.cs b/src/Ramstack.Parsing/Parser.Eol.cs index 02aaf84..ae0934d 100644 --- a/src/Ramstack.Parsing/Parser.Eol.cs +++ b/src/Ramstack.Parsing/Parser.Eol.cs @@ -3,14 +3,14 @@ namespace Ramstack.Parsing; partial class Parser { /// - /// Gets a parser that matches the end of line. + /// Gets a parser that matches and consumes a line break, or succeeds at the end of input. /// public static Parser Eol { get; } = new EolParser(); #region Inner type: EolParser /// - /// Represents a parser that matches the end of line. + /// Represents a parser that matches and consumes a line break, or succeeds at the end of input. /// private sealed class EolParser() : Parser("end of line") { diff --git a/src/Ramstack.Parsing/Parser.Fold.cs b/src/Ramstack.Parsing/Parser.Fold.cs index 74f81dd..c60e806 100644 --- a/src/Ramstack.Parsing/Parser.Fold.cs +++ b/src/Ramstack.Parsing/Parser.Fold.cs @@ -35,7 +35,7 @@ public static Parser Fold(this Parser parser, Parser Math.Pow(l, r)); /// /// - /// The type of value produces by the main parser. + /// The type of value produced by the main parser. /// The type of the operator token produced by the parser. /// The main parser that matches a value. /// The operator parser that matches an operator token. @@ -51,7 +51,7 @@ public static Parser FoldR(this Parser parser, Parser /// Represents a left-associative parser. /// - /// The type of value produces by the main parser. + /// The type of value produced by the main parser. /// The type of the operator token produced by the parser. /// The main parser that matches a value. /// The operator parser that matches an operator token. @@ -105,7 +105,7 @@ protected internal override Parser ToVoidParser() /// /// Represents a right-associative parser. /// - /// The type of value produces by the main parser. + /// The type of value produced by the main parser. /// The type of the operator token produced by the parser. /// The main parser that matches a value. /// The operator parser that matches an operator token. diff --git a/src/Ramstack.Parsing/Parser.Repeat.cs b/src/Ramstack.Parsing/Parser.Repeat.cs index f5a322a..220c471 100644 --- a/src/Ramstack.Parsing/Parser.Repeat.cs +++ b/src/Ramstack.Parsing/Parser.Repeat.cs @@ -117,14 +117,14 @@ 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 between and times, inclusive. /// /// The type of the value produced by the specified parser. - /// The to apply the specified number of times. - /// Minimum number of repetitions. - /// Maximum number of repetitions. + /// The parser to apply repeatedly. + /// The minimum number of repetitions. + /// The maximum number of repetitions. /// - /// A parser that applies the specified parser a defined number of times. + /// A parser that applies the specified parser between and times, inclusive. /// public static Parser> Repeat(this Parser parser, int min, int max) { @@ -138,13 +138,13 @@ public static Parser> Repeat(this Parser parser, int min, int max) } /// - /// Creates a parser that applies the specified parser a defined number of times. + /// Creates a parser that applies the specified parser between and times, inclusive. /// - /// The to apply the specified number of times. - /// Minimum number of repetitions. - /// Maximum number of repetitions. + /// The parser to apply repeatedly. + /// The minimum number of repetitions. + /// The maximum number of repetitions. /// - /// A parser that applies the specified parser a defined number of times. + /// A parser that applies the specified parser between and times, inclusive. /// public static Parser Repeat(this Parser parser, int min, int max) { diff --git a/src/Ramstack.Parsing/Parser.Separated.cs b/src/Ramstack.Parsing/Parser.Separated.cs index bf5df24..f827ac4 100644 --- a/src/Ramstack.Parsing/Parser.Separated.cs +++ b/src/Ramstack.Parsing/Parser.Separated.cs @@ -9,10 +9,10 @@ partial class Parser /// The type of the value produced by the separator parser. /// The main parser. /// The parser that identifies the separators placed between the elements parsed by the main parser. - /// if trailing separator is allowed; otherwise, . + /// if a trailing separator is allowed; otherwise, . /// The minimum number of repetitions. /// The maximum number of repetitions. - /// /// + /// /// A parser that repeatedly applies the main parser, interleaved with the specified separator. /// public static Parser> Separated(this Parser parser, Parser separator, bool allowTrailing = false, int min = 0, int max = int.MaxValue) => @@ -26,7 +26,7 @@ public static Parser> Separated(this Parser parser, Pa /// The type of the value produced by the main parser. /// The main parser. /// The parser that identifies the separators placed between the elements parsed by the main parser. - /// if trailing separator is allowed; otherwise, . + /// if a trailing separator is allowed; otherwise, . /// The minimum number of repetitions. /// The maximum number of repetitions. private sealed class SeparatedParser(Parser parser, Parser separator, bool allowTrailing, int min, int max) : Parser> @@ -76,8 +76,8 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeparatorParser /// - /// Represents a specialized parser used as an optimization that discards the parsed result, - /// that repeatedly applies the main parser, interleaved with a separator specified by another parser. + /// Represents a parser that repeatedly applies the main parser with separators between matches + /// and discards the parsed values. /// private sealed class VoidSeparatedParser : Parser { @@ -92,7 +92,7 @@ private sealed class VoidSeparatedParser : Parser /// /// The main parser. /// The parser that identifies the separators placed between the elements parsed by the main parser. - /// if trailing separator is allowed; otherwise, . + /// if a trailing separator is allowed; otherwise, . /// The minimum number of repetitions. /// The maximum number of repetitions. public VoidSeparatedParser(Parser parser, Parser separator, bool allowTrailing, int min, int max) diff --git a/src/Ramstack.Parsing/Parser.Seq.Generated.cs b/src/Ramstack.Parsing/Parser.Seq.Generated.cs index 5d6cd18..32e7b43 100644 --- a/src/Ramstack.Parsing/Parser.Seq.Generated.cs +++ b/src/Ramstack.Parsing/Parser.Seq.Generated.cs @@ -14,7 +14,7 @@ namespace Ramstack.Parsing; partial class Parser { /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -25,7 +25,7 @@ partial class Parser new SeqParser(parser1, parser2); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -36,7 +36,7 @@ public static Parser Seq(Parser parser1, Parser parser2) => new VoidSeq2Parser(parser1, parser2); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -48,7 +48,7 @@ public static Parser Seq(Parser parser1, Parser parser2) => new SeqParser(parser1, parser2, parser3); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -60,7 +60,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new VoidSeq3Parser(parser1, parser2, parser3); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -73,7 +73,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new SeqParser(parser1, parser2, parser3, parser4); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -86,7 +86,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new VoidSeq4Parser(parser1, parser2, parser3, parser4); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -100,7 +100,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new SeqParser(parser1, parser2, parser3, parser4, parser5); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -114,7 +114,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new VoidSeq5Parser(parser1, parser2, parser3, parser4, parser5); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -129,7 +129,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new SeqParser(parser1, parser2, parser3, parser4, parser5, parser6); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -144,7 +144,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new VoidSeq6Parser(parser1, parser2, parser3, parser4, parser5, parser6); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -160,7 +160,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new SeqParser(parser1, parser2, parser3, parser4, parser5, parser6, parser7); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -176,7 +176,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new VoidSeq7Parser(parser1, parser2, parser3, parser4, parser5, parser6, parser7); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -193,7 +193,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new SeqParser(parser1, parser2, parser3, parser4, parser5, parser6, parser7, parser8); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -210,7 +210,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new VoidSeq8Parser(parser1, parser2, parser3, parser4, parser5, parser6, parser7, parser8); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -228,7 +228,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new SeqParser(parser1, parser2, parser3, parser4, parser5, parser6, parser7, parser8, parser9); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -246,7 +246,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new VoidSeq9Parser(parser1, parser2, parser3, parser4, parser5, parser6, parser7, parser8, parser9); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -265,7 +265,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse new SeqParser(parser1, parser2, parser3, parser4, parser5, parser6, parser7, parser8, parser9, parser10); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// /// The parser instance. /// The parser instance. @@ -286,7 +286,7 @@ public static Parser Seq(Parser parser1, Parser parser2, Parse #region Inner type: SeqParser /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser : Parser<(T1, T2)> { @@ -330,7 +330,7 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeq2Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq2Parser : Parser { @@ -369,7 +369,7 @@ public override bool TryParse(ref ParseContext context, out Unit value) #region Inner type: SeqParser /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser : Parser<(T1, T2, T3)> { @@ -416,7 +416,7 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeq3Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq3Parser : Parser { @@ -458,7 +458,7 @@ public override bool TryParse(ref ParseContext context, out Unit value) #region Inner type: SeqParser /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser : Parser<(T1, T2, T3, T4)> { @@ -508,7 +508,7 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeq4Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq4Parser : Parser { @@ -553,7 +553,7 @@ public override bool TryParse(ref ParseContext context, out Unit value) #region Inner type: SeqParser /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser : Parser<(T1, T2, T3, T4, T5)> { @@ -606,7 +606,7 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeq5Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq5Parser : Parser { @@ -654,7 +654,7 @@ public override bool TryParse(ref ParseContext context, out Unit value) #region Inner type: SeqParser /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser : Parser<(T1, T2, T3, T4, T5, T6)> { @@ -710,7 +710,7 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeq6Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq6Parser : Parser { @@ -761,7 +761,7 @@ public override bool TryParse(ref ParseContext context, out Unit value) #region Inner type: SeqParser /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser : Parser<(T1, T2, T3, T4, T5, T6, T7)> { @@ -820,7 +820,7 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeq7Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq7Parser : Parser { @@ -874,7 +874,7 @@ public override bool TryParse(ref ParseContext context, out Unit value) #region Inner type: SeqParser /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser : Parser<(T1, T2, T3, T4, T5, T6, T7, T8)> { @@ -936,7 +936,7 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeq8Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq8Parser : Parser { @@ -993,7 +993,7 @@ public override bool TryParse(ref ParseContext context, out Unit value) #region Inner type: SeqParser /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser : Parser<(T1, T2, T3, T4, T5, T6, T7, T8, T9)> { @@ -1058,7 +1058,7 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeq9Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq9Parser : Parser { @@ -1118,7 +1118,7 @@ public override bool TryParse(ref ParseContext context, out Unit value) #region Inner type: SeqParser /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser : Parser<(T1, T2, T3, T4, T5, T6, T7, T8, T9, T10)> { @@ -1186,7 +1186,7 @@ protected internal override Parser ToVoidParser() => #region Inner type: VoidSeq10Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq10Parser : Parser { diff --git a/src/Ramstack.Parsing/Parser.Seq.tt b/src/Ramstack.Parsing/Parser.Seq.tt index 71d9351..4f5fa42 100644 --- a/src/Ramstack.Parsing/Parser.Seq.tt +++ b/src/Ramstack.Parsing/Parser.Seq.tt @@ -22,7 +22,7 @@ partial class Parser } <#+ private void GenerateMethods(int arity) { #> /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// <#+ for (var n = 1; n <= arity; n++) { #> /// The parser instance. @@ -34,7 +34,7 @@ partial class Parser new SeqParser<<#=GenerateList(arity, n => $"T{n}", from: 1)#>>(<#=GenerateList(arity, n => $"parser{n}", from: 1, separator: ", ")#>); /// - /// Creates a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Creates a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// <#+ for (var n = 1; n <= arity; n++) { #> /// The parser instance. @@ -49,7 +49,7 @@ partial class Parser #region Inner type: SeqParser<<#=GenerateList(arity, n => $"T{n}", from: 1)#>> /// - /// Represents a parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class SeqParser<<#=GenerateList(arity, n => $"T{n}", from: 1)#>> : Parser<(<#=GenerateList(arity, n => $"T{n}", from: 1)#>)> { @@ -97,7 +97,7 @@ partial class Parser #region Inner type: VoidSeq<#=arity#>Parser /// - /// Represents a specialized parser that applies the specified parsers sequentially that succeeds only when all parsers succeed. + /// Represents a specialized parser that runs the specified parsers in sequence and succeeds only if they all succeed. /// private sealed class VoidSeq<#=arity#>Parser : Parser { diff --git a/src/Ramstack.Parsing/Parser.Set.cs b/src/Ramstack.Parsing/Parser.Set.cs index 3a6fab2..1da7d79 100644 --- a/src/Ramstack.Parsing/Parser.Set.cs +++ b/src/Ramstack.Parsing/Parser.Set.cs @@ -33,7 +33,7 @@ public static Parser Set(char lo, char hi) /// /// Creates a parser that matches any single character within the specified range set. - /// For example, use Set("a-z0-9") to parse any alphanumeric character. + /// For example, use Set("a-z0-9") to match a lowercase ASCII letter or an ASCII digit. /// /// /// The Set method supports a wide range of character classes and escape sequences, including: @@ -97,7 +97,7 @@ public static Parser Set(char lo, char hi) /// Anchors (e.g., ^, $, \A, \Z, \z, \G, \b, \B). /// /// - /// A string representing a character classes, e.g., "A-Za-z\p{Nd}". + /// A character class without surrounding square brackets, e.g., @"A-Za-z\p{Nd}". /// /// A parser that matches any single character within the specified range sets. /// diff --git a/src/Ramstack.Parsing/Parser.Then.cs b/src/Ramstack.Parsing/Parser.Then.cs index 43c8e2e..59f9ae4 100644 --- a/src/Ramstack.Parsing/Parser.Then.cs +++ b/src/Ramstack.Parsing/Parser.Then.cs @@ -4,7 +4,7 @@ partial class Parser { /// /// Creates a parser that sequentially applies the current parser and a specified second parser, - /// returning the result of the second parser with ignoring the result of the first. + /// returning the result of the second parser while discarding the result of the first. /// /// The type of the value produced by the first parser, which is ignored. /// The type of the value produced by the second parser. @@ -12,7 +12,7 @@ partial class Parser /// The subsequent parser whose result is returned. /// /// A parser that sequentially applies the current parser and a specified second parser, - /// returning the result of the second parser with ignoring the result of the first. + /// returning the result of the second parser while discarding the result of the first. /// public static Parser Then(this Parser parser, Parser then) => new ThenParser(parser.Void(), then); @@ -21,7 +21,7 @@ public static Parser Then(this Parser parser, Parser /// Represents a parser that sequentially applies an initial parser and a specified second parser, - /// returning the result of the second parser with ignoring the result of the first. + /// returning the result of the second parser while discarding the result of the first. /// /// The type of the value produced by the second parser. /// The initial parser. diff --git a/src/Ramstack.Parsing/Parser.ThenIgnore.cs b/src/Ramstack.Parsing/Parser.ThenIgnore.cs index 9580faa..b68c011 100644 --- a/src/Ramstack.Parsing/Parser.ThenIgnore.cs +++ b/src/Ramstack.Parsing/Parser.ThenIgnore.cs @@ -4,7 +4,7 @@ partial class Parser { /// /// Creates a parser that sequentially applies the current parser and a specified second parser, - /// returning the result of the first parser with ignoring the result of the second. + /// returning the result of the first parser while discarding the result of the second. /// /// The type of the value produced by the first parser. /// The type of the value produced by the second parser, which is ignored. @@ -12,7 +12,7 @@ partial class Parser /// The subsequent parser, applied after the initial parser. /// /// A parser that sequentially applies the current parser and a specified second parser, - /// returning the result of the first parser with ignoring the result of the second. + /// returning the result of the first parser while discarding the result of the second. /// public static Parser ThenIgnore(this Parser parser, Parser ignore) => new ThenIgnoreParser(parser, ignore.Void()); @@ -21,7 +21,7 @@ public static Parser ThenIgnore(this Parser parser /// /// Represents a parser that sequentially applies an initial parser and a specified second parser, - /// returning the result of the first parser with ignoring the result of the second. + /// returning the result of the first parser while discarding the result of the second. /// /// The type of the value produced by the first parser. /// The initial parser whose result is returned. diff --git a/src/Ramstack.Parsing/Parser.UnicodeCategory.cs b/src/Ramstack.Parsing/Parser.UnicodeCategory.cs index f4658cd..2df93a1 100644 --- a/src/Ramstack.Parsing/Parser.UnicodeCategory.cs +++ b/src/Ramstack.Parsing/Parser.UnicodeCategory.cs @@ -3,21 +3,21 @@ namespace Ramstack.Parsing; partial class Parser { /// - /// Creates a parser that matches the specified Unicode category of the character. + /// Creates a parser that matches a character in the specified Unicode category. /// /// The of the character to match. /// - /// A parser that parses the specified Unicode category of the character. + /// A parser that matches a character in the specified Unicode category. /// public static Parser L(UnicodeCategory category) => L((GeneralUnicodeCategory)(1 << (int)category)); /// - /// Creates a parser that matches the specified Unicode categories of the character. + /// Creates a parser that matches a character in any of the specified Unicode categories. /// - /// The of the character to match. + /// The Unicode categories to match. /// - /// A parser that parses the specified Unicode categories of the character. + /// A parser that matches a character in any of the specified Unicode categories. /// public static Parser L(GeneralUnicodeCategory categories) { diff --git a/src/Ramstack.Parsing/Parser.Until.cs b/src/Ramstack.Parsing/Parser.Until.cs index 21ad72f..0719569 100644 --- a/src/Ramstack.Parsing/Parser.Until.cs +++ b/src/Ramstack.Parsing/Parser.Until.cs @@ -12,7 +12,8 @@ partial class Parser /// The parser that determines when to stop. /// /// A parser that applies zero or more times, stopping when - /// succeeds, and returns an array of the results produced by . + /// succeeds, and returns a list of the results produced by . + /// The terminator is not consumed. /// public static Parser> Until(this Parser parser, Parser terminator) => new UntilParser(parser, terminator.Void()); @@ -26,7 +27,8 @@ public static Parser> Until(this Parser parser, Parse /// The parser that determines when to stop. /// /// A parser that applies zero or more times, stopping when - /// succeeds, and returns an array of the results produced by . + /// succeeds, and returns a list of the results produced by . + /// The terminator is not consumed. /// public static Parser> Until(this Parser parser, Parser terminator) => new UntilParser(parser, terminator); @@ -70,14 +72,8 @@ public override bool TryParse(ref ParseContext context, [NotNullWhen(true)] out // if (context.Position == position) { - // - // Parsing failed in this case because: - // 1. The main parser matched, but the position remained unchanged. - // 2. The terminator didn't match before, and it won't match now. - // 3. Rechecking would yield the same result, making it redundant. - // 4. Without a terminator, parsing is considered unsuccessful, and it will never match now. - // 5. If a parser matches but the position remains unchanged, it results in an infinite loop. - // + // The parser succeeded without consuming input. + // Stop to avoid an infinite loop. break; } } @@ -129,14 +125,8 @@ public override bool TryParse(ref ParseContext context, out Unit value) // if (context.Position == position) { - // - // Parsing failed in this case because: - // 1. The main parser matched, but the position remained unchanged. - // 2. The terminator didn't match before, and it won't match now. - // 3. Rechecking would yield the same result, making it redundant. - // 4. Without a terminator, parsing is considered unsuccessful, and it will never match now. - // 5. If a parser matches but the position remains unchanged, it results in an infinite loop. - // + // The parser succeeded without consuming input. + // Stop to avoid an infinite loop. break; } } diff --git a/src/Ramstack.Parsing/Parser.cs b/src/Ramstack.Parsing/Parser.cs index de4c28c..19b0676 100644 --- a/src/Ramstack.Parsing/Parser.cs +++ b/src/Ramstack.Parsing/Parser.cs @@ -1,6 +1,6 @@ namespace Ramstack.Parsing; /// -/// Represents a helper class that provides a constructor functions and extension methods for the . +/// Provides factory methods and extension methods for . /// public static partial class Parser; diff --git a/src/Ramstack.Parsing/Ramstack.Parsing.csproj b/src/Ramstack.Parsing/Ramstack.Parsing.csproj index 4b1885a..e7368b3 100644 --- a/src/Ramstack.Parsing/Ramstack.Parsing.csproj +++ b/src/Ramstack.Parsing/Ramstack.Parsing.csproj @@ -2,7 +2,7 @@ net6.0;net7.0;net8.0;net9.0 - A blazing-fast, lightweight, and intuitive parser combinator library for .NET + A fast, lightweight parser combinator library for .NET enable enable latest diff --git a/src/Ramstack.Parsing/Utilities/BitVector`1.cs b/src/Ramstack.Parsing/Utilities/BitVector`1.cs index 06f0379..a1a1568 100644 --- a/src/Ramstack.Parsing/Utilities/BitVector`1.cs +++ b/src/Ramstack.Parsing/Utilities/BitVector`1.cs @@ -51,12 +51,12 @@ ref Unsafe.As(ref Unsafe.AsRef(in _storage)), } /// - /// Returns an array of the object representing the internal bitset, + /// Returns an array of objects representing the internal bitset, /// applying the specified offset to each character value. /// /// The offset to apply to the character values. Must be non-negative. /// - /// An array of the object representing the characters indicated by the set bits + /// An array of objects representing the characters indicated by the set bits /// in the internal representation. /// public CharClassRange[] ToCharClassRanges(int offset) diff --git a/src/Ramstack.Parsing/Utilities/CharClassExtensions.cs b/src/Ramstack.Parsing/Utilities/CharClassExtensions.cs index e58a7b1..ce917b2 100644 --- a/src/Ramstack.Parsing/Utilities/CharClassExtensions.cs +++ b/src/Ramstack.Parsing/Utilities/CharClassExtensions.cs @@ -302,7 +302,7 @@ internal static string ToPrintable(this CharClass @class) /// /// Formats the specified character as a printable string. /// - /// The string buffer to append the formatted string. + /// The buffer to append the formatted string to. /// The character to format. /// The control characters that should be escaped. private static void Format(ref StringBuffer sb, char c, string controls = "") @@ -342,7 +342,7 @@ _ when controls.Contains(c) => "\\" + c, /// /// Formats the specified Unicode categories as a printable string. /// - /// The string buffer to append the formatted string. + /// The buffer to append the formatted string to. /// The Unicode categories to format. private static void Format(ref StringBuffer sb, GeneralUnicodeCategory category) { diff --git a/src/Ramstack.Parsing/Utilities/CharClassParser.cs b/src/Ramstack.Parsing/Utilities/CharClassParser.cs index f50daf0..0a7b033 100644 --- a/src/Ramstack.Parsing/Utilities/CharClassParser.cs +++ b/src/Ramstack.Parsing/Utilities/CharClassParser.cs @@ -47,10 +47,7 @@ bool ProcessCategory() if (end < 0) Error_InvalidPattern(pattern); - // I skipped adding support for named Unicode blocks (like \p{Hiragana}) - // since it seems many parser users don't need it. If I'm wrong about that, - // it can be fixed quickly - just a couple lines of code. For now though, - // range definitions can be used instead. + // Named Unicode blocks are not supported. Use explicit character ranges instead. // Unicode Block Names: https://www.unicode.org/Public/16.0.0/ucd/Blocks.txt var key = pattern[(p + 3)..end]; @@ -211,7 +208,7 @@ private static void Error_InvalidEscapeSequence(string pattern) => [DoesNotReturn] private static void Error_InvalidUnicodeSequence(string pattern) => - throw new ArgumentException($"Invalid pattern '{pattern}'. Unrecognized unicode sequence."); + throw new ArgumentException($"Invalid pattern '{pattern}'. Invalid Unicode escape sequence."); [DoesNotReturn] private static void Error_UnknownProperty(string pattern, string name) => diff --git a/tests/Ramstack.Parsing.Tests/Utilities/CharClassParserTests.cs b/tests/Ramstack.Parsing.Tests/Utilities/CharClassParserTests.cs index daf466f..c7d5c29 100644 --- a/tests/Ramstack.Parsing.Tests/Utilities/CharClassParserTests.cs +++ b/tests/Ramstack.Parsing.Tests/Utilities/CharClassParserTests.cs @@ -82,10 +82,10 @@ public void ParseTest(string set, string expected) [TestCase("\\p{Q}", "Invalid pattern '\\p{Q}'. Unknown property 'Q'.")] [TestCase("\\p{Lu", "Invalid pattern '\\p{Lu'.")] [TestCase("\\T", "Invalid pattern '\\T'. Unrecognized escape sequence.")] - [TestCase("\\ur234", "Invalid pattern '\\ur234'. Unrecognized unicode sequence.")] - [TestCase("\\u1r34", "Invalid pattern '\\u1r34'. Unrecognized unicode sequence.")] - [TestCase("\\u12r4", "Invalid pattern '\\u12r4'. Unrecognized unicode sequence.")] - [TestCase("\\u123r", "Invalid pattern '\\u123r'. Unrecognized unicode sequence.")] + [TestCase("\\ur234", "Invalid pattern '\\ur234'. Invalid Unicode escape sequence.")] + [TestCase("\\u1r34", "Invalid pattern '\\u1r34'. Invalid Unicode escape sequence.")] + [TestCase("\\u12r4", "Invalid pattern '\\u12r4'. Invalid Unicode escape sequence.")] + [TestCase("\\u123r", "Invalid pattern '\\u123r'. Invalid Unicode escape sequence.")] public void ParseTest_Invalid(string set, string message) { Assert.That( From 38073cd1424b6389149816413b07be465105ff40 Mon Sep 17 00:00:00 2001 From: rameel Date: Sun, 20 Sep 2026 00:31:54 +0500 Subject: [PATCH 2/3] parsers: align parentheses --- src/Ramstack.Parsing/Parser.Set.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Ramstack.Parsing/Parser.Set.cs b/src/Ramstack.Parsing/Parser.Set.cs index 1da7d79..34def3e 100644 --- a/src/Ramstack.Parsing/Parser.Set.cs +++ b/src/Ramstack.Parsing/Parser.Set.cs @@ -158,7 +158,7 @@ internal static Parser Set(CharClass @class) list.Add( ( comparisons: width != 0 ? (count + width - 1 & -width) >>> BitOperations.Log2((uint)width) : count, - consumption: width != 0 ? (count + width - 1) & -width : count, + consumption: width != 0 ? (count + width - 1 & -width) : count, parser: new RangeParser( new ContainsSearcher(@class.GetSymbols(simdAligned: true)), categories) { Name = name } From 54bb9c2ae06e5989db6e03ecff64844bda1a4b44 Mon Sep 17 00:00:00 2001 From: rameel Date: Sun, 20 Sep 2026 00:33:18 +0500 Subject: [PATCH 3/3] docs: clarify XML comments --- src/Ramstack.Parsing/Parser`1.cs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/Ramstack.Parsing/Parser`1.cs b/src/Ramstack.Parsing/Parser`1.cs index ec5cefd..b041973 100644 --- a/src/Ramstack.Parsing/Parser`1.cs +++ b/src/Ramstack.Parsing/Parser`1.cs @@ -29,8 +29,8 @@ protected Parser(string? name) => /// Attempts to parse the specified source text. Diagnostic messages are suppressed during this operation. /// /// The source text to parse. - /// When this method returns, contains the parsed result if the parsing was successful; - /// otherwise, . + /// When this method returns, contains the parsed value if parsing succeeded; + /// otherwise, the default value of . /// /// if the parser succeeded; otherwise, . /// @@ -107,8 +107,8 @@ public ParseResult Parse(ReadOnlySpan source) /// Attempts to parse the source text using the provided . /// /// The parse context containing the source text and position. - /// When this method returns, contains the parsed result if the parsing was successful; - /// otherwise, . + /// When this method returns, contains the parsed value if parsing succeeded; + /// otherwise, the default value of . /// /// if the parser succeeded; otherwise, . /// @@ -128,7 +128,7 @@ protected internal virtual Parser ToNamedParser(string? name) => /// Creates a parser that matches the input without capturing or storing the parsed result. /// /// - /// A lightweight instance that performs parsing without result allocation. + /// A parser that discards the parsed value. /// protected internal virtual Parser ToVoidParser() => this as Parser ?? new Parser.VoidParser(this) { Name = Name };