Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/Ramstack.Parsing/Argument.cs
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ public static void ThrowIfGreaterThanOrEqual<T>(T value, T other, [CallerArgumen
/// <summary>
/// Throws an <see cref="ArgumentOutOfRangeException"/> if <paramref name="value"/> is negative.
/// </summary>
/// <typeparam name="T">The type of the value being checked, which implements <see cref="IComparable{T}"/>.</typeparam>
/// <typeparam name="T">The type of the value being checked, which implements <see cref="System.Numerics.INumberBase{T}"/>.</typeparam>
/// <param name="value">The value to check.</param>
/// <param name="paramName">The name of the parameter being checked. Automatically supplied by the compiler.</param>
public static void ThrowIfNegative<T>(T value, [CallerArgumentExpression("value")] string? paramName = null) where T : struct, System.Numerics.INumberBase<T>
Expand All @@ -73,7 +73,7 @@ public static void ThrowIfNegative<T>(T value, [CallerArgumentExpression("value"
/// <summary>
/// Throws an <see cref="ArgumentOutOfRangeException"/> if <paramref name="value"/> is negative or zero.
/// </summary>
/// <typeparam name="T">The type of the value being checked, which implements <see cref="IComparable{T}"/>.</typeparam>
/// <typeparam name="T">The type of the value being checked, which implements <see cref="System.Numerics.INumberBase{T}"/>.</typeparam>
/// <param name="value">The value to check.</param>
/// <param name="paramName">The name of the parameter being checked. Automatically supplied by the compiler.</param>
public static void ThrowIfNegativeOrZero<T>(T value, [CallerArgumentExpression("value")] string? paramName = null) where T : struct, System.Numerics.INumberBase<T>
Expand All @@ -85,7 +85,7 @@ public static void ThrowIfNegativeOrZero<T>(T value, [CallerArgumentExpression("
/// <summary>
/// Throws an <see cref="ArgumentOutOfRangeException"/> if <paramref name="value"/> is equal to <paramref name="other"/>.
/// </summary>
/// <typeparam name="T">The type of the values being compared, which implements <see cref="IEquatable{T}"/>.</typeparam>
/// <typeparam name="T">The type of the values being compared, which implements <see cref="System.Numerics.IEqualityOperators{TSelf,TOther,TResult}"/>.</typeparam>
/// <param name="value">The value to check.</param>
/// <param name="other">The reference value to compare against.</param>
/// <param name="paramName">The name of the parameter being checked. Automatically supplied by the compiler.</param>
Expand All @@ -98,7 +98,7 @@ public static void ThrowIfEqual<T>(T value, T other, [CallerArgumentExpression("
/// <summary>
/// Throws an <see cref="ArgumentOutOfRangeException"/> if <paramref name="value"/> is not equal to <paramref name="other"/>.
/// </summary>
/// <typeparam name="T">The type of the values being compared, which implements <see cref="IEquatable{T}"/>.</typeparam>
/// <typeparam name="T">The type of the values being compared, which implements <see cref="System.Numerics.IEqualityOperators{TSelf,TOther,TResult}"/>.</typeparam>
/// <param name="value">The value to check.</param>
/// <param name="other">The reference value to compare against.</param>
/// <param name="paramName">The name of the parameter being checked. Automatically supplied by the compiler.</param>
Expand Down
2 changes: 1 addition & 1 deletion src/Ramstack.Parsing/Literal.EscapeSequence.cs
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ partial class Literal
];

/// <summary>
/// Gets a parser that matches the escape sequence.
/// Gets a parser that matches an escape sequence and returns the decoded character.
/// </summary>
public static Parser<char> EscapeSequence { get; } = new EscapeSequenceParser<char>();

Expand Down
75 changes: 45 additions & 30 deletions src/Ramstack.Parsing/Parser.Repeat.cs
Original file line number Diff line number Diff line change
Expand Up @@ -71,58 +71,74 @@ public static Parser<Unit> Many(this Parser<Unit> parser) =>
Repeat(parser, 0, int.MaxValue);

/// <summary>
/// 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 <paramref name="count"/> times.
/// </summary>
/// <typeparam name="T">The type of the value produced by the specified parser.</typeparam>
/// <param name="parser">The <see cref="Parser{T}"/> to apply at least the specified number of times.</param>
/// <param name="count">The minimum number of repetitions.</param>
/// <param name="parser">The <see cref="Parser{T}"/> to apply at least <paramref name="count"/> times.</param>
/// <param name="count">The minimum number of repetitions. Must be non-negative.</param>
/// <returns>
/// A parser that applies the specified parser at least a defined number of times.
/// A parser that applies the specified parser at least <paramref name="count"/> times.
/// </returns>
public static Parser<List<T>> AtLeast<T>(this Parser<T> parser, int count) =>
Repeat(parser, count, int.MaxValue);
public static Parser<List<T>> AtLeast<T>(this Parser<T> parser, int count)
{
Argument.ThrowIfNegative(count);

return Repeat(parser, count, int.MaxValue);
}

/// <summary>
/// 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 <paramref name="count"/> times.
/// </summary>
/// <param name="parser">The <see cref="Parser{T}"/> to apply at least the specified number of times.</param>
/// <param name="count">The minimum number of repetitions.</param>
/// <param name="parser">The <see cref="Parser{T}"/> to apply at least <paramref name="count"/> times.</param>
/// <param name="count">The minimum number of repetitions. Must be non-negative.</param>
/// <returns>
/// A parser that applies the specified parser at least a defined number of times.
/// A parser that applies the specified parser at least <paramref name="count"/> times.
/// </returns>
public static Parser<Unit> AtLeast(this Parser<Unit> parser, int count) =>
Repeat(parser, count, int.MaxValue);
public static Parser<Unit> AtLeast(this Parser<Unit> parser, int count)
{
Argument.ThrowIfNegative(count);

return Repeat(parser, count, int.MaxValue);
}

/// <summary>
/// Creates a parser that applies the specified parser a defined number of times.
/// Creates a parser that applies the specified parser exactly <paramref name="count"/> times.
/// </summary>
/// <typeparam name="T">The type of the value produced by the specified parser.</typeparam>
/// <param name="parser">The <see cref="Parser{T}"/> to apply the specified number of times.</param>
/// <param name="count">The number of repetitions.</param>
/// <param name="count">The number of repetitions. Must be greater than zero.</param>
/// <returns>
/// A parser that applies the specified parser a defined number of times.
/// A parser that applies the specified parser exactly <paramref name="count"/> times.
/// </returns>
public static Parser<List<T>> Repeat<T>(this Parser<T> parser, int count) =>
Repeat(parser, count, count);
public static Parser<List<T>> Repeat<T>(this Parser<T> parser, int count)
{
Argument.ThrowIfNegativeOrZero(count);

return Repeat(parser, count, count);
}

/// <summary>
/// Creates a parser that applies the specified parser a defined number of times.
/// Creates a parser that applies the specified parser exactly <paramref name="count"/> times.
/// </summary>
/// <param name="parser">The <see cref="Parser{T}"/> to apply the specified number of times.</param>
/// <param name="count">The number of repetitions.</param>
/// <param name="count">The number of repetitions. Must be greater than zero.</param>
/// <returns>
/// A parser that applies the specified parser a defined number of times.
/// A parser that applies the specified parser exactly <paramref name="count"/> times.
/// </returns>
public static Parser<Unit> Repeat(this Parser<Unit> parser, int count) =>
Repeat(parser, count, count);
public static Parser<Unit> Repeat(this Parser<Unit> parser, int count)
{
Argument.ThrowIfNegativeOrZero(count);

return Repeat(parser, count, count);
}

/// <summary>
/// Creates a parser that applies the specified parser between <paramref name="min"/> and <paramref name="max"/> times, inclusive.
/// </summary>
/// <typeparam name="T">The type of the value produced by the specified parser.</typeparam>
/// <param name="parser">The parser to apply repeatedly.</param>
/// <param name="min">The minimum number of repetitions.</param>
/// <param name="max">The maximum number of repetitions.</param>
/// <param name="min">The minimum number of repetitions. Must be non-negative and no greater than <paramref name="max"/>.</param>
/// <param name="max">The maximum number of repetitions. Must be greater than zero.</param>
/// <returns>
/// A parser that applies the specified parser between <paramref name="min"/> and <paramref name="max"/> times, inclusive.
/// </returns>
Expand All @@ -141,8 +157,8 @@ public static Parser<List<T>> Repeat<T>(this Parser<T> parser, int min, int max)
/// Creates a parser that applies the specified parser between <paramref name="min"/> and <paramref name="max"/> times, inclusive.
/// </summary>
/// <param name="parser">The parser to apply repeatedly.</param>
/// <param name="min">The minimum number of repetitions.</param>
/// <param name="max">The maximum number of repetitions.</param>
/// <param name="min">The minimum number of repetitions. Must be non-negative and no greater than <paramref name="max"/>.</param>
/// <param name="max">The maximum number of repetitions. Must be greater than zero.</param>
/// <returns>
/// A parser that applies the specified parser between <paramref name="min"/> and <paramref name="max"/> times, inclusive.
/// </returns>
Expand Down Expand Up @@ -287,11 +303,10 @@ private static Parser<List<char>> CreateRepeatParser(CharClass @class, int min,
.parser;
}


#region Inner type: RepeatParser

/// <summary>
/// Represents a parser that applies the specified parser a defined number of times.
/// Represents a parser that applies another parser within specified repetition limits.
/// </summary>
/// <typeparam name="T">The type of the value produced by the specified parser.</typeparam>
private sealed class RepeatParser<T> : Parser<List<T>>
Expand All @@ -301,7 +316,7 @@ private sealed class RepeatParser<T> : Parser<List<T>>
private readonly int _max;

/// <summary>
/// Represents a parser that applies the specified parser a defined number of times.
/// Initializes a new instance of the <see cref="RepeatParser{T}"/> class.
/// </summary>
/// <param name="parser">The <see cref="Parser{T}"/> to be applied a specified number of times.</param>
/// <param name="min">The minimum number of repetitions.</param>
Expand Down Expand Up @@ -367,7 +382,7 @@ protected internal override Parser<Unit> ToVoidParser() =>

/// <summary>
/// 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.
/// </summary>
private sealed class VoidRepeatParser : Parser<Unit>
{
Expand Down
2 changes: 1 addition & 1 deletion src/Ramstack.Parsing/Parser.Set.cs
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ public static Parser<char> Set(char lo, char hi)
/// </item>
/// </list>
///
/// The following features are **not supported**:
/// The following features are <em>not supported</em>:
/// <list type="bullet">
/// <item><description>Named Unicode blocks (e.g., <c>\p{Cyrillic}</c>).</description></item>
/// <item><description>Negation within ranges (e.g., <c>^0-9</c>).</description></item>
Expand Down
8 changes: 7 additions & 1 deletion src/Ramstack.Parsing/Parser.Void.cs
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,14 @@ partial class Parser
/// <typeparam name="T">The type of the value produced by the parser.</typeparam>
/// <param name="parser">The parser to convert.</param>
/// <returns>
/// 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.
/// </returns>
/// <remarks>
/// Transformations whose results are discarded may be skipped, including callbacks passed to
/// <c>Map</c>, <c>Do</c>, <c>FoldL</c>, <c>FoldR</c>, and <c>Prefixed</c>.
/// Side effects and exceptions in skipped callbacks do not occur.
/// This also applies when a combinator discards a parser's result internally.
/// </remarks>
public static Parser<Unit> Void<T>(this Parser<T> parser) =>
parser as Parser<Unit> ?? parser.ToVoidParser();

Expand Down
9 changes: 9 additions & 0 deletions src/Ramstack.Parsing/Parser`1.cs
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ protected Parser(string? name) =>
/// through <see cref="Parser.Fail{T}(string)"/> or <see cref="Parser.FatalError(string)"/>.
/// </para>
/// <para>
/// A successful match may consume only a prefix of the source text.
/// To require the entire input to match, append <see cref="Parser.Eof"/> using <c>ThenIgnore</c>.
/// </para>
/// <para>
/// Exceptions thrown by user-provided functions, such as the callbacks passed to
/// <c>Map</c>, <c>Do</c>, or <c>FoldL</c>, are not suppressed and propagate to the caller.
/// Use <see cref="Parse(ReadOnlySpan{char})"/> to capture them in
Expand Down Expand Up @@ -74,6 +78,11 @@ public bool TryParse(ReadOnlySpan<char> source, [NotNullWhen(true)] out T? value
/// <returns>
/// A <see cref="ParseResult{T}"/> containing the parsed result or error information.
/// </returns>
/// <remarks>
/// A successful match may consume only a prefix of the source text.
/// To require the entire input to match, append <see cref="Parser.Eof"/> using <c>ThenIgnore</c>,
/// for example, <c>parser.ThenIgnore(Parser.Eof).Parse(source)</c>.
/// </remarks>
public ParseResult<T> Parse(ReadOnlySpan<char> source)
{
var context = new ParseContext(source);
Expand Down
Loading