1<p align="center"> 2 <img src="https://static.hoa-project.net/Image/Hoa.svg" alt="Hoa" width="250px" /> 3</p> 4 5--- 6 7<p align="center"> 8 <a href="https://travis-ci.org/hoaproject/regex"><img src="https://img.shields.io/travis/hoaproject/regex/master.svg" alt="Build status" /></a> 9 <a href="https://coveralls.io/github/hoaproject/regex?branch=master"><img src="https://img.shields.io/coveralls/hoaproject/regex/master.svg" alt="Code coverage" /></a> 10 <a href="https://packagist.org/packages/hoa/regex"><img src="https://img.shields.io/packagist/dt/hoa/regex.svg" alt="Packagist" /></a> 11 <a href="https://hoa-project.net/LICENSE"><img src="https://img.shields.io/packagist/l/hoa/regex.svg" alt="License" /></a> 12</p> 13<p align="center"> 14 Hoa is a <strong>modular</strong>, <strong>extensible</strong> and 15 <strong>structured</strong> set of PHP libraries.<br /> 16 Moreover, Hoa aims at being a bridge between industrial and research worlds. 17</p> 18 19# Hoa\Regex 20 21[![Help on IRC](https://img.shields.io/badge/help-%23hoaproject-ff0066.svg)](https://webchat.freenode.net/?channels=#hoaproject) 22[![Help on Gitter](https://img.shields.io/badge/help-gitter-ff0066.svg)](https://gitter.im/hoaproject/central) 23[![Documentation](https://img.shields.io/badge/documentation-hack_book-ff0066.svg)](https://central.hoa-project.net/Documentation/Library/Regex) 24[![Board](https://img.shields.io/badge/organisation-board-ff0066.svg)](https://waffle.io/hoaproject/regex) 25 26This library provides tools to analyze regular expressions and generate strings 27based on regular expressions ([Perl Compatible Regular 28Expressions](http://pcre.org)). 29 30[Learn more](https://central.hoa-project.net/Documentation/Library/Regex). 31 32## Installation 33 34With [Composer](https://getcomposer.org/), to include this library into 35your dependencies, you need to 36require [`hoa/regex`](https://packagist.org/packages/hoa/regex): 37 38```sh 39$ composer require hoa/regex '~1.0' 40``` 41 42For more installation procedures, please read [the Source 43page](https://hoa-project.net/Source.html). 44 45## Testing 46 47Before running the test suites, the development dependencies must be installed: 48 49```sh 50$ composer install 51``` 52 53Then, to run all the test suites: 54 55```sh 56$ vendor/bin/hoa test:run 57``` 58 59For more information, please read the [contributor 60guide](https://hoa-project.net/Literature/Contributor/Guide.html). 61 62## Quick usage 63 64As a quick overview, we propose to see two examples. First, analyze a regular 65expression, i.e. lex, parse and produce an AST. Second, generate strings based 66on a regular expression by visiting its AST with an isotropic random approach. 67 68### Analyze regular expressions 69 70We need the [`Hoa\Compiler` 71library](https://central.hoa-project.net/Resource/Library/Compiler) to lex, parse 72and produce an AST of the following regular expression: `ab(c|d){2,4}e?`. Thus: 73 74```php 75// 1. Read the grammar. 76$grammar = new Hoa\File\Read('hoa://Library/Regex/Grammar.pp'); 77 78// 2. Load the compiler. 79$compiler = Hoa\Compiler\Llk\Llk::load($grammar); 80 81// 3. Lex, parse and produce the AST. 82$ast = $compiler->parse('ab(c|d){2,4}e?'); 83 84// 4. Dump the result. 85$dump = new Hoa\Compiler\Visitor\Dump(); 86echo $dump->visit($ast); 87 88/** 89 * Will output: 90 * > #expression 91 * > > #concatenation 92 * > > > token(literal, a) 93 * > > > token(literal, b) 94 * > > > #quantification 95 * > > > > #alternation 96 * > > > > > token(literal, c) 97 * > > > > > token(literal, d) 98 * > > > > token(n_to_m, {2,4}) 99 * > > > #quantification 100 * > > > > token(literal, e) 101 * > > > > token(zero_or_one, ?) 102 */ 103``` 104 105We read that the whole expression is composed of a single concatenation of two 106tokens: `a` and `b`, followed by a quantification, followed by another 107quantification. The first quantification is an alternation of (a choice betwen) 108two tokens: `c` and `d`, between 2 to 4 times. The second quantification is the 109`e` token that can appear zero or one time. 110 111We can visit the tree with the help of the [`Hoa\Visitor` 112library](https://central.hoa-project.net/Resource/Library/Visitor). 113 114### Generate strings based on regular expressions 115 116To generate strings based on the AST of a regular expressions, we will use the 117`Hoa\Regex\Visitor\Isotropic` visitor: 118 119```php 120$generator = new Hoa\Regex\Visitor\Isotropic(new Hoa\Math\Sampler\Random()); 121echo $generator->visit($ast); 122 123/** 124 * Could output: 125 * abdcde 126 */ 127``` 128 129Strings are generated at random and match the given regular expression. 130 131## Documentation 132 133The 134[hack book of `Hoa\Regex`](https://central.hoa-project.net/Documentation/Library/Regex) 135contains detailed information about how to use this library and how it works. 136 137To generate the documentation locally, execute the following commands: 138 139```sh 140$ composer require --dev hoa/devtools 141$ vendor/bin/hoa devtools:documentation --open 142``` 143 144More documentation can be found on the project's website: 145[hoa-project.net](https://hoa-project.net/). 146 147## Getting help 148 149There are mainly two ways to get help: 150 151 * On the [`#hoaproject`](https://webchat.freenode.net/?channels=#hoaproject) 152 IRC channel, 153 * On the forum at [users.hoa-project.net](https://users.hoa-project.net). 154 155## Contribution 156 157Do you want to contribute? Thanks! A detailed [contributor 158guide](https://hoa-project.net/Literature/Contributor/Guide.html) explains 159everything you need to know. 160 161## License 162 163Hoa is under the New BSD License (BSD-3-Clause). Please, see 164[`LICENSE`](https://hoa-project.net/LICENSE) for details. 165