1780612405
markdown-eaed247a6520178b30791357af15c14e3a4a06ea
s:7178:"<p align="center">
  <img src="splat.svg" alt="Splat" width="50%">
</p>
<p align="center">
    <a href="https://github.com/PHLAK/Splat/discussions"><img src="https://img.shields.io/badge/Join_the-Community-7b16ff.svg?style=for-the-badge" alt="Join our Community"></a>
    <a href="https://github.com/users/PHLAK/sponsorship"><img src="https://img.shields.io/badge/Become_a-Sponsor-cc4195.svg?style=for-the-badge" alt="Become a Sponsor"></a>
    <a href="https://paypal.me/ChrisKankiewicz"><img src="https://img.shields.io/badge/Make_a-Donation-006bb6.svg?style=for-the-badge" alt="One-time Donation"></a>
    <br>
    <a href="https://packagist.org/packages/PHLAK/Splat"><img src="https://img.shields.io/packagist/v/PHLAK/Splat.svg?style=flat-square" alt="Latest Stable Version"></a>
    <a href="https://packagist.org/packages/PHLAK/Splat"><img src="https://img.shields.io/packagist/dt/PHLAK/Splat.svg?style=flat-square" alt="Total Downloads"></a>
    <a href="https://github.com/PHLAK/Splat/blob/master/LICENSE"><img src="https://img.shields.io/github/license/PHLAK/Splat?style=flat-square" alt="License"></a>
    <a href="https://github.com/PHLAK/Splat/actions"><img alt="GitHub branch checks state" src="https://img.shields.io/github/checks-status/phlak/splat/master?style=flat-square"></a>
</p>
<hr />
<p>Glob-like file and pattern matching utility.</p>
<h2>Requirements</h2>
<ul>
<li><a href="https://www.php.net/">PHP</a> &gt;= 7.2</li>
</ul>
<h2>Installation</h2>
<p>Install Splat with Composer.</p>
<pre><code>composer require phlak/splat</code></pre>
<p>Then import the <code>Glob</code> or <code>Pattern</code> classes as needed.</p>
<pre><code class="language-php">use PHLAK\Splat\Glob;
use PHLAK\Splat\Pattern;</code></pre>
<h2>Patterns</h2>
<p><code>Glob</code> methods accept a <code>$pattern</code> as the first parameter. This can be a string
or an instance of <code>\PHLAK\Splat\Pattern</code>. A pattern string may contain one or
more of the following special matching expressions.</p>
<h3>Matching Expressions</h3>
<ul>
<li><code>?</code> matches any single character</li>
<li><code>*</code> matches zero or more characters excluding <code>/</code> (<code>\</code> on Windows)</li>
<li><code>**</code> matches zero or more characters including <code>/</code> (<code>\</code> on Windows)</li>
<li><code>[abc]</code> matches a single character from the set (i.e. <code>a</code>, <code>b</code> or <code>c</code>)</li>
<li><code>[a-c]</code> matches a single character in the range (i.e. <code>a</code>, <code>b</code> or <code>c</code>)</li>
<li><code>[^abc]</code> matches any character not in the set (i.e. not <code>a</code>, <code>b</code> or <code>c</code>)</li>
<li><code>[^a-c]</code> matches any character not in the range (i.e. not <code>a</code>, <code>b</code> or <code>c</code>)</li>
<li><code>{foo,bar,baz}</code> matches any pattern in the set (i.e. <code>foo</code>, <code>bar</code> or <code>baz</code>)</li>
</ul>
<h3>Assertions</h3>
<p>The following assertions can be use to assert that a string is followed by or
not followed by another pattern.</p>
<ul>
<li><code>(=foo)</code> matches any string that also contains <code>foo</code></li>
<li><code>(!foo)</code> matches any string that does not also contain <code>foo</code></li>
</ul>
<p>For example, a pattern of <code>*.tar(!.{gz|xz})</code> will match a string ending with
<code>.tar</code> or <code>.tar.bz</code> but not <code>tar.gz</code> or <code>tar.xz</code>.</p>
<h3>Converting Patterns To Regular Expressions</h3>
<p>Convet a glob pattern to a regular expression pattern.</p>
<pre><code class="language-php">Pattern::make('foo')-&gt;toRegex(); // Returns '#^foo$#'
Pattern::make('foo/bar.txt')-&gt;toRegex(); // Returns '#^foo/bar\.txt$#'
Pattern::make('file.{yml,yaml}')-&gt;toRegex(); // Returns '#^file\.(yml|yaml)$#'</code></pre>
<p>You can also control line anchors via the <code>$options</code> parameter.</p>
<pre><code class="language-php">Pattern::make('foo')-&gt;toRegex(Glob::NO_ANCHORS); // Returns '#foo#'
Pattern::make('foo')-&gt;toRegex(Glob::START_ANCHOR); // Returns '#^foo#'
Pattern::make('foo')-&gt;toRegex(Glob::END_ANCHOR); // Returns '#foo$#'
Pattern::make('foo')-&gt;toRegex(Glob::BOTH_ANCHORS); // Returns '#^foo$#'
Pattern::make('foo')-&gt;toRegex(Glob::START_ANCHOR | Glob::END_ANCHOR); // Returns '#^foo$#'</code></pre>
<hr />
<h3>Escape</h3>
<p>Escape glob pattern characters from a string.</p>
<pre><code class="language-php">Pattern::escape('What?'); // Returns 'What\?'
Pattern::escape('*.{yml,yaml}'); // Returns '\*.\{yml\,yaml\}'
Pattern::escape('[Gg]l*b.txt'); // Returns '\[Gg\]l\*b.txt'</code></pre>
<h2>Methods</h2>
<h3>Files In</h3>
<p>Get a list of files in a directory matching a glob pattern.</p>
<pre><code class="language-php">Glob::in('**.txt', 'some/file/path');</code></pre>
<p>Returns a <a href="https://symfony.com/doc/current/components/finder.html">Symfony Finder Component</a>
containing the files matching the glob pattern within the specified directory
(e.g. <code>foo.txt</code>, <code>foo/bar.txt</code>, <code>foo/bar/baz.txt</code>, etc.).</p>
<hr />
<h3>Exact Match</h3>
<p>Test if a string matches a glob pattern.</p>
<pre><code class="language-php">Glob::match('*.txt', 'foo.txt'); // true
Glob::match('*.txt', 'foo.log'); // false</code></pre>
<hr />
<h3>Match Start</h3>
<p>Test if a string starts with a glob pattern.</p>
<pre><code class="language-php">Glob::matchStart('foo/*', 'foo/bar.txt'); // true
Glob::matchStart('foo/*', 'bar/foo.txt'); // false</code></pre>
<hr />
<h3>Match End</h3>
<p>Test if a string ends with a glob pattern.</p>
<pre><code class="language-php">Glob::matchEnd('**.txt', 'foo/bar.txt'); // true
Glob::matchEnd('**.txt', 'foo/bar.log'); // false</code></pre>
<hr />
<h3>Match Within</h3>
<p>Test if a string contains a glob pattern.</p>
<pre><code class="language-php">Glob::matchWithin('bar', 'foo/bar/baz.txt'); // true
Glob::matchWithin('bar', 'foo/baz/qux.txt'); // false</code></pre>
<hr />
<h3>Filter an Array (of Strings)</h3>
<p>Filter an array of strings to values matching a glob pattern.</p>
<pre><code class="language-php">Glob::filter('**.txt', [
    'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
]);

// Returns ['foo.txt', 'foo/bar.txt']</code></pre>
<hr />
<h3>Reject an Array (of Strings)</h3>
<p>Filter an array of strings to values <em>not</em> matching a glob pattern.</p>
<pre><code class="language-php">Glob::reject('**.txt', [
    'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
]);

// Returns ['foo', 'bar.zip', 'foo/bar.png']</code></pre>
<h2>Changelog</h2>
<p>A list of changes can be found on the <a href="https://github.com/PHLAK/Splat/releases">GitHub Releases</a> page.</p>
<h2>Troubleshooting</h2>
<p>For general help and support join our <a href="https://github.com/PHLAK/Splat/discussions">GitHub Discussion</a> or reach out on <a href="https://twitter.com/PHLAK">Twitter</a>.</p>
<p>Please report bugs to the <a href="https://github.com/PHLAK/Splat/issues">GitHub Issue Tracker</a>.</p>
<h2>Copyright</h2>
<p>This project is licensed under the <a href="https://github.com/PHLAK/Splat/blob/master/LICENSE">MIT License</a>.</p>";