iak/regexbuilder

A fluent api that simplifies writing regular expressions

Regex builder

A fluent api that simplifies writing regular expressions. (for the ones of us who always forget the syntax), _(*1)

Installation

Grab it using composer, _(*2)

$ composer require iak/regexbuilder

```json { "require": { "iak/regexbuilder": "^1.0" } }, <sub>(*3)</sub>

Simple as that :)

## Introduction

This library is for all of us that find regular expressions hard to write and impossible to remember all the different flags, look aheads, capture groups etc.

Instead of spending that half hour searching stackoverflow, I hope you can easily whip up a pattern using this lib.

Note. a basic understading of how regular expressions is still needed.

## Quick start

First of all, use the class at the top of you file,

```php
use RegexBuilder\Regex;

Now you can use it like this, <sub>(*4)</sub>

$string = "wow! this is cool!"

$match = Regex::word("wow")->symbol("!")->match($string); // wow!

Or maybe something more advanced (and demostrating some different ways of using the library), <sub>(*5)</sub>

    // Match an email address

    $email = "info@isakberglind.se";

    Regex::group("a-z0-9_-.")
        ->oneOrMore()
        ->symbol("@")
        ->group("a-z0-9_-].")
        ->oneOrMore()
        ->symbol(".")
        ->group("a-z")
        ->count(2,6)
        ->match($email);

    // a simple url-matcher

    $url = "http://www.landslide-design.se";

    Regex::word(["http", "https", "ftp"])
        ->symbols("://")
        ->capture(function ($query) {
            return $query->symbols("www.");
        })
        ->optional()
        ->group("a-zA-Z0-9@:._")
        ->count(2, 255)
        ->symbols(".")
        ->group(function ($query) {
            return $query->range("a", "z");
        })
        ->count(2, 6)
        ->group(function ($query) {
            return $query
                ->range("a", "z")
                ->range("A", "Z")
                ->range(0, 9)
                ->symbols("@:_.?//");
        })
        ->zeroOrMore()
        ->match($url);

Documentation

Words, patterns and symbols

br/, <sub>(*6)</sub>

word(mixed $word = null)

Matches provided word, array of words or any word, <sub>(*7)</sub>

    $string = "This is a hard example!";

    Regex::word("simple")->replace("simple", $string);   // This is a simple example

    Regex::word(["This", "simple", "example"])->matchAll($string); // ["this", "example"]

    Regex::word()->matchAll($string) // ["this", "is", "a", "hard", "example"]

br/, <sub>(*8)</sub>

notWord()

Matches anything but a word, <sub>(*9)</sub>

    $string = "Hi!!!!! What's up?";

    Regex::notWord()->match($string); // '!!!! '

br/, <sub>(*10)</sub>

symbols(string $symbols)

Matches provided symbols (escapes string, if you don't want that, use "pattern"), <sub>(*11)</sub>

    $string = "This is &!^@? awesome!"

    Regex::symbols("&!^@?")->replace("totally", $string) // This is totally awesome

br/, <sub>(*12)</sub>

pattern(string $pattern)

Matches provided pattern br/ Aliases: raw(), <sub>(*13)</sub>

    $string = "kickass example text";

    Regex::pattern("(example|text)")->matchAll($string); // ["example", "text"]

br/, <sub>(*14)</sub>

Characters

br/, <sub>(*15)</sub>

You can match a bunch of characters using the following helper methods, <sub>(*16)</sub>

    Regex::digit();
    Regex::notDigit();
    Regex::whitespace();
    Regex::notWhitespace();
    Regex::char();
    Regex::notChar();
    Regex::hexDigit();
    Regex::octalDigit();
    Regex::newLine();
    Regex::carriageReturn();
    Regex::tab();
    Regex::verticalTab();
    Regex::formFeed();
    Regex::space();
    Regex::any();

br/, <sub>(*17)</sub>

Quantifiers

br/, <sub>(*18)</sub>

oneOrMore()

Matches one or more of preceding group, character or character set., <sub>(*19)</sub>

    $string = "Here are some numbers 123456. Cool huh?"

    Regex::digit()->oneOrMore()->match($string) // 123456

br/, <sub>(*20)</sub>

zeroOrMore()

Matches zero or more, <sub>(*21)</sub>

    $string = "AA A1A A12A";

    Regex::char()->digit()->zeroOrMore()->char()->matchAll($string) // ["AA", "A1A", "A12A"]

br/, <sub>(*22)</sub>

count(int $count/$start, int $end = null)

Matches the specified amount or the minimum and maximun count, <sub>(*23)</sub>

    $string = "1 12 123 1234";

    // Specify the exact count to match..
    Regex::digit()->count(3)->match($string); // 123

    // Or a minimum and maximum..
    Regex::digit()->count(2,4)->matchAll($string); // [12, 123, 1234]

br/, <sub>(*24)</sub>

Groups & Character sets

br/, <sub>(*25)</sub>

range(mixed $start, $mixed $end)

Specifies a range, made especially for working with character sets, <sub>(*26)</sub>

    Regex::range("a", "z"); // a-z

br/, <sub>(*27)</sub>

group(mixed $pattern/$callback)

Creates a character set, <sub>(*28)</sub>

    // Using a callback

    Regex::group(function ($builder) {
        return $builder->range("a", "z");
    });

    // Using a raw pattern

    Regex::group("a-z");

    // Produces the same;  [a-z]

br/, <sub>(*29)</sub>

Capture groups

br/, <sub>(*30)</sub>

capture(callable $callback = null)

Creates a capture group, <sub>(*31)</sub>

    $string = "Capture this if you can!";

    // you can either capture the previous statement..

    Regex::word("this")->capture();

    // .. or using a callback

    Regex::capture(function ($builder) {
        return $builder->word("this");
    });

    // Produces the same; (this)

br/, <sub>(*32)</sub>

opionalCapture(mixed $pattern/$callback)

Creates a non capturing group, <sub>(*33)</sub>

    $string = "Do not capture this if you can!";

    // you can either capture the previous statement..

    Regex::word("this")->capture();

    // .. or using a callback

    Regex::capture(function ($builder) {
        return $builder->word("this");
    });

    // Produces the same; (?:this)?

br/, <sub>(*34)</sub>

startCapture() and endCapture()

You can also surround what you want to capture with these methods, <sub>(*35)</sub>

    $string = "Capture this if you can";

    Regex::startCapture()->word("this")->endCapture(); // (this)

br/, <sub>(*36)</sub>

Look aheads & look behinds

br/, <sub>(*37)</sub>

behind(mixed $pattern/$callback)

Creates a look behind br/ Aliases: beginsWith(), before(), <sub>(*38)</sub>

    $string = "important";

    // Using a callback..
    Regex::behind(function ($builder) {
        return $builder->symbols("");
    })
    ->word()
    ->match($string);

    // .. or a raw pattern..
    Regex::behind("\*\*\*\*")->word()->match($string);

    // important

br/, <sub>(*39)</sub>

after(mixed $pattern/$callback)

Creates a look ahead, works exactly like before() br/ Aliases: endsWith(), <sub>(*40)</sub>

br/, <sub>(*41)</sub>

Other helpers

br/, <sub>(*42)</sub>

optional(mixed $characters/$start = null, $length = null)

Makes capture group, character set or character optional, <sub>(*43)</sub>

    $string = "Is it spelled color or colour?";

    // Using a characters
    Regex::word("colour")->optional("u")->matchAll($string); // ["color", "colour"]

    // Using a start and a length
    Regex::word("colour")->optional(4,1)->matchAll($string); // ["color", "colour"]

    // Make last statement optinal

    Regex::symbols("colo")->char("u")->optional()->symbols("r")->matchAll($string); // ["color", "colour"]

br/, <sub>(*44)</sub>

escape(string $pattern)

Escapes provided pattern, <sub>(*45)</sub>

    $pattern = "^[]$<";

    Regex::escape($pattern); // \^\[\]\$\<

br/, <sub>(*46)</sub>

getPattern()

Returs the built up pattern, <sub>(*47)</sub>

    Regex::group("a-zA-Z")->oneOrMore()->symbols("!!")->optional()->zeroOrMore()->getPattern(); // /[a-zA-Z]+!!?*/

br/, <sub>(*48)</sub>

release()

Removes built up pattern, <sub>(*49)</sub>

    Regex::group("a-z")->symbol("!")->release()->symbols("only this")->getPattern(); // /only this/

br/, <sub>(*50)</sub>

Matching and replacing

br/, <sub>(*51)</sub>

replace($string, $subject)

Replace built up pattern with provided string, <sub>(*52)</sub>

    $string = "This is a hashtag: @. I'm sure!";

    Regex::symbol("@")->replace("#", $string); // This is a hashtag: #. I'm sure!

br/, <sub>(*53)</sub>

match($string)

Matches the first occurrence of the built up pattern br/ Note! only return the match. If you want all capture groups, use matchWithGroups(), <sub>(*54)</sub>

    $string = "Follow me on twitter: @Isak_Berglind!";

    Regex::symbol("@")->group("a-zA-Z_")->oneOrMore()->match($string); // @Isak_Berglind

br/, <sub>(*55)</sub>

matchAll($string)

Matches all of the occurences of the built up pattern br/ Note! only return the match. If you want all capture groups, use matchAllWithGroups(), <sub>(*56)</sub>

    $string = "this is as good as it gets";

    Regex::any()->symbol("s")->matchAll($string); // ["is", "is", "as", "as", "ts"]