FLUX (Fluent Regex) 0.5.2

by Selvin Ortiz

Description

Fluent Regular Expressions in PHP inspired by and largely based on VerbalExpressions:JS by Jesse Luoto

@see inspiration & credits below for more info.

Requirements

PHP 5.3
Composer

Install

Flux is available as a package via composer

require: "selvinortiz/flux": "dev-master"
autoload: require_once 'path/to/vendor/autoload.php'
namespace: use SelvinOrtiz\Utils\Flux\Flux;
instantiate: $flux = Flux::getInstance();

You can additionally clone/download this repo and do whatever you want: )

@Example

This simple example illustrates the way you would use flux and it's fluent interface to build complex patterns.

require_once realpath(__DIR__.'/../vendor/autoload.php');

use SelvinOrtiz\Utils\Flux\Flux;
use SelvinOrtiz\Utils\Flux\Helper;

// The subject string (URL)
$str	= 'http://www.selvinortiz.com';

// Building the pattern (Fluently)
$flux	= Flux::getInstance()
		->startOfLine()
		->find('http')
		->maybe('s')
		->then('://')
		->maybe('www.')
		->anythingBut('.')
		->either('.co', '.com')
		->ignoreCase()
		->endOfLine();

// Output the Flux instance
Helper::dump( $flux );

// Output the fluently built pattern (@see /src/SelvinOrtiz/Utils/Flux/Helper)
Helper::msg( $flux ); // /^(http)(s)?(\:\/\/)(www\.)?([^\.]*)(.co|.com)$/i

// Inspect the results
Helper::msg( $str );
Helper::msg( $flux->match( $str ) ? 'matched' : 'unmatched' );
Helper::msg( $flux->replace( 'https://$5$6', $str ) );

For other examples, please see the /etc directory.

@Changelog

0.5.2

Adds length() method which adds or replaces the modifier used in the previous call
Adds getLastSegmentKey()
Adds the (empty) Factory class for optimized, often used patterns
Fixes indentation and EOF on phpunit.xml
Fixes comment typos on README and example files Pull Request #10

0.5.1

