tea/regex

A clean interface for building and working with regular expressions. Lightweight wrapper for the built in PCRE library (preg_* functions).

dev-master / 0.1.0.x-dev 2017-01-09 00:52 UTC

Requires

• php: >=5.4
• gherkins/regexpbuilderphp: 0.*.*
• tea/contracts: ~0.1.0
• tea/future: ~0.1.0

Requires (Dev)

• phpbench/phpbench: @dev
• phpunit/phpunit: ~5.0

MIT

• David Kyalo

• utils
• regex
• regular
• expressions
• PCRE
• preg
• tea

README

PHP comes with a built-in regular expression library (PCRE), which provides the preg_* functions. Most of the time, these functions require some odd patterns like passing variables by reference and treating false or null values as errors. To make working with regex a bit more developer-friendly, tea/regex provides a clean interface for the preg_* functions as well as a human-readable API for building regular expressions.

Basic Usage.

To build and work with regular expressions, tea\regex provides a couple of flexible components.

• The RegularExpression object which represents a regex pattern and provides various regex methods (match(), replace(), split()).
• The Builder which provides a human-readable API for building regular expressions.
• The Regex static facade which provides a static interface for the RegularExpression object.

Getting Started.

To perform regex functions such as match, replace, split, we need to create a RegularExpression instance. There are various ways to do this.

use Tea\Regex\Regex;
use function Tea\Regex\re;
use Tea\Regex\RegularExpression;

// 1. Creating directly.
$regex = new RegularExpression('^\d+-([A-Za-z]+)-([A-Za-z]+)');
$matches = $regex->match('254-foo-bar-baz'); // 'Tea\Regex\Result\Matches' object

// 2. Using the Regex static facade.
$regex = Regex::create('^\d+'); // 'Tea\Regex\RegularExpression' object
$replaced = $regex->replace('x', '254-foo-bar-baz'); // 'Tea\Regex\Result\Replacement' object

// 3. Using the re() function.
$regex = re('-'); // 'Tea\Regex\RegularExpression' object
$result = $regex->split('254-foo-bar-baz'); // array('254', 'foo', 'bar', 'baz')

Notice that the delimiters and modifiers are missing from the regex patterns used above? Yes. The methods above will throw an error if you provide a pattern with the delimiters and/or any modifiers set. In the examples above, / is be used as the delimiter and the u modifiers is set. / delimiter and u modifier are the default.

To set the delimiter and modifiers to be used:

// Compiles to '#^ \d+ - ([A-Za-z]+) - ([A-Za-z]+)#ix'
$regex = new RegularExpression('^ \d+ - ([A-Za-z]+) - ([A-Za-z]+)', 'ix', '#');

// Compiles to '|^\d+|u'
$regex = Regex::create('^\d+', null, '|');

// Compiles to '/-/'
$regex = re('-', '', '/');

Creating with complete regex patterns.

$regex = RegularExpression::from('/^\d+/u');
Regex::from(...);
Regex::match(...);
Regex::replace(...);

Match

...

MatchAll

...

replace

...

replaceCallback

...

filter

...

matches

...

replaced

...

split

...