Added 'action' methods in BuilderPattern similar to Builder class and created Dockblocks

Author: MaestroError

README.md

@@ -61,10 +61,13 @@ Examples: `->dot("zeroOrMore")` `->exact("hello worls", false, "1+")`
 
 - Add benchmarks and tests for search against large data ✔️
 - Add Feature Tests for BuilderPattern ✔️
-- Add Dockblocs and comments for new methods
+- Remove need for "end" method in BuilderPattern ✔️
+- Add Dockblocs and comments for new methods ✔️
 
 - Add facade for Laravel
 - Wrap Builder in class for static start
+  - "string" and "source" for builder start
+  - "start" and "pattern" for builderPattern start
 - Write documentation (add credit for https://regexr.com/ and ChatGPT)
 
 - Implement string resolver pattern to use strings like "text(2)-digits()" (or "text:2-digits", or "text|2-digits") as pattern
@@ -74,3 +77,4 @@ Examples: `->dot("zeroOrMore")` `->exact("hello worls", false, "1+")`
 - Make options controllable from config or provider (?)
 - Make pattern controllable from config or provider (?)
 - I should be able to make new pattern using BuilderPattern
+- I should be able to make add custom pattern to the existing one using BuilderPattern

src/Builder.php

@@ -28,10 +28,24 @@ class Builder implements BuilderContract {
 
     use BuilderPatternMethods;
 
+    /**
+     * The string to be processed with regex.
+     */
     protected string $str;
+
+    /**
+     * The current pattern being applied.
+     */
     protected PatternContract $pattern;
+
+    /**
+     * Manages options for the current pattern.
+     */
     protected OptionsManager $manager;
 
+    /**
+     * List of available patterns.
+     */
     public array $patterns = 
     [
         TextOrNumbersPattern::class,
@@ -52,39 +66,69 @@ class Builder implements BuilderContract {
         FilePathWinPattern::class,
     ];
 
+    /**
+     * Constructs a new Builder instance.
+     *
+     * @param string $str The initial string to process with regex.
+     */
     public function __construct(string $str = "") {
         $this->str = $str;
         $this->manager = new OptionsManager();
         // @todo add patterns via config
     }
 
+    /**
+     * Processes an options array and applies it to the current pattern.
+     *
+     * @param array $options An associative array of options.
+     */
     protected function processConfigArray(array $options) {
         // Build options in options manager
         $this->manager->buildOptions($options);
         // Set used options to pattern
         $this->pattern->setOptions($this->manager->getUsedOptions());
     }
 
+    /**
+     * Processes a callback function to configure options.
+     *
+     * @param callable $callback A function that configures options using an OptionsBuilder.
+     */
     protected function processCallback(callable $callback) {
         $optionsBuilder = new OptionsBuilder();
         $callback($optionsBuilder);
         $this->processConfigArray($optionsBuilder->getOptions());
     }
 
+    /**
+     * Validates the current string as an exact match against the current pattern.
+     *
+     * @return bool True if the string is an exact match, false otherwise.
+     */
     protected function validateAsInput(): bool {
         if (!$this->pattern->validateInput($this->str)) {
             return false;
         }
         return true;
     }
 
+    /**
+     * Validates if the current string contains any matches for the current pattern.
+     *
+     * @return bool True if the string contains matches, false otherwise.
+     */
     protected function validateAsString(): bool {
         if (!$this->pattern->validateMatches($this->str)) {
             return false;
         }
         return true;
     }
 
+    /**
+     * Retrieves all matches of the current pattern within the string.
+     *
+     * @return array|null An array of matches or null if no matches are found.
+     */
     protected function getAllMatches(): ?array {
         return $this->pattern->getMatches($this->str);
     }
@@ -157,11 +201,23 @@ public function setOptions(array|callable $config): void {
         } 
     }
 
+    /**
+     * Registers a single pattern in the Builder.
+     *
+     * @param PatternContract $pattern The pattern to register.
+     * @return self The Builder instance, for method chaining.
+     */
     public function registerPattern(PatternContract $pattern): self {
         $this->patterns[] = $pattern;
         return $this;
     }
 
+    /**
+     * Registers multiple patterns in the Builder.
+     *
+     * @param array $patterns An array of patterns to register.
+     * @return self The Builder instance, for method chaining.
+     */
     public function registerPatterns(array $patterns): self {
         foreach ($patterns as $pattern) {
             if (is_subclass_of($pattern, PatternContract::class)) {
@@ -173,10 +229,17 @@ public function registerPatterns(array $patterns): self {
         return $this;
     }
 
+    /**
+     * Retrieves the list of registered patterns.
+     *
+     * @return array An array of registered patterns.
+     */
     public function getPatterns(): array {
         return $this->patterns;
     }
 
+    // Expression flag methods:
+
     public function asCaseInsensitive(): self {
         $this->pattern->addExpressionFlag("i");
         return $this;
@@ -201,7 +264,17 @@ public function asSticky(): self {
         $this->pattern->addExpressionFlag("y");
         return $this;
     }
-    
+
+    /**
+     * Dynamically handles calls to pattern methods.
+     *
+     * This method is invoked when a method is called on the Builder that matches the name of a registered pattern.
+     *
+     * @param string $name The name of the method being called.
+     * @param array $args The arguments passed to the method.
+     * @return self The Builder instance, for method chaining.
+     * @throws \LogicException If no patterns are registered or the pattern name is not found.
+     */
     public function __call(
         $name,
         $args

src/Contracts/PatternContract.php

@@ -76,6 +76,12 @@ public function getInputValidationPattern(): string;
      */
     public function getMatchesValidationPattern(): string;
 
+    /**
+     * Adds regex flag to the pattern
+     * 
+     * @param string $flag to add after regex pattern
+     * @return void
+     */
     public function addExpressionFlag(string $flag): void;
 
     /**

src/Options/CharOption.php

@@ -53,7 +53,7 @@ private function checkSpecialChars(string $input) {
         return true;
     }
 
-    // Option methods
+    // Option methods:
     public function minSpecialCharacters(int $count) {
         $this->minSpecialCharacters = $count;
         return $this;

src/Patterns/BasePattern.php

@@ -27,12 +27,24 @@ class BasePattern implements PatternContract {
      */
     protected string $pattern = "[a-z]";
 
+    /**
+     * @var string Static property to define the pattern name.
+     */
     public static string $name = "";
 
+    /**
+     * @var array Static property to define the pattern arguments one by one.
+     */
     public static array $args = [];
 
+    /**
+     * @var array Static property to apply the default options for the pattern.
+     */
     public static array $defaultOptions = [];
 
+    /**
+     * @var string A string to hold expression flags for the regex pattern.
+     */
     protected string $expressionFlags = "";
 
     /**
@@ -169,6 +181,13 @@ public function getMatchesValidationPattern(): string {
         return "/{$this->pattern}/" . $this->expressionFlags;
     }
 
+    /**
+     * Processes an array of arguments and builds an options array.
+     *
+     * @param array $args Names of the arguments.
+     * @param array $values Values of the arguments.
+     * @return array An associative array of options.
+     */
     protected static function processArguments(array $args, array $values): array {
         $options = [];
         // Build options array based on condition
@@ -184,12 +203,23 @@ protected static function processArguments(array $args, array $values): array {
         return $options;
     }
 
+    /**
+     * Processes a callback function to configure options.
+     *
+     * @param callable $callback The callback function used for configuring options.
+     * @return array An associative array of options set by the callback.
+     */
     protected static function processCallback(callable $callback): array {
         $optionsBuilder = new OptionsBuilder();
         $callback($optionsBuilder);
         return $optionsBuilder->getOptions();
     }
 
+    /**
+     * Adds a regex expression flag to the pattern.
+     *
+     * @param string $flag The single-character flag to add to the regex pattern.
+     */
     public function addExpressionFlag(string $flag): void {
         if (strpos($this->expressionFlags, $flag) === false) {
             $this->expressionFlags .= $flag;