Add functionality to do this:

pattern('=(\d+?);')->replace($str)->by()->group(1)->callback('dechex');

instead of this

pattern('=(\d+?);')->replace($str)->callback(function (Match $m) {
    return dechex($m->group(1));
}

but i guess it only makes sense with callback() and byMap()

Allow certain match() methods to return grouped values.

Methods:

• groupBy(string|int) - groups by capturing group
• groupByCallback(callable) - groups by user defined callback

Requirements:

• All of them must be usable with filter()->groupBy().

Example for all()

pattern('\d+(?<unit>cm|mm)')->match('12cm 14mm 13cm 19cm 18mm 2mm')->groupBy('unit')
  ->all();

[
  'cm' => ['12cm', '13cm', '19cm'],
  'mm' => ['14mm', '18mm', '2mm']
]

<?php
pattern('word')
    ->match('word')
    ->all()
    ->forEach(function (Match $m) {
        $m->setUserData('welp');
    })
    ->filter(function (Match $m) {
        return $m->getUserData() == 'welp' ; // true
    });

or maybe

<?php
$m->userData = 'welp';
return $m->userData == 'welp' ;

PS: Why even bother, when you can duck-type userData?

If flag x is used in a pattern, then all whitespaces are ignored.

If I use it in PatternBuilder:

Pattern::inject('/my duper pattern @input/x', [
    'input' => 'text with whitespaces'
]);

then those whitespaces in the user input will also be ignore, because of the x flag.

This feature might feel spuerfluous to some, because the result can be achieved with look aheads and look beahinds.

When replacing http://(/w+).com for http://google.com you could inject group 1 with 'xd', that would result in 'http://xd.com'.

Instead of returning ->all(). return an \Iterator to traverse elements.

Also for Pattern.match().group().iterator().

Example: (list of people, some with ages)

Clark, Brian 23, Olivia, Jane 24, Marcin 26

New API:

• Returns a group from the first match or throws exception

  pattern('[a-z]+(?: (?<age>\d+))?')->match($s)->group('age')->first();

  Throw GroupNotMatchedException if subject matched, but group wasn't.

Add pattern()->analyze()->explain()

Add API for handling replacements, that didn't happen.

The default behaviour:

• Returning the input $subject - just like any replacement

The customizable behaviour:

• Returning a predefined string, if no replacement happened - orReturn()
• Returning generated string based on $subject - orElse()
  • Just returning $string is no different than default behaviour
• Throwing an exception (ReplacementPatternNotMatchedException) - orThrow()

API:

Replace \d+ with '0' or return Unmatched: $subject:

pattern('\d+')->replace('Hello')
  ->first()
  ->orElse(function (string $subject) {
    return "Unmatched: '$subject'" ;
   })
  ->with('0');

No number found in: 'Hello'

Replace \d+ with '0' or return Unmatched:

first()->orReturn('Unmatched :/')->with('0');

Unmatched :/

Replace \d+ with '0' or throw InvalidArgumentException/default:

first()->orThrow(InvalidArgumentException::class)->with('0');
// or
first()->orThrow()->with('0');

Exception is thrown

Make a method that knows how to simplify a pattern.

patter('[0-9]{1,} and [.]{1}')->analyze()->simplify();

\d+ and \.

WITH SPECIAL CARE ABOUT ESCAPING

Currently, pattern()/Pattern::of()/new Pattern(), each "guess" whether a pattern is delimited (with flags) or not.

This is ambiguous, for example:

• is /abc/m delimited? Of course
• is _abc_m delimited? pattern() would say yes
• is ,(word),x delimited? pattern() would see ,(word), and x flag.
• is ,(word),xF delimited? suddenly, xF are not valid flags so pattern() would see ,(word),xF with no flags.
• is //s an empty pattern with s flag? Or //s pattern? pattern() would choose the first

So:

• we must remove automatic delimiter detection, because it causes too much ambiguity
• pattern()/Pattern::of() will now treat each pattern as undelimited by default. Validation will be performed, whether we have enough delimiters to delimit it properly. If we don't, the other method will have to be used.
• New method will have to be added Pattern::pcre(), which will only accept a delimited pattern, that is:
  • Having a delimiters at the start and end of a string (+ additional flags).
  • No validation of pattern used with the new method should be done, in hope that PCRE by itself will validate it.

New method name, perhaps:

• Pattern::standard() - standard pattern for PCRE, not so much for T-Regx
• Pattern::basic()
• Pattern::pcre() - unintuitive
• Pattern::undelimited() - too long
• Pattern::raw() - too crude

MatchesPattern and Base have very similar constructors and matches() methods, but they are ought to do completely different things.

For a pattern like this:

pattern('_ERROR$')->matches($subject);

to filter those values

NO_ERROR
UTF8_ERROR
RUNTIME_ERROR

CleanRegex could analyze the pattern, see if it doesn't contain any special characters (or all those characters are escaped) and use substr() and strpost() instead. If pattern happens to have ^ or $ at beginning or end, it would only match those sub strings at begining or end.

• $match->groupOffsets() - to remove
• $match->group('as')->offset() - ok
• $match->group('as')->byteOffset() - todo
• $match->groups()->offsets() - ok
• $match->groups()->byteOffsets() - todo

pattern()->valid() returns true/false, indicating whether a pattern is valid or not.

We also need pattern()->analyze()->validate() that will (or will not) throw an Exception with detailed message about the pattern and why it's invalid.

Possibly also a method pattern()->analyze()->validateWithSubject($s) that could check not only compile-time but also run-time errors (like utf8 errors or backtracking errors).

Add a way to use user-supplied values inside patterns.

 return preg_match(
  '/\b' . preg_quote($str1, '/') . '\b with ' . preg_quote($str2, '/') . ' :\)/i', 
$str2);

It should:

• be similar to prepared sql statements, but without presenting tokens in patterns (regexp are already complicated enough)
• be simple to quote user input (not to remember the delimiter, not to use long method)
• use multiple combinations of patterns and user input

For Facade style, instead of:

Pattern::pattern('[A-Z][a-z]+')->test($subject)

You could try:

Pattern::of('[A-Z][a-z]+')->test($subject)

Reads better for me :)

