Quantifier.cs

namespace ReadableRex.Patterns
{
    /// <summary>
    /// Provides methods to apply quantifiers to a regular expression pattern.
    /// </summary>
    /// <remarks>The <see cref="Quantifier"/> class allows you to specify how many times a pattern should be
    /// repeated in a regular expression. It supports exact, minimum, maximum, and range-based repetitions, as well as
    /// common quantifiers like zero or more, one or more, and optional. The class also provides a lazy quantifier
    /// option.</remarks>
    public class Quantifier
    {
        /// <summary>
        /// Represents a pattern that can be quantified in an expression.
        /// </summary>
        /// <remarks>This field is used to store a pattern that may be subject to quantification, such as
        /// repetition or optionality, within an expression. The specific behavior and usage of this pattern depend on
        /// the context in which it is applied.</remarks>
        readonly Pattern _quantifiedExpression;

        /// <summary>
        /// Represents a quantifier that applies to a specified pattern.
        /// </summary>
        /// <param name="quantifiedExpression">The pattern to which the quantifier is applied. Cannot be null.</param>
        internal Quantifier(Pattern quantifiedExpression)
        {
            _quantifiedExpression = quantifiedExpression;
        }

        /// <summary>
        /// Specifies that the preceding element in the pattern must occur exactly the specified number of times.
        /// </summary>
        /// <param name="timesToRepeat">The exact number of times the preceding element should be repeated. Must be a non-negative integer.</param>
        /// <returns>A <see cref="Pattern"/> object representing the modified pattern with the specified repetition constraint.</returns>
        public virtual Pattern Exactly(int timesToRepeat)
        {
            _quantifiedExpression.RegEx("{" + timesToRepeat + "}");
            return _quantifiedExpression;
        }

        /// <summary>
        /// Gets a pattern that matches zero or more occurrences of the current pattern.
        /// </summary>
        /// <remarks>This property returns a pattern that can be used to match zero or more repetitions of
        /// the  specified pattern. It is useful in scenarios where the presence of the pattern is optional  or can
        /// occur multiple times.</remarks>
        public virtual Pattern ZeroOrMore
        {
            get
            {
                _quantifiedExpression.RegEx("*");
                return _quantifiedExpression;
            }
        }

        /// <summary>
        /// Gets a pattern that matches one or more occurrences of the preceding element.
        /// </summary>
        /// <remarks>This property returns a pattern that applies the '+' quantifier to the preceding
        /// element, indicating that the element must appear at least once in the input.</remarks>
        public virtual Pattern OneOrMore
        {
            get
            {
                _quantifiedExpression.RegEx("+");
                return _quantifiedExpression;
            }
        }

        /// <summary>
        /// Gets a pattern that matches the preceding element zero or one time.
        /// </summary>
        /// <remarks>This property returns a pattern that applies the optional quantifier to the current
        /// expression, allowing the preceding element to appear zero or one time in the match.</remarks>
        public virtual Pattern Optional
        {
            get
            {
                _quantifiedExpression.RegEx("?");
                return _quantifiedExpression;
            }
        }

        /// <summary>
        /// Repeats the current pattern at least a specified number of times.
        /// </summary>
        /// <param name="timesToRepeat">The minimum number of times the pattern should be repeated. Must be a non-negative integer.</param>
        /// <returns>A <see cref="Pattern"/> representing the quantified expression that matches the pattern repeated at least
        /// the specified number of times.</returns>
        public virtual Pattern AtLeast(int timesToRepeat)
        {
            _quantifiedExpression.RegEx("{" + timesToRepeat + ",}");
            return _quantifiedExpression;
        }

        /// <summary>
        /// Repeats the current pattern at most a specified number of times.
        /// </summary>
        /// <param name="timesToRepeat"></param>
        /// <returns></returns>
        public virtual Pattern AtMost(int timesToRepeat)
        {
            _quantifiedExpression.RegEx("{," + timesToRepeat + "}");
            return _quantifiedExpression;
        }

        /// <summary>
        /// Specifies that the pattern should match a sequence that occurs between a minimum and maximum number of
        /// times.
        /// </summary>
        /// <param name="minimum">The minimum number of times the sequence must occur. Must be non-negative.</param>
        /// <param name="maximum">The maximum number of times the sequence can occur. Must be greater than or equal to <paramref
        /// name="minimum"/>.</param>
        /// <returns>A <see cref="Pattern"/> object representing the quantified expression.</returns>
        public virtual Pattern InRange(int minimum, int maximum)
        {
            _quantifiedExpression.RegEx("{" + minimum + "," + maximum + "}");
            return _quantifiedExpression;
        }

        /// <summary>
        /// Gets a lazy quantifier for the current quantified expression.
        /// </summary>
        public Quantifier Lazy
        {
            get
            {
                return new LazyQuantifier(_quantifiedExpression);
            }
        }
    }
}