RegexpBuilder documentation

RegexpBuilder is a library that helps you to build simple regular expressions

Library structure

This library builds simple regular expressions starting from a base structure composed by 3 entities:
subject[frequency][condition]

The subject is the main part of the regular expression and it indicates which part of the string the regexp must match.
The optional frequency indicates the number of ripetitions of the subject
The optional condition sets a condition for the presence of the subject

You can also use group methods to build a unique subject starting from multiple subjects

Features

Support for every type of match
Capturing and non-capturing groups
Predefined characters sets
Unicode characters
Back references
Assertions
Conditional subpatterns

Changelog

Version 1.0
- Added replaceWith, replaceWithCallback, split and grep methods
- Fixed bug on characters escape
- Added 6 more tests
Version 0.2
- Fixed bug on conditions using PRECEEDED_BY and NOT_PRECEEDED_BY
- Added 2 more tests
Version 0.1
- First release

Modifiers constants

CASE_SENSITIVE

Setting this modifier the regexp become case sensitive

CASE_INSENSITIVE

Setting this modifier the regexp become case insensitive

MULTILINE

Setting this modifier the regexp will treat the strings as a set of lines separated by \n

UNICODE_MODE

Setting this modifier the UNICODE mode will be enabled and the regexp can match also on non-latin letters

Costructor

regexpBuilder

Class costructor. Set regexp modifiers.
Arguments

String $modifiers A set of modifiers constants concatenated

Example

									$R=new regexpBuilder(CASE_INSENSITIVE); //The regexp is case insensitive
									$R=new regexpBuilder(UNICODE_MODE.CASE_INSENSITIVE); //The regexp uses unicode mode and is case insensitive

Other functions

render

Returns the regexp constructed
Return
String Regexp constructed
Example

									$R=new regexpBuilder(CASE_INSENSITIVE);
									$R->match("abc");
									echo $R->render();	//#(?:abc)#i

testOn

Test the regexp on the given strings
Arguments

String ... Strings for the test

Return
Bool False if at least one test is false, true otherwise
Example

									$R->testOn("string1","string2");

execOn

Execute the regexp on the given string and return the matches array
Arguments

String $string String for the execution
Mixed $flags Optional flags (http://www.php.net/manual/en/function.preg-match-all.php)

Return
Array Array of matches
Example

									$R->execOn("string1",PREG_PATTERN_ORDER);

replaceWith

Replace every match in the given string with the given replacement
Arguments

String $replacement Replacement string
String $string String for the replacement
Int $limit Maximum number of replacements. By default there's no limit.

Return
String The result of the replacement
Example

									$R->replaceWith("replacement","string");

replaceWithCallback

Replace every match in the given string using the given callback
Arguments

String|Fn $callback The name of the function or the result of create_function()
String $string String for the replacement
Int $limit Maximum number of replacements. By default there's no limit.

Return
String The result of the replacement
Example

									$fn=create_function('$match','return trim($match[0]);');
									$R->replaceWithCallback($fn,"string");

split

Split string by the regexp
Arguments

String $string Subject
Int $limit Maximum number of substrings. By default there's no limit.
Int $flags Optional flags (http://www.php.net/manual/en/function.preg-split.php)

Return
Array Splitted string result
Example

									$R->split("string");

grep

Returns the entries of the given array that match the regexp
Arguments

Array $input Subject array
Int $flags Optional flags (http://www.php.net/manual/en/function.preg-grep.php)

Return
Array Filtered array
Example

									$array=array("filter","this","array");
									$R->grep($array);

addCode

Add the given string to the regexp without escape it. This can be useful for add pieces of code directly at the end of the regexp, but it can break internal class controls and generate errors.
Arguments

String $regexp Piece of code to add at the end of the regexp

Return
Object Class instance
Example

									$R->addCode("[a-z]*");

setErrorLevel

Set the error level. 1=errors are shown and stored in the internal array,0=errors are stored in the internal array but they are not shown
Arguments

Int $level Error level

Return
Object Class instance

getErrors

Return the internal errors array
Return
Array Internal errors array

The default character set of the library includes only letters from the latin alphabet. If you want to extend it anable the UNICODE mode by setting the correct modifier in the class constructor and use UNICODE constants instead of latin constants.

Characters group constants

GENERAL_SPACE_CHAR

Every space, tabulation, newline ecc..

NEWLINE_CHAR

Newline character

TAB_CHAR

Tabulation character

CARRIAGE_RETURN_CHAR

Carriage return character

SPACE_CHAR

Space character

NON_GENERAL_SPACE_CHAR

Every char except space, tabulation, newline ecc...

Latin characters group constants

LETTER_CHAR

Letter

UPPERCASE_LETTER

Uppercase letter

LOWERCASE_LETTER

Lowercase letter

DIGIT_CHAR

Number

NON_DIGIT_CHAR

Every char except numbers

NON_LETTER_CHAR

Every char except letters

UNICODE mode characters group constants

UNICODE_LETTER_CHAR

Letter

UNICODE_UPPERCASE_LETTER

Uppercase letter

UNICODE_LOWERCASE_LETTER

Lowercase letter

UNICODE_DIGIT_CHAR

Number

UNICODE_NON_DIGIT_CHAR

Every char except numbers

UNICODE_NON_LETTER_CHAR

Every char except letters

Subject functions

match

Match the given string
Arguments

String $text Text to match

Return
Object Class instance Example

									$R->match("test");	//Match the string "test"

matchOneOfTheseChars

Match one of the given characters
Arguments

string|array $chars Characters to match

Return
Object Class instance Example

									$R->matchOneOfTheseChars("abc")	//Match "a", "b" or "c"
									$R->matchOneOfTheseChars("a","b","c")	//Same as above
									$R->matchOneOfTheseChars(array("a","b","c"))	//Same as above

matchEveryCharExcept

Match every character except the given
Arguments

string|array $chars Characters

Return
Object Class instance Example

									$R->matchEveryCharExcept("abc")	//Match every character except "a", "b" or "c"
									$R->matchEveryCharExcept("a","b","c")	//Same as above
									$R->matchEveryCharExcept(array("a","b","c"))	//Same as above

matchEverything

Match every character
Return
Object Class instance Example

									$R->matchEverything()->frequency(4);//Match the next 4 characters

matchOneOfTheseWords

Match one of the given words
Arguments

string|array $words Words to match

Return
Object Class instance Example

									$R->matchOneOfTheseWords("test","foo")	//Match "test" or "foo"
									$R->matchOneOfTheseWords(array("test","foo"))	//Same as above

matchCapture

Back reference. Match the result of a previous capturing group by name or position. The position count starts from 1
Arguments

int|string $name Name or position of the capturing group result to match

Return
Object Class instance Example

									$R->capture("test")
									->matchOneOfTheseWords("abc","def")
									->closeCapture()
									->matchCapture("test");	//Match the result of the "test" capturing group. If the "test" capture match "abc" this function match "abc", If the "test" capture match "def" this function match "def"

Group functions

Using these functions you can group many subjects inside a new one and then set a frequency or a condition for that. In this way you can manage a group of subjects as a single one.

capture

Start a capturing group
Arguments

string $name An optional string to assign a name the capture group

Return
Object Class instance Example

									$R->capture("test")
									->matchOneOfTheseWords("abc","def")
									->match("other")->frequency(5)
									->closeCapture();	//Match "abc" or "def" followed by "other" repeated 5 times

closeCapture

Close a capturing group. Look at the example above
Return
Object Class instance

openGroup

Start a non capturing group. The difference between this method and "capture" is that when you execute the regular expression the part of the string matched by "capture" will be returned in the result array, with this function won't.
Return
Object Class instance Example

									$R->openGroup()
									->matchOneOfTheseWords("abc","def")
									->match("test")->frequency(5)
									->openGroup()->frequency(2);	//Match "abc" or "def" followed by "other" repeated 5 times. Look for this group 2 times.

closeGroup

Close a non capturing group. Look at the example above
Return
Object Class instance

Special subject functions

For these subjects you can't specify a frequency

matchLineStart

Match the line start
Return
Object Class instance Example

									$R->matchLineStart()->match("test")	//Look for test at the begin of the string

matchLineEnd

Match the line end
Return
Object Class instance Example

									$R->match("test")->matchLineEnd()	//Look for test at the end of the line

Frequency constants

ONE_OR_MORE

Match the previous subject one ore more times

ZERO_OR_MORE

Match the previous subject zero or more times

ZERO_OR_ONE

Match the previous subject zero or one time

Frequency limit constants

LESS_THEN

Match the previous subject less times then the given number

MORE_THEN

Match the previous subject more times then the given number

LESS_THEN_OR_EQUAL_TO

Match the previous subject less times then the given number or exactly the given number of times

MORE_THEN_OR_EQUAL_TO

Match the previous subject more times then the given number or exactly the given number of times

Frequency functions

execOn

Set the frequency of the previous subject
Arguments

String|int $min The smaller limit of frequency, the exact frequency or one of the frequency or frequency limit constants
Int $max The higher limit of frequency

Return
Object Class instance Example

									$R->match("a")->frequency(5);	//Match "a" exactly 5 times
									$R->match("a")->frequency(5,7);	//Match "a" between 5 and 7 times
									$R->match("a")->frequency(ONE_OR_MORE);	//Match "a" one or more times
									$R->match("a")->frequency(MORE_THEN,7);	//Match "a" more than 7 times

oneOrMoreTimes

Set the frequency of the previous subject to one or more times. Same as frequency(ONE_OR_MORE)
Return
Object Class instance Example

									$R->match("a")->oneOrMoreTimes();	//Match "a" one or more times

zeroOrMoreTimes

Set the frequency of the previous subject to zero or more times. Same as frequency(ZERO_OR_MORE)
Return
Object Class instance Example

									$R->match("a")->zeroOrMoreTimes();	//Match "a" zero or more times

zeroOrOneTime

Set the frequency of the previous subject to zero or one time. Same as frequency(ZERO_OR_ONE)
Return
Object Class instance Example

									$R->match("a")->zeroOrOneTime();	//Match "a" zero or one time

Condition constants

FOLLOWED_BY

Match the previous subject if it's followed by...

NOT_FOLLOWED_BY

Match the previous subject if it's not followed by...

PRECEEDED_BY

Match the previous subject if it's preceeded by...

NOT_PRECEEDED_BY

Match the previous subject if it's not preceeded by...

Condition functions

ifItIs

Start a condition for the previous subject
Arguments

String $condition One of the condition constants

Return
Object Class instance Example

									$R->match("a")->ifItIs(FOLLOWED_BY)->match("b")->closeIf();	//Match "a" if it's followed by "b"
									
									//If..then..otherwise sintax
									$R->match("a")->ifItIs(FOLLOWED_BY)
									->match("b")
									->then()->match("b")
									->otherwise->matchEverything()
									->closeIf();	//If "a" is followed by "b" match "b" otherwise match every other char

then

Execute every function after this only if the prevoius condition is true
Return
Object Class instance
Example

									$R->match("a")->ifItIs(FOLLOWED_BY)
									->match("b")
									->then()->match("b")
									->closeIf();	//Match "b" only if "a" is followed by "b"

otherwise

Execute every function after this only if the prevoius condition is false
Return
Object Class instance
Example

									$R->match("a")->ifItIs(FOLLOWED_BY)
									->match("b")
									->then()->match("b")
									->otherwise()->match("c")
									->closeIf();	//Match "c" only if "a" is not followed by "b"

closeIf

Close the condition
Return
Object Class instance

Copyright 2009 Marco Marchi�

Author: Marco Marchi�

License:
This code is released under LGPL license. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.