As suggested by this poll: https://4programmers.net/Forum/PHP/330463-sugestia_nazwania_metody?p=1616850#id1616850

ReplaceMatch already receives an analyzed pattern. This pattern could be used to iterate Matches, filter those out, and only perform replacement on the left out Matches.

• Add ignoring() method which ignores replacements by polymorphism
• Include user data between ignoring() and callback()
• Disallow ignoring()->ignoring()->callback()
• Add replace()->nth(i)
• Add replace()->range()
• Add replace()->rangeIfExists()

Requirements:

• Must be usable with unique()->filter() and filter()->unique()
• Must be usable with unique()->groupBy()

Methods:

• unique() identifies uniqueness by Match.text()
• unique()->byGroup($p) identifies uniqueness by Match.group($p)
• unique()->byCallback(callable) identifies uniqueness by callable which receives Match object

Makes sense for:

• unique()->all()
• unique()->only(int) - which retrieves certain amount of matches, and then uniquess them :D
  • So ['1', '1', '2', '3'] for unique()->only(3) would return:
    • ['1', '2'].
  • So ['1', '1', '2', '3'] for unique()->maxUnique(3)->only(4) would return:
    • ['1', '2', '3'].
• unique()->count()
• unique()->map(), flatMap()
• unique()->forEach(), iterate(), iterator()
• unique()->offsets()/byteOffsets(),
• unique()->group('unit')->all() - finds unique matches, and returns unit groups from them
• unique()->group('unit')->offsets()/byteOffsets(),

It should not be possible to call:
group('unit')->unique()
because what sense does it make to:
group(1)->unique()->byGroup(2)->group(3)

For branches master-php5.3 and master-php5.6.

• 5.6.0 - 5.6.38

Probably after 1.1 release.

• Huge Feature pattern()->explain() - returns nested arrays of human readable description of pattern for debugging.

Hi, I just found out about this library, it looks really good, but I have a question. Is there a reason why you aren't locking releases with git tags?

withGroupWithReferences() makes no sense.

withGroup() should quote references just like with() now quotes

#43

Many changes have been made to MatchPattern and Match. Those changes must also be applied to ReplacePattern and ReplaceMatch.

It should be possible to call

pattern()->match()->group()->map(); // done
pattern()->match()->group()->forEach(); // done
pattern()->match()->group()->fluent(); // done
pattern()->match()->group()->filter();
pattern()->match()->group()->forFirst(); // done
pattern()->match()->group()->offsets(); // done

• TODO: See if result of Match.group() has alike interface with possible callback argument.

There are no tests for

• \Unit\Replace
• \Integration\Match

What could be possible

pattern()->filter()->all();      // return all filtered values
pattern()->filter()->first();    // return the first of filtered values
pattern()->filter()->only(int);  // return limited filtered values

But that's problematic because elements of $a can be matched more than once :/

Given that replace() implements common interface by limits

pattern()->replace()->first()    // limit 1
pattern()->replace()->all()      // limit -1
pattern()->replace()->only(int)  // limit $x 

and match() by preg methods

pattern()->match()->first()      // preg_match()
pattern()->match()->all()        // preg_match_all()
pattern()->match()->only(int)    // array_slice(preg_match_all(), 0, $i)

a question arises: Should there also be only() method?

pattern()->match()->only(int)

This is a substitute for

// all
pattern()->match()->map(function ($m) {
    return $m->offset();
});

// first
pattern()->match()->first(function ($m) {
    return $m->offset();
});

For groups you could do

pattern()->match()->map(function ($m) {
    return $m->group('a')->offset(); // this already returns group offset
});

• Include a detailed documentation of every public method
• Include only @param, @returns and @throws tags.
• Include @psalm and @phpstan annotations
• Include @see and @link attributes linking to classes and documentation on t-regx
• Add @api tag to public elements and @internal tag to implementation details (most of Internal/ namespace)

• For match()->only($i) for i$ is bigger than the amount of matches
• For pattern()->match() with subject longer than 65536 characters.

Feature description

Add

preg::grep_keys()

For example in TestMatchesPattern.

pattern()->match()->offsets()->first()

throws
SubjectNotMatchedException : Expected to get first match, but subject was not matched

but could

SubjectNotMatchedException : Expected to get first match offset, but subject was not matched

Add asInt() so that one can call

•  pattern()->match()->asInt();
   pattern()->match()->asInt();
   pattern()->match()->asInt();

• asInt() should be identical to:

  pattern()->match()
    ->fluent()
    ->map(function (Match $match) {
      return $match->toInt();
    })
    ->*();

  but faster, because Match won't have to be constructed
• Also add for match()->group()

Allow Match and Match.group() to be returned by any method that it makes sense for it (and treat it as Match.text() and GroupMatch.text()). Use it for methods:

• replace()->callback()
• match()->map()
• replace()->by()->group()->callback()

GroupName::isValid(2); // true
GroupName::isValid('group'); // true

GroupName::isValid('2asd'); // false
GroupName::isValid(-1); // false
GroupName::isValid(null); // false
GroupName::isValid([]); // false

And same for MatchGroup::isValidName() that only works for strings

Common use case for preg_replace() are chained calls:

$r = preg_replace("/(!|\"|#|$|%|'|̣)/", '', $r);
$r = preg_replace("/(̀|́|̉|$|>)/", '', $r);
$r = preg_replace("'<[\/\!]*?[^<>]*?>'si", '', $r);
return $r;

Example

pattern('[0-9]')->fails('Word'); // true

pattern('[0-9]')->fails('2018'); // false

• Add info about calling preg_last_error() to readme
• Add info about "always an exception" to table of contents

PS:

• Add general PatternException (or maybe TRegxException) that all methods will call.

Test ErrorsCleanerTest.shouldGetCompileError() passes for every version of PHP between 7.1.0-7.1.12, and keeps failing between 7.1.13-7.1.21 and for every 7.2.* version.

This is caused by this bug fix: https://bugs.php.net/bug.php?id=74183

For <7.1.12 causing compile time PCRE error only makes error_get_last() to return an error. It doesn't make preg_last_error() return anything (it returns 0 - PREG_NO_ERROR). Data from error_get_last() is enough to throw CompileError based exception.

Since 7.1.13 though, preg_last_error() starts to return data to throw an exception, so no longer CompileError is raised, but composite model BothHostError.

Solutions:

• first: Write two separate tests for <7.1.12 and >7.1.13 (meh)
• second: Make tests only rely on interfaces and return values, not on specific instances (better)

Problems:

• first: Adds unnecessary complexity.
• second: If the tests only relied on interfaces, this bug wouldn't have ever been found. (no longer a unit test, but an integration test. To unit test it, we need to know the exact implementation).

For example

SafeRegex\Exception\CompileSafeRegexException : Object of class CleanRegex\Match\ReplaceMatch could not be converted to int
 
(caused by E_NOTICE)

If someone calls

pattern('p')->match($s)->only(1);

this should call ->first() under the hood.