Custom pattern section

Author: MaestroError

README.md

@@ -111,12 +111,14 @@ textOrNumbers(int $minLength, int $maxLength, int $minUppercase, int $minLowerca
 email(int $maxLength, array|string $onlyDomains, array|string $onlyExtensions)`
 ```
 
-````php
+```php
 url(array|string $onlyProtocol)`
+```
+
 ```php
 // $onlyDomains & $onlyExtensions array or string separated by comma "org,com"
 domainName(int $maxLength, array|string $onlyDomains, array|string $onlyExtensions)`
-````
+```
 
 ```php
 date()
@@ -153,7 +155,9 @@ password(int $minLength, int $minUppercase, int $minNumbers, int $minSpecialChar
 ```
 
 ```php
-// $restrictTags & $onlyTags array or string separated by comma `"script, style"`. It isn't recomended to use both option in simultaneously
+// $restrictTags & $onlyTags array or string
+// separated by comma `"script, style"`.
+// It isn't recomended to use both option simultaneously
 htmlTag(array|string $restrictTags, array|string $onlyTags)
 ```
 
@@ -171,6 +175,45 @@ filePath(int $isDirectory, bool $isFile, bool $fileExists,string $pathType) -
 filePathWin(int $isDirectory, bool $isFile, bool $fileExists)
 ```
 
+Didn't it cover all your needs? Let's take a look to the custom patterns section.
+
+## Custom Patterns
+
+For scenarios where predefined patterns do not suffice, EloquentRegex allows you to define custom patterns using the start or customPattern methods as initiator:
+
+```php
+EloquentRegex::start($yourString);
+// Or
+EloquentRegex::customPattern($yourString);
+```
+
+_Note: They does the exaclty same thing, you can use your favorite one_
+
+### Creating a Custom Pattern
+
+You can start building a custom pattern to match a specific string format, such as a custom ID format that starts with letters followed by digits:
+
+```php
+$result = EloquentRegex::start('ID123456')
+            ->literal('ID')
+            ->digitsRange(1, 10)
+            ->check();
+
+if ($result) {
+    echo "The string matches the custom ID format!";
+} else {
+    echo "The string does not match the custom ID format.";
+}
+
+```
+
+Custom pattern builder supports a wide range of character classes and all special chars. Also, `literal` or `exact` method could be used to match exact string you need, or `char` method could be used to match exact character. The full list of pattern builder methods is comming soon. Before that, you can check this files out:
+
+- [Character Classes](https://github.com/MaestroError/eloquent-regex/blob/documentation-and-examples/src/Traits/BuilderPatternTraits/CharacterClassesTrait.php)
+- [Special characters](https://github.com/MaestroError/eloquent-regex/blob/documentation-and-examples/src/Traits/BuilderPatternTraits/SpecificCharsTrait.php)
+- [Groups](https://github.com/MaestroError/eloquent-regex/blob/documentation-and-examples/src/Traits/BuilderPatternTraits/GroupsTrait.php)
+- [Anchors](https://github.com/MaestroError/eloquent-regex/blob/documentation-and-examples/src/Traits/BuilderPatternTraits/AnchorsTrait.php)
+
 #### Quantifiers
 
 Available values for quantifiers as argument:

src/Patterns/BuilderPattern.php

@@ -7,13 +7,14 @@
 use Maestroerror\EloquentRegex\Traits\BuilderPatternTraits\CharacterClassesTrait;
 use Maestroerror\EloquentRegex\Traits\BuilderPatternTraits\SpecificCharsTrait;
 use Maestroerror\EloquentRegex\Traits\BuilderPatternTraits\AnchorsTrait;
+use Maestroerror\EloquentRegex\Traits\BuilderPatternTraits\GroupsTrait;
 use Maestroerror\EloquentRegex\Builder;
 
 
 class BuilderPattern extends BasePattern {
 
     // BuilderPattern doesn't need the "execute" method (src\Traits\Pattern.php)
-    use CharacterClassesTrait, SpecificCharsTrait, AnchorsTrait;
+    use CharacterClassesTrait, SpecificCharsTrait, AnchorsTrait, GroupsTrait;
 
     /**
      * @var array Array of options for the pattern.
@@ -174,147 +175,5 @@ public function lazy(): self {
         return $this;
     }
 
-    /**
-     * Adds a new set of characters.
-     *
-     * @param callable $callback A callback that receives a BuilderPattern instance to define the subpattern.
-     * @return self
-     */
-    public function charSet(callable $callback, ?string $q = null): self {
-        $subPattern = new self();
-        $callback($subPattern);
-        $p = '[' . $subPattern->getPattern() . ']';
-        $this->pattern .= $q ? $this->applyQuantifier($p, $q) : $p;
-        return $this;
-    }
-
-    /**
-     * Adds a new set of denied characters.
-     *
-     * @param callable $callback A callback that receives a BuilderPattern instance to define the subpattern.
-     * @return self
-     */
-    public function negativeCharSet(callable $callback, ?string $q = null): self {
-        $subPattern = new self();
-        $callback($subPattern);
-        $p = '[^' . $subPattern->getPattern() . ']';
-        $this->pattern .= $q ? $this->applyQuantifier($p, $q) : $p;
-        return $this;
-    }
-
-    /**
-     * Adds a new grouped subpattern.
-     *
-     * @param callable $callback A callback that receives a BuilderPattern instance to define the subpattern.
-     * @return self
-     */
-    public function group(callable $callback, ?string $q = null): self {
-        $subPattern = new self();
-        $callback($subPattern);
-        $p = $subPattern->getPattern();
-        $this->pattern .= $q ? $this->applyQuantifier($p, $q) : '(' . $p . ')';
-        return $this;
-    }
-
-    /**
-     * Adds a new non-capturing grouped subpattern.
-     *
-     * @param callable $callback A callback that receives a BuilderPattern instance to define the subpattern.
-     * @return self
-     */
-    public function nonCapturingGroup(callable $callback, ?string $q = null): self {
-        $subPattern = new self();
-        $callback($subPattern);
-        $p = '(?:' . $subPattern->getPattern() . ')';
-        $this->pattern .= $q ? $this->applyQuantifier($p, $q) : $p;
-        return $this;
-    }
 
-    /**
-     * Adds an alternation pattern.
-     *
-     * @param callable $callback A callback that receives a BuilderPattern instance to define the alternation.
-     * @return self
-     */
-    public function orPattern(callable $callback, ?string $q = null): self {
-        $builder = new self();
-        $callback($builder);
-        $p = $builder->getPattern();
-        $this->pattern .= $q ? '|' . $this->applyQuantifier($p, $q) : '|' . $p;
-        return $this;
-    }
-
-    /**
-     * Adds a positive lookahead assertion.
-     *
-     * @param callable $callback A callback that receives a BuilderPattern instance to define the assertion.
-     * @return self
-     */
-    public function lookAhead(callable $callback): self {
-        $builder = new self();
-        $callback($builder);
-        $this->pattern .= '(?=' . $builder->getPattern() . ')';
-        return $this;
-    }
-
-    /**
-     * Adds a positive lookbehind assertion.
-     *
-     * @param callable $callback A callback that receives a BuilderPattern instance to define the assertion.
-     * @return self
-     */
-    public function lookBehind(callable $callback): self {
-        $builder = new self();
-        $callback($builder);
-        $this->pattern .= '(?<=' . $builder->getPattern() . ')';
-        return $this;
-    }
-
-    /**
-     * Adds a negative lookahead assertion.
-     *
-     * @param callable $callback A callback that receives a BuilderPattern instance to define the assertion.
-     * @return self
-     */
-    public function negativeLookAhead(callable $callback): self {
-        $builder = new self();
-        $callback($builder);
-        $this->pattern .= '(?!' . $builder->pattern . ')';
-        return $this;
-    }
-
-    /**
-     * Adds a negative lookbehind assertion.
-     *
-     * @param callable $callback A callback that receives a BuilderPattern instance to define the assertion.
-     * @return self
-     */
-    public function negativeLookBehind(callable $callback): self {
-        $builder = new self();
-        $callback($builder);
-        $this->pattern .= '(?<!' . $builder->pattern . ')';
-        return $this;
-    }
-
-    /**
-     * Adds a raw regex string to the pattern.
-     *
-     * @param string $regex The raw regex string to add.
-     * @return self
-     */
-    public function addRawRegex(string $regex): self {
-        $this->pattern .= $regex;
-        return $this;
-    }
-
-    /**
-     * Wraps a given regex string in a non-capturing group and adds it to the pattern.
-     *
-     * @param string $regex The regex string to wrap and add.
-     * @return self
-     */
-    public function addRawNonCapturingGroup(string $regex): self {
-        $this->pattern .= '(?:' . $regex . ')';
-        return $this;
-    }
 }

src/Traits/BuilderPatternTraits/GroupsTrait.php

@@ -0,0 +1,156 @@
+<?php
+
+namespace Maestroerror\EloquentRegex\Traits\BuilderPatternTraits;
+
+trait GroupsTrait {
+
+    /**
+     * Adds a new set of characters.
+     *
+     * @param callable $callback A callback that receives a BuilderPattern instance to define the subpattern.
+     * @param ?string $q a Quantifier
+     * @return self
+     */
+    public function charSet(callable $callback, ?string $q = null): self {
+        $subPattern = new self();
+        $callback($subPattern);
+        $p = '[' . $subPattern->getPattern() . ']';
+        $this->pattern .= $q ? $this->applyQuantifier($p, $q) : $p;
+        return $this;
+    }
+
+    /**
+     * Adds a new set of denied characters.
+     *
+     * @param callable $callback A callback that receives a BuilderPattern instance to define the subpattern.
+     * @param ?string $q a Quantifier
+     * @return self
+     */
+    public function negativeCharSet(callable $callback, ?string $q = null): self {
+        $subPattern = new self();
+        $callback($subPattern);
+        $p = '[^' . $subPattern->getPattern() . ']';
+        $this->pattern .= $q ? $this->applyQuantifier($p, $q) : $p;
+        return $this;
+    }
+
+    /**
+     * Adds a new grouped subpattern.
+     *
+     * @param callable $callback A callback that receives a BuilderPattern instance to define the subpattern.
+     * @param ?string $q a Quantifier
+     * @return self
+     */
+    public function group(callable $callback, ?string $q = null): self {
+        $subPattern = new self();
+        $callback($subPattern);
+        $p = $subPattern->getPattern();
+        $this->pattern .= $q ? $this->applyQuantifier($p, $q) : '(' . $p . ')';
+        return $this;
+    }
+
+    /**
+     * Adds a new non-capturing grouped subpattern.
+     *
+     * @param callable $callback A callback that receives a BuilderPattern instance to define the subpattern.
+     * @param ?string $q a Quantifier
+     * @return self
+     */
+    public function nonCapturingGroup(callable $callback, ?string $q = null): self {
+        $subPattern = new self();
+        $callback($subPattern);
+        $p = '(?:' . $subPattern->getPattern() . ')';
+        $this->pattern .= $q ? $this->applyQuantifier($p, $q) : $p;
+        return $this;
+    }
+    
+    /**
+     * Adds an alternation pattern.
+     *
+     * @param callable $callback A callback that receives a BuilderPattern instance to define the alternation.
+     * @param ?string $q a Quantifier
+     * @return self
+     */
+    public function orPattern(callable $callback, ?string $q = null): self {
+        $builder = new self();
+        $callback($builder);
+        $p = $builder->getPattern();
+        $this->pattern .= $q ? '|' . $this->applyQuantifier($p, $q) : '|' . $p;
+        return $this;
+    }
+
+    /**
+     * Adds a positive lookahead assertion.
+     *
+     * @param callable $callback A callback that receives a BuilderPattern instance to define the assertion.
+     * @return self
+     */
+    public function lookAhead(callable $callback): self {
+        $builder = new self();
+        $callback($builder);
+        $this->pattern .= '(?=' . $builder->getPattern() . ')';
+        return $this;
+    }
+
+    /**
+     * Adds a positive lookbehind assertion.
+     *
+     * @param callable $callback A callback that receives a BuilderPattern instance to define the assertion.
+     * @return self
+     */
+    public function lookBehind(callable $callback): self {
+        $builder = new self();
+        $callback($builder);
+        $this->pattern .= '(?<=' . $builder->getPattern() . ')';
+        return $this;
+    }
+
+    /**
+     * Adds a negative lookahead assertion.
+     *
+     * @param callable $callback A callback that receives a BuilderPattern instance to define the assertion.
+     * @return self
+     */
+    public function negativeLookAhead(callable $callback): self {
+        $builder = new self();
+        $callback($builder);
+        $this->pattern .= '(?!' . $builder->pattern . ')';
+        return $this;
+    }
+
+    /**
+     * Adds a negative lookbehind assertion.
+     *
+     * @param callable $callback A callback that receives a BuilderPattern instance to define the assertion.
+     * @return self
+     */
+    public function negativeLookBehind(callable $callback): self {
+        $builder = new self();
+        $callback($builder);
+        $this->pattern .= '(?<!' . $builder->pattern . ')';
+        return $this;
+    }
+
+    /**
+     * Adds a raw regex string to the pattern.
+     *
+     * @param string $regex The raw regex string to add.
+     * @return self
+     */
+    public function addRawRegex(string $regex): self {
+        $this->pattern .= $regex;
+        return $this;
+    }
+
+    /**
+     * Wraps a given regex string in a non-capturing group and adds it to the pattern.
+     *
+     * @param string $regex The regex string to wrap and add.
+     * @return self
+     */
+    public function addRawNonCapturingGroup(string $regex): self {
+        $this->pattern .= '(?:' . $regex . ')';
+        return $this;
+    }
+
+}