Merge pull request #43 from SimonFrings/functions

Improve documentation to use fully-qualified function names

Author: clue

README.md

@@ -10,10 +10,10 @@ A simple and modern approach to stream filtering in PHP
 * [Why?](#why)
 * [Support us](#support-us)
 * [Usage](#usage)
-  * [append()](#append)
-  * [prepend()](#prepend)
-  * [fun()](#fun)
-  * [remove()](#remove)
+    * [append()](#append)
+    * [prepend()](#prepend)
+    * [fun()](#fun)
+    * [remove()](#remove)
 * [Install](#install)
 * [Tests](#tests)
 * [License](#license)
@@ -58,26 +58,26 @@ Let's take these projects to the next level together! 🚀
 This lightweight library consists only of a few simple functions.
 All functions reside under the `Clue\StreamFilter` namespace.
 
-The below examples assume you use an import statement similar to this:
+The below examples refer to all functions with their fully-qualified names like this:
 
 ```php
-use Clue\StreamFilter as Filter;
-
-Filter\append(…);
+Clue\StreamFilter\append(…);
 ```
 
-Alternatively, you can also refer to them with their fully-qualified name:
+As of PHP 5.6+ you can also import each required function into your code like this:
 
 ```php
-\Clue\StreamFilter\append(…);
+use function Clue\StreamFilter\append;
+
+append(…);
 ```
 
-As of PHP 5.6+ you can also import each required function into your code like this:
+Alternatively, you can also use an import statement similar to this:
 
 ```php
-use function Clue\StreamFilter\append;
+use Clue\StreamFilter as Filter;
 
-append(…);
+Filter\append(…);
 ```
 
 ### append()
@@ -100,7 +100,7 @@ The `$callback` should be a valid callable function which accepts
 an individual chunk of data and should return the updated chunk:
 
 ```php
-$filter = Filter\append($stream, function ($chunk) {
+$filter = Clue\StreamFilter\append($stream, function ($chunk) {
     // will be called each time you read or write a $chunk to/from the stream
     return $chunk;
 });
@@ -109,7 +109,7 @@ $filter = Filter\append($stream, function ($chunk) {
 As such, you can also use native PHP functions or any other `callable`:
 
 ```php
-Filter\append($stream, 'strtoupper');
+Clue\StreamFilter\append($stream, 'strtoupper');
 
 // will write "HELLO" to the underlying stream
 fwrite($stream, 'hello');
@@ -119,7 +119,7 @@ If the `$callback` accepts invocation without parameters,
 then this signature will be invoked once ending (flushing) the filter:
 
 ```php
-Filter\append($stream, function ($chunk = null) {
+Clue\StreamFilter\append($stream, function ($chunk = null) {
     if ($chunk === null) {
         // will be called once ending the filter
         return 'end';
@@ -139,7 +139,7 @@ In order to play nice with PHP's stream handling,
 the `Exception` will be transformed to a PHP warning instead:
 
 ```php
-Filter\append($stream, function ($chunk) {
+Clue\StreamFilter\append($stream, function ($chunk) {
     throw new \RuntimeException('Unexpected chunk');
 });
 
@@ -151,12 +151,12 @@ The optional `$read_write` parameter can be used to only invoke the `$callback`
 when either writing to the stream or only when reading from the stream:
 
 ```php
-Filter\append($stream, function ($chunk) {
+Clue\StreamFilter\append($stream, function ($chunk) {
     // will be called each time you write to the stream
     return $chunk;
 }, STREAM_FILTER_WRITE);
 
-Filter\append($stream, function ($chunk) {
+Clue\StreamFilter\append($stream, function ($chunk) {
     // will be called each time you read from the stream
     return $chunk;
 }, STREAM_FILTER_READ);
@@ -186,7 +186,7 @@ This function prepends a filter to the start of this list.
 If the given filter can not be added, it throws an `Exception`.
 
 ```php
-$filter = Filter\prepend($stream, function ($chunk) {
+$filter = Clue\StreamFilter\prepend($stream, function ($chunk) {
     // will be called each time you read or write a $chunk to/from the stream
     return $chunk;
 });
@@ -208,7 +208,7 @@ Using `fun()` makes accessing these as easy as passing an input string to filter
 and getting the filtered output string.
 
 ```php
-$fun = Filter\fun('string.rot13');
+$fun = Clue\StreamFilter\fun('string.rot13');
 
 assert('grfg' === $fun('test'));
 assert('test' === $fun($fun('test'));
@@ -221,7 +221,7 @@ or parameters as Zend PHP.
 Accessing an unknown filter function will result in a `RuntimeException`:
 
 ```php
-Filter\fun('unknown'); // throws RuntimeException
+Clue\StreamFilter\fun('unknown'); // throws RuntimeException
 ```
 
 Some filters may accept or require additional filter parameters – most
@@ -234,7 +234,7 @@ Please refer to the individual filter definition for more details.
 For example, the `string.strip_tags` filter can be invoked like this:
 
 ```php
-$fun = Filter\fun('string.strip_tags', '<a><b>');
+$fun = Clue\StreamFilter\fun('string.strip_tags', '<a><b>');
 
 $ret = $fun('<b>h<br>i</b>');
 assert('<b>hi</b>' === $ret);
@@ -248,7 +248,7 @@ may use internal buffers and may emit a final data chunk on close.
 The filter function can be closed by invoking without any arguments:
 
 ```php
-$fun = Filter\fun('zlib.deflate');
+$fun = Clue\StreamFilter\fun('zlib.deflate');
 
 $ret = $fun('hello') . $fun('world') . $fun();
 assert('helloworld' === gzinflate($ret));
@@ -258,7 +258,7 @@ The filter function must not be used anymore after it has been closed.
 Doing so will result in a `RuntimeException`:
 
 ```php
-$fun = Filter\fun('string.rot13');
+$fun = Clue\StreamFilter\fun('string.rot13');
 $fun();
 
 $fun('test'); // throws RuntimeException
@@ -277,15 +277,15 @@ The `remove(resource<stream filter> $filter): bool` function can be used to
 remove a filter previously added via [`append()`](#append) or [`prepend()`](#prepend).
 
 ```php
-$filter = Filter\append($stream, function () {
+$filter = Clue\StreamFilter\append($stream, function () {
     // …
 });
-Filter\remove($filter);
+Clue\StreamFilter\remove($filter);
 ```
 
 ## Install
 
-The recommended way to install this library is [through Composer](https://getcomposer.org).
+The recommended way to install this library is [through Composer](https://getcomposer.org/).
 [New to Composer?](https://getcomposer.org/doc/00-intro.md)
 
 This project follows [SemVer](https://semver.org/).
@@ -300,13 +300,13 @@ See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades.
 This project aims to run on any platform and thus does not require any PHP
 extensions and supports running on legacy PHP 5.3 through current PHP 8+ and
 HHVM.
-It's *highly recommended to use PHP 7+* for this project.
+It's *highly recommended to use the latest supported PHP version* for this project.
 Older PHP versions may suffer from a number of inconsistencies documented above.
 
 ## Tests
 
 To run the test suite, you first need to clone this repo and then install all
-dependencies [through Composer](https://getcomposer.org):
+dependencies [through Composer](https://getcomposer.org/):
 
 ```bash
 $ composer install
@@ -315,7 +315,7 @@ $ composer install
 To run the test suite, go to the project root and run:
 
 ```bash
-$ php vendor/bin/phpunit
+$ vendor/bin/phpunit
 ```
 
 ## License

src/functions.php

@@ -20,7 +20,7 @@
  * an individual chunk of data and should return the updated chunk:
  *
  * ```php
- * $filter = Filter\append($stream, function ($chunk) {
+ * $filter = Clue\StreamFilter\append($stream, function ($chunk) {
  *     // will be called each time you read or write a $chunk to/from the stream
  *     return $chunk;
  * });
@@ -29,7 +29,7 @@
  * As such, you can also use native PHP functions or any other `callable`:
  *
  * ```php
- * Filter\append($stream, 'strtoupper');
+ * Clue\StreamFilter\append($stream, 'strtoupper');
  *
  * // will write "HELLO" to the underlying stream
  * fwrite($stream, 'hello');
@@ -39,7 +39,7 @@
  * then this signature will be invoked once ending (flushing) the filter:
  *
  * ```php
- * Filter\append($stream, function ($chunk = null) {
+ * Clue\StreamFilter\append($stream, function ($chunk = null) {
  *     if ($chunk === null) {
  *         // will be called once ending the filter
  *         return 'end';
@@ -59,7 +59,7 @@
  * the `Exception` will be transformed to a PHP warning instead:
  *
  * ```php
- * Filter\append($stream, function ($chunk) {
+ * Clue\StreamFilter\append($stream, function ($chunk) {
  *     throw new \RuntimeException('Unexpected chunk');
  * });
  *
@@ -71,12 +71,12 @@
  * when either writing to the stream or only when reading from the stream:
  *
  * ```php
- * Filter\append($stream, function ($chunk) {
+ * Clue\StreamFilter\append($stream, function ($chunk) {
  *     // will be called each time you write to the stream
  *     return $chunk;
  * }, STREAM_FILTER_WRITE);
  *
- * Filter\append($stream, function ($chunk) {
+ * Clue\StreamFilter\append($stream, function ($chunk) {
  *     // will be called each time you read from the stream
  *     return $chunk;
  * }, STREAM_FILTER_READ);
@@ -126,7 +126,7 @@ function append($stream, $callback, $read_write = STREAM_FILTER_ALL)
  * If the given filter can not be added, it throws an `Exception`.
  *
  * ```php
- * $filter = Filter\prepend($stream, function ($chunk) {
+ * $filter = Clue\StreamFilter\prepend($stream, function ($chunk) {
  *     // will be called each time you read or write a $chunk to/from the stream
  *     return $chunk;
  * });
@@ -168,7 +168,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL)
  * and getting the filtered output string.
  *
  * ```php
- * $fun = Filter\fun('string.rot13');
+ * $fun = Clue\StreamFilter\fun('string.rot13');
  *
  * assert('grfg' === $fun('test'));
  * assert('test' === $fun($fun('test'));
@@ -181,7 +181,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL)
  * Accessing an unknown filter function will result in a `RuntimeException`:
  *
  * ```php
- * Filter\fun('unknown'); // throws RuntimeException
+ * Clue\StreamFilter\fun('unknown'); // throws RuntimeException
  * ```
  *
  * Some filters may accept or require additional filter parameters – most
@@ -194,7 +194,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL)
  * For example, the `string.strip_tags` filter can be invoked like this:
  *
  * ```php
- * $fun = Filter\fun('string.strip_tags', '<a><b>');
+ * $fun = Clue\StreamFilter\fun('string.strip_tags', '<a><b>');
  *
  * $ret = $fun('<b>h<br>i</b>');
  * assert('<b>hi</b>' === $ret);
@@ -208,7 +208,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL)
  * The filter function can be closed by invoking without any arguments:
  *
  * ```php
- * $fun = Filter\fun('zlib.deflate');
+ * $fun = Clue\StreamFilter\fun('zlib.deflate');
  *
  * $ret = $fun('hello') . $fun('world') . $fun();
  * assert('helloworld' === gzinflate($ret));
@@ -218,7 +218,7 @@ function prepend($stream, $callback, $read_write = STREAM_FILTER_ALL)
  * Doing so will result in a `RuntimeException`:
  *
  * ```php
- * $fun = Filter\fun('string.rot13');
+ * $fun = Clue\StreamFilter\fun('string.rot13');
  * $fun();
  *
  * $fun('test'); // throws RuntimeException
@@ -288,10 +288,10 @@ function fun($filter, $parameters = null)
  * Remove a filter previously added via `append()` or `prepend()`.
  *
  * ```php
- * $filter = Filter\append($stream, function () {
+ * $filter = Clue\StreamFilter\append($stream, function () {
  *     // …
  * });
- * Filter\remove($filter);
+ * Clue\StreamFilter\remove($filter);
  * ```
  *
  * @param resource $filter