From 5d0c4ca6ab3953da1b521320eae88eb64a0efc76 Mon Sep 17 00:00:00 2001
From: Chris Kankiewicz
Date: Sun, 16 May 2021 17:34:32 -0700
Subject: [PATCH] Updated the README
---
README.md | 191 +++++++++++++++++++++++++++---------------------------
1 file changed, 95 insertions(+), 96 deletions(-)
diff --git a/README.md b/README.md
index d1cfeea..5b848ff 100644
--- a/README.md
+++ b/README.md
@@ -3,15 +3,14 @@
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
---
@@ -26,25 +25,25 @@ Requirements
Installation
------------
- composer require phlak/splat
+Install Splat with Composer.
-Usage
--------------
+ composer require phlak/splat
-### Initialization
+Then import the `Glob` or `Pattern` classes as needed.
- ```php
- use PHLAK\Splat\Glob;
+```php
+use PHLAK\Splat\Glob;
+use PHLAK\Splat\Pattern;
+```
- new Glob($pattern);
- // or
- Glob::pattern($pattern);
- ```
+Patterns
+--------
-When instantiating a `Glob` object you must supply a `$pattern` string that may
-contain one or more of the following special matching expressions.
+`Glob` methods accept a `$pattern` as the first parameter. This can be a string
+or an instance of `\PHLAK\Splat\Pattern`. A pattern string may contain one or
+more of the following special matching expressions.
-#### Matching Expressions
+### Matching Expressions
- `?` matches any single character
- `*` matches zero or more characters excluding `/` (`\` on Windows)
@@ -55,10 +54,10 @@ contain one or more of the following special matching expressions.
- `[^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`)
-#### Assertions
+### Assertions
The following assertions can be use to assert that a string is followed by or
-not followed by another pattern.
+not followed by another pattern.
- `(=foo)` matches any string that also contains `foo`
- `(!foo)` matches any string that does not also contain `foo`
@@ -66,15 +65,48 @@ not followed by another pattern.
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
+
+Convet a glob pattern 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 also control line anchors via the `$options` parameter.
+
+```php
+Pattern::make('foo')->toRegex(Glob::NO_ANCHORS); // Returns '#foo#'
+Pattern::make('foo')->toRegex(Glob::START_ANCHOR); // Returns '#^foo#'
+Pattern::make('foo')->toRegex(Glob::END_ANCHOR); // Returns '#foo$#'
+Pattern::make('foo')->toRegex(Glob::BOTH_ANCHORS); // Returns '#^foo$#'
+Pattern::make('foo')->toRegex(Glob::START_ANCHOR | Glob::END_ANCHOR); // Returns '#^foo$#'
+```
+
---
+### Escape
+
+Escape glob pattern characters from a string.
+
+```php
+Pattern::escape('What?'); // Returns 'What\?'
+Pattern::escape('*.{yml,yaml}'); // Returns '\*.\{yml\,yaml\}'
+Pattern::escape('[Gg]l*b.txt'); // Returns '\[Gg\]l\*b.txt'
+```
+
+Methods
+-------
+
### Files In
-Get a list of files in a directory matching the glob pattern.
+Get a list of files in a directory matching a glob pattern.
- ```php
- Glob::pattern('**.txt')->in('some/file/path');
- ```
+```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
@@ -84,107 +116,74 @@ containing the files matching the glob pattern within the specified directory
### Exact Match
-Test if a string matches the glob pattern.
+Test if a string matches a glob pattern.
- ```php
- Glob::pattern('*.txt')->match('foo.txt'); // true
- Glob::pattern('*.txt')->match('foo.log'); // false
- ```
+```php
+Glob::match('*.txt', 'foo.txt'); // true
+Glob::match('*.txt', 'foo.log'); // false
+```
---
### Match Start
-Test if a string starts with the glob pattern.
+Test if a string starts with a glob pattern.
- ```php
- Glob::pattern('foo/*')->matchStart('foo/bar.txt'); // true
- Glob::pattern('foo/*')->matchStart('bar/foo.txt'); // false
- ```
+```php
+Glob::matchStart('foo/*', 'foo/bar.txt'); // true
+Glob::matchStart('foo/*', 'bar/foo.txt'); // false
+```
---
### Match End
-Test if a string ends with the glob pattern.
+Test if a string ends with a glob pattern.
- ```php
- Glob::pattern('**.txt')->matchEnd('foo/bar.txt'); // true
- Glob::pattern('**.txt')->matchEnd('foo/bar.log'); // false
- ```
+```php
+Glob::matchEnd('**.txt', 'foo/bar.txt'); // true
+Glob::matchEnd('**.txt', 'foo/bar.log'); // false
+```
---
### Match Within
-Test if a string contains the glob pattern.
+Test if a string contains a glob pattern.
- ```php
- Glob::pattern('bar')->matchWithin('foo/bar/baz.txt'); // true
- Glob::pattern('bar')->matchWithin('foo/baz/qux.txt'); // false
- ```
+```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 the glob pattern.
+Filter an array of strings to values matching a glob pattern.
- ```php
- Glob::pattern('**.txt')->filter([
- 'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
- ]);
+```php
+Glob::pattern('**.txt')->filter([
+ 'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
+]);
- // Returns ['foo.txt', 'foo/bar.txt']
- ```
+// Returns ['foo.txt', 'foo/bar.txt']
+```
---
### Reject an Array (of Strings)
-Filter an array of strings to values *not* matching the glob pattern.
+Filter an array of strings to values *not* matching a glob pattern.
- ```php
- Glob::pattern('**.txt')->reject([
- 'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
- ]);
+```php
+Glob::pattern('**.txt')->reject([
+ 'foo', 'foo.txt', 'bar.zip', 'foo/bar.png', 'foo/bar.txt',
+]);
- // Returns ['foo', 'bar.zip', 'foo/bar.png']
- ```
-
----
-
-### To Regular Expression
-
-Convet the glob pattern to a regular expression pattern.
-
- ```php
- Glob::pattern('foo')->toRegex(); // Returns '#^foo$#'
- Glob::pattern('foo/bar.txt')->toRegex(); // Returns '#^foo/bar\.txt$#'
- Glob::pattern('file.{yml,yaml}')->toRegex(); // Returns '#^file\.(yml|yaml)$#'
- ```
-
- You can also control line anchors via the `$options` parameter.
-
- ```php
- Glob::pattern('foo')->toRegex(Glob::NO_ANCHORS); // Returns '#foo#'
- Glob::pattern('foo')->toRegex(Glob::START_ANCHOR); // Returns '#^foo#'
- Glob::pattern('foo')->toRegex(Glob::END_ANCHOR); // Returns '#foo$#'
- Glob::pattern('foo')->toRegex(Glob::BOTH_ANCHORS); // Returns '#^foo$#'
- Glob::pattern('foo')->toRegex(Glob::START_ANCHOR | Glob::END_ANCHOR); // Returns '#^foo$#'
- ```
-
----
-
-### Escape
-
-Escape glob pattern characters from a string.
+// Returns ['foo', 'bar.zip', 'foo/bar.png']
+```
- ```php
- Glob::escape('What?'); // Returns 'What\?'
- Glob::escape('*.{yml,yaml}'); // Returns '\*.\{yml\,yaml\}'
- Glob::escape('[Gg]l*b.txt'); // Returns '\[Gg\]l\*b.txt'
- ```
Changelog
---------
@@ -194,7 +193,7 @@ A list of changes can be found on the [GitHub Releases](https://github.com/PHLAK
Troubleshooting
---------------
-For general help and support join our [Spectrum Community](https://spectrum.chat/phlaknet) or reach out on [Twitter](https://twitter.com/PHLAK).
+For general help and support join our [GitHub Discussion](https://github.com/PHLAK/Splat/discussions) or reach out on [Twitter](https://twitter.com/PHLAK).
Please report bugs to the [GitHub Issue Tracker](https://github.com/PHLAK/Splat/issues).