xp-framework/rfc — Issue #165: New text.regex package
Author: thekid
Created: 2011-10-17 16:02:10+00:00
State: closed
Labels: framework, implemented

Scope of Change
====
A new package text.regex will be added.

Rationale
====
Object oriented API for regular expressions.

Functionality
====
The entry point class is text.regex.Pattern which is a wrapper around the
preg_*() functions in PHP.

Testing whether a pattern matches
----
The most common use-case is to test whether a given pattern matches.

```php
matches($string)) {
...
}
?>
```

The problem with the preg_match() approach is that it will return FALSE
if the pattern is malformed (and raise a warning) - this is something that
can lead to long debugging / wtf?! sessions. The Pattern class will throw
an exception.

Retrieving matched text
----
To match parts out of a string:

```php
match($string);
Console::writeLine($match->group(0));
?>
```

The results in both cases is a string-array with the contents
`[ "www.example.com", "www.", "www", "com" ]`.

Working with string objects
----
The text.regex pattern supports the lang.types.String object built-in:

```php
match($string)->group(1); // "0001"
?>
```

Modifiers
----
Instead of embedding the modifiers in the pattern string, they need to be
passed to the Pattern class' compile() method as bitfield:

```php
matches($username);
?>
```

Further modifiers are:

```
Constant name Modifier
================ ========
CASE_INSENSITIVE i
MULTILINE m
DOTALL s
EXTENDED x
ANCHORED A
DOLLAR_ENDONLY D
ANALYSIS S
UNGREEDY U
UTF8 u

```

This is more verbose but easier to read.

Security considerations
====
None.

Speed impact
====
Slightly slower than procedural approach.

Dependencies
====
PCRE extension (enabled by default)

Related documents
====
* http://java.sun.com/docs/books/tutorial/essential/regex/index.html
Lesson: Regular Expressions
* http://de3.php.net/pcre
PHP Manual: PCRE Functions
* http://www.pcre.org/pcre.txt
Concatenation of PCRE manpages
* http://experiments.xp-framework.net/?arena,regex
Implementation