Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/phlak/splat
Glob-like file and pattern matching utility.
https://github.com/phlak/splat
file-matching glob pattern-matching php regex regular-expression
Last synced: 6 days ago
JSON representation
Glob-like file and pattern matching utility.
- Host: GitHub
- URL: https://github.com/phlak/splat
- Owner: PHLAK
- License: mit
- Created: 2020-04-30T22:46:24.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-07-01T00:05:32.000Z (over 1 year ago)
- Last Synced: 2024-05-02T06:00:57.990Z (9 months ago)
- Topics: file-matching, glob, pattern-matching, php, regex, regular-expression
- Language: PHP
- Homepage: https://packagist.org/packages/phlak/splat
- Size: 97.7 KB
- Stars: 108
- Watchers: 3
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
---
Glob-like file and pattern matching utility.
Requirements
------------
- [PHP](https://www.php.net/) >= 8.1
Installation
------------
Install Splat with Composer.
composer require phlak/splat
Then import the `Glob` or `Pattern` classes as needed.
```php
use PHLAK\Splat\Glob;
use PHLAK\Splat\Pattern;
```
Patterns
--------
`Glob` methods accept a `$pattern` as the first parameter. This can be a string
or an instance of `\PHLAK\Splat\Pattern`.
```php
$pattern = new Pattern(...);
$pattern = Pattern::make(...);
```
A pattern string may contain one or more of the following special matching
expressions.
### Matching Expressions
- `?` matches any single character
- `*` matches zero or more characters excluding `/` (`\` on Windows)
- `**` matches zero or more characters including `/` (`\` on Windows)
- `[abc]` matches a single character from the set (i.e. `a`, `b` or `c`)
- `[a-c]` matches a single character in the range (i.e. `a`, `b` or `c`)
- `[!abc]` matches any character not in the set (i.e. not `a`, `b` or `c`)
- `[!a-c]` matches any character not in the range (i.e. not `a`, `b` or `c`)
- `{foo,bar,baz}` matches any pattern in the set (i.e. `foo`, `bar` or `baz`)
- Sets may contain other matching patterns (i.e. `{foo,ba[rz]}`)
### Assertions
The following assertions can be use to assert that a string is followed by, or
not followed by, another pattern.
- `(=foo)` matches any string that also contains `foo`
- `(!foo)` matches any string that does not also contain `foo`
For example, a pattern of `*.tar(!.{gz,xz})` will match a string ending with
`.tar` or `.tar.bz` but not `tar.gz` or `tar.xz`.
### Converting Patterns To Regular Expressions
Glob patterns can be converted to a regular expression pattern.
```php
Pattern::make('foo')->toRegex(); // Returns '#^foo$#'
Pattern::make('foo/bar.txt')->toRegex(); // Returns '#^foo/bar\.txt$#'
Pattern::make('file.{yml,yaml}')->toRegex(); // Returns '#^file\.(yml|yaml)$#'
```
You can control regular expression line anchors via the `$anchors` parameter.
```php
use PHLAK\Splat\Anchors;
use PHLAK\Splat\Pattern;
Pattern::make('foo')->toRegex(Anchors::NONE); // Returns '#foo#'
Pattern::make('foo')->toRegex(Anchors::START); // Returns '#^foo#'
Pattern::make('foo')->toRegex(Anchors::END); // Returns '#foo$#'
Pattern::make('foo')->toRegex(Anchors::BOTH); // Returns '#^foo$#'
```
### Pattern Character Escaping
Sometimes you may have characters in a string that shouldn't be treated as
matching expression characters. In those situations you can escape any character
by preceeding it with a backslash (`\`).
```php
Pattern::make('What is happening\?');
Pattern::make('Wall-E \[2008\].mp4');
```
You may also escape glob pattern characters from a string programmatically with
the `Pattern::escape()` method.
```php
Pattern::escape('What is happening?'); // Returns 'What is happening\?'
Pattern::escape('*.{yml,yaml}'); // Returns '\*.\{yml\,yaml\}'
Pattern::escape('[Ss]pl*t.txt'); // Returns '\[Ss\]pl\*t.txt'
```
Methods
-------
### Files In
Get a list of files in a directory matching a glob pattern.
```php
Glob::in('**.txt', 'some/file/path');
```
Returns a [Symfony Finder Component](https://symfony.com/doc/current/components/finder.html)
containing the files matching the glob pattern within the specified directory
(e.g. `foo.txt`, `foo/bar.txt`, `foo/bar/baz.txt`, etc.).
---
### Exact Match
Test if a string matches a glob pattern.
```php
Glob::match('*.txt', 'foo.txt'); // true
Glob::match('*.txt', 'foo.log'); // false
```
---
### Match Start
Test if a string starts with a glob pattern.
```php
Glob::matchStart('foo/*', 'foo/bar.txt'); // true
Glob::matchStart('foo/*', 'bar/foo.txt'); // false
```
---
### Match End
Test if a string ends with a glob pattern.
```php
Glob::matchEnd('**.txt', 'foo/bar.txt'); // true
Glob::matchEnd('**.txt', 'foo/bar.log'); // false
```
---
### Match Within
Test if a string contains a glob pattern.
```php
Glob::matchWithin('bar', 'foo/bar/baz.txt'); // true
Glob::matchWithin('bar', 'foo/baz/qux.txt'); // false
```
---
### Filter an Array (of Strings)
Filter an array of strings to values matching a glob pattern.
```php
Glob::filter('**.txt', [
'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
]);
// Returns ['foo.txt', 'foo/bar.txt']
```
---
### Reject an Array (of Strings)
Filter an array of strings to values *not* matching a glob pattern.
```php
Glob::reject('**.txt', [
'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
]);
// Returns ['foo', 'bar.zip', 'foo/bar.png']
```
Changelog
---------
A list of changes can be found on the [GitHub Releases](https://github.com/PHLAK/Splat/releases) page.
Troubleshooting
---------------
For general help and support join our [GitHub Discussion](https://github.com/PHLAK/Splat/discussions) or reach out on [Bluesky](https://bsky.app/profile/phlak.dev).
Please report bugs to the [GitHub Issue Tracker](https://github.com/PHLAK/Splat/issues).
Copyright
---------
This project is licensed under the [MIT License](https://github.com/PHLAK/Splat/blob/master/LICENSE).