Adds getSegments() which was not included in 0.5.0 Issue #5
Adds removeSegment() which can be used in unit tests as well
Adds lineBreak() and br() which matches a new line (DOS/Unix)
Adds clear() which allows you to clear out the pattern and start from scratch
Adds getPattern() which compiles the expression and returns it
Adds `deprecation candidates as @todos
Fixes mixed logic between add() and raw()
Fixes implementation on the orTry() method
Moves example in readme above changelog
Improves unit tests

0.5.0 (Beta)

Adds getSegments() to improve testability Issue #5
Adds composer package selvinortiz/flux
Adds dev branch
Adds contributing notes
Adds install notes

0.4.5

Fixes internal namespace conflict
Changes namespace from Sortiz\Tools to SelvinOrtiz\Utils\Flux
Adds composer support Issue #3
Adds the addSeed() and removeSeed() methods Issue #4
Adds the getInstance() static method
Adds FluxUrlExample.php, FluxDateExample.php, and FluxPhoneExample.php
Adds getSeed() to get the seed without forcing __toString on the object
Adds getSegment() to extract a segment (capturing group) from the pattern
Implements unit tests (60% coverage) Issue #3
Implements Full PSR-2 Compliance (Tabs over Spaces)
Enables the seed on match() and replace() Issue #4
Removes example.php and defines them elsewhere
Moves examples into /etc and defines one example per file
Other small fixes and additions

0.4.0

Adds Flux to the Sortiz\Tools namespace
Implements PSR-2 Compliance (Tabs over Spaces)
Updates version number on Flux and this readme file
Updates the class instantiation with fully qualified class name on example.php
Adds references to other repos that have ported flux
Addresses concerns outlined in Issue #3

0.3.0

Improves documentation with phone/date examples
Adds the letters() method
Renames the numbers() method to digits()
Adds support for quantifiers for digits()
Adds ignoreCase() and promotes it above inAnyCase()
Improves the documented API

Thought hard about changing the name to FluentX any thoughts?

0.2.0

Adds the either( $option1, $option2 [, $option3 ...] ) method to handle OR cases
Updates the fluent example in this readme file
Adds the license

0.1.0 (Alpha)

Initial preview release

@Todo

Add source code comments
Add support for quantifiers
Add language methods for more advanced use cases
Add reference to repos that have ported Flux (*)
Add license notes (*)
Add contributing notes (*)
Add credits (*)

FLUX API

The flux API was designed to give you a fluent chainable object to build patterns with.

`startOfLine()`

Adds a beginning of line ^ modifier

`endOfLine()`

Adds an end of line $ modifier

`find( $val ) & then( $val )`

Allows you to augment the pattern with a required segment and it escapes regular expression characters

`maybe( $val )`

Allows you to augment the pattern with an optional segment

`any( $val ) & anyOf( $val )`

Allows you to create a set of characters to match

`anything()`

Adds a wild card (.*) segment to the pattern but it does not make dotAll() explicit

`anythingBut( $val )`

Will match anything but the characters in $val which is opposite of any() and anyOf

`br() & lineBreak()`

Allows you to match a new line (DOS/Unix)

`tab()`

Adds a (\t) to the pattern which will match a tab

`word()`

Adds (\w+) to the pattern which will match a single word

`letters( $min=null, $max=null )`

Only matches characters in the alphabet and uses $min and $max to create a quantifier

`digits( $mix=null, $max=null )`

Only matches digits and uses $min and $max to create a quantifier like word()

`range( $from, $to [, $from, $to ...])`

Allows you to create a range character class like a-z0-9 by calling range('a', 'z', 0, 9)

`orTry( $val='' )`

Allows you to create OR cases (this)|(else) and retain the capturing order to use in replace()

`ignoreCase() & inAnyCase()`

Adds the i modifier to the pattern which will allow you to match in a case insensitive manner

`matchNewLine() & dotAll()`

Adds the s modifier to the pattern which will allow you to match a new line when using anything()

`multiline()`

Adds the m modifier to the pattern which will allow you to search across multiple lines

`oneLine() & searchOneLine()`

Removes the modifier added by multiline() if it was previously called

`match( $subject )`

Simply takes your $subject in, compares it against the pattern, and returns whether a it matched or not

`replace( $replacement, $subject )`

You can replace matched segments by using the $x format where x is the (int) position of the matched segment

`getPattern()`

Returns the compiled pattern which you can also get by using the flux instance in a context where __toString() will be called

`clear()`

Clears the created pattern along with the modifiers, prefixes, and suffixes

Flux Elsewhere

There is a straight port of Flux for NodeJS by James Brooks whom has also collaborated on this project.

Feedback

This is something that started as a weekend experiment but I would love to take it further so if you have any suggestions, please fire away!

The best way to get in touch with me is via twitter @selvinortiz we'll take if from there :)

Contributing

Check for open issues or open a new issue for a feature request or a bug
Fork this repo to start making your changes to the dev branch or branch off
Write a test which shows that the bug was fixed or that the feature works as expected
Send a pull request and bug me until I merge it or tell you no cigar; )

Inspiration & Credits

This project is inspired and largely based on VerbalExpressions:JS by Jesse Luoto whom on July 20, 2013 started a weekend project that generated a lot of interest in the developer community and that project has proven to have a lot of potential.

Flux is not a straight port of VerbalExpressions but if you're interested in a straight VerbalExpressions port for PHP you should checkout VerbalExpressions:PHP by Mark Wilson

VerbalExpressions has also been ported to Ruby, Java, Groovy as of this update (July 25, 2013).

For a little background as to why flux was created and why you should use it, please refer to Issue #7 for a discussion on that matter.

MIT License

Flux is released under the MIT license which pretty much means you can do with it as you please and I won't get mad because I'm that nice; )

Files

README.md

Latest commit

History

README.md

File metadata and controls

FLUX (Fluent Regex) 0.5.2

Description

Requirements

Install

@Example

@Changelog

0.5.2

0.5.1

0.5.0 (Beta)

0.4.5

0.4.0

0.3.0

0.2.0

0.1.0 (Alpha)

@Todo

FLUX API

startOfLine()

endOfLine()

find( $val ) & then( $val )

maybe( $val )

any( $val ) & anyOf( $val )

anything()

anythingBut( $val )

br() & lineBreak()

tab()

word()

letters( $min=null, $max=null )

digits( $mix=null, $max=null )

range( $from, $to [, $from, $to ...])

orTry( $val='' )

ignoreCase() & inAnyCase()

matchNewLine() & dotAll()

multiline()

oneLine() & searchOneLine()

match( $subject )

replace( $replacement, $subject )

getPattern()

clear()