From f84063dc7db5cb2fe812e5631d0265dc931c5550 Mon Sep 17 00:00:00 2001 From: Pol Dellaiera Date: Wed, 14 Oct 2020 21:09:16 +0200 Subject: [PATCH] docs: Update documentation. Signed-off-by: Pol Dellaiera --- README.md | 2 +- docs/index.rst | 108 +++++++++++++++++++++++++++++++++++++++++++-- docs/pages/api.rst | 2 + 3 files changed, 108 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index ab1e4f85f..857c619a6 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ On top of this, this library: * uses [S.O.L.I.D. principles][solid on wikipedia], * does not have any external dependency, * fully tested, - * type safe (_type safe @ > 94%_), + * type safe (_type safe @ > 95%_), * framework agnostic. Except a few methods, most methods are [pure][pure function on wikipedia] and return a diff --git a/docs/index.rst b/docs/index.rst index c235d4040..853e80a92 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ -Collection -========== +PHP Collection +============== Collection is a functional utility library for PHP greater than 7.1.3. @@ -25,7 +25,7 @@ On top of this, this library: * uses `S.O.L.I.D. principles`_, * does not have any external dependency, * fully tested, - * type safe (*type safe @ > 98%*), + * type safe (*type safe @ > 95%*), * framework agnostic. Except a few methods, most methods are `pure`_ and return a `new Collection object`_. @@ -45,9 +45,100 @@ This library has been inspired by: * `mtdowling/transducers`_ * `Ruby Array`_ * `Collect.js`_ + * `Rambda`_ * `nikic/iter`_ + * `Haskell`_ * `Lazy.js`_ +Features +-------- + +- **Decoupled**: Each Collection methods is a shortcut to one isolated + standard class, each operation has its own responsibility. Usually + the arguments needed are standard PHP variables like ``int``, + ``string``, ``callable`` or ``iterator``. It allows users to use + those operations individually, at their own will to build up + something custom. Currently, more than :ref:`80 operations ` + are available in this library. This library is basically an + example of what you can do with all those small bricks, but nothing + prevent users to use an operation on its own as well. + +- **It takes function first, data-last**: In the following example, + multiple operations are created. The data to be operated on is + generally supplied at last. + + .. code:: php + + 'foo' !== $userId; + + // Using the Collection library + $collection = Collection::fromIterable($data) + ->filter($filterCallback) + ->reverse(); + print_r($collection->all()); // ['baz', 'bar'] + + // Using single operations. + $filter = Filter::of()($filterCallback); + $reverse = Reverse::of(); + $pipe = Pipe::of()($reverse, $filter); + + print_r(iterator_to_array($pipe(new ArrayIterator($data)))); // ['baz', 'bar'] + + More information about this in the `Brian Lonsdorf's conference`_, + even if this is for Javascript, + those concepts are common to other programming languages. + + In a nutshell, the combination of currying and function-first enables + the developer to compose functions with very little code (*often in a + “point-free” fashion*), before finally passing in the relevant user + data. + +- **Operations are stateless and curried by default**: This currying + makes it easy to compose functions to create new functions. Because + the API is *function-first*, *data-last*, you can continue composing + and composing until you build up the function you need before + dropping in the data. See `this Hugh Jackson article`_ describing + the advantages of this style. + + In the following example, the well-known `flatMap`_ could + be composed of other operations as such: + + .. code:: php + + + Pipe::of()( + Map::of()($callable), + Flatten::of()(1), + Normalize::of() + ); + + $callback = fn(string $name): array => explode(',', $name); + + print_r(iterator_to_array($flatMap($callback)($userData))); // ['foo', 'bar', 'baz', 'john'] + + +On the internet +--------------- + + * `Reddit announcement thread`_ + * `Reddit release 2.0.0 thread`_ + * `Featured in PHPStorm Annotated August 2020`_ + +Changelog +--------- + +See `CHANGELOG.md`_ for a changelog based on `git commits`_. + +For more detailed changelogs, please check `the release changelogs`_. + .. _array_map(): https://www.php.net/array-map .. _array_filter(): https://www.php.net/array-filter .. _array_reduce(): https://www.php.net/array-reduce @@ -56,6 +147,8 @@ This library has been inspired by: .. _mtdowling/transducers: https://github.com/mtdowling/transducers.php .. _Ruby Array: https://ruby-doc.org/core-2.7.0/Array.html .. _Collect.js: https://collect.js.org +.. _Rambda: https://ramdajs.com/ +.. _Haskell: https://www.haskell.org/ .. _new Collection object: https://github.com/loophp/collection/blob/master/src/Collection.php .. _SplObjectStorage: https://www.php.net/manual/en/class.splobjectstorage.php .. _this example: https://loophp-collection.readthedocs.io/en/latest/pages/usage.html#manipulate-keys-and-values @@ -71,6 +164,15 @@ This library has been inspired by: .. _PSR-4: https://www.php-fig.org/psr/psr-4/ .. _PSR-12: https://www.php-fig.org/psr/psr-12/ .. _Ruby arrays: https://apidock.com/ruby/Array +.. _Brian Lonsdorf's conference: https://www.youtube.com/watch?v=m3svKOdZijA +.. _this Hugh Jackson article: http://hughfdjackson.com/javascript/why-curry-helps/ +.. _flatMap: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap +.. _Reddit announcement thread: https://www.reddit.com/r/PHP/comments/csxw23/a_stateless_and_modular_collection_class/ +.. _Reddit release 2.0.0 thread: https://www.reddit.com/r/PHP/comments/i2u2le/release_of_version_200_of_loophpcollection/ +.. _Featured in PHPStorm Annotated August 2020: https://blog.jetbrains.com/phpstorm/2020/08/php-annotated-august-2020/ +.. _CHANGELOG.md: https://github.com/loophp/collection/blob/master/CHANGELOG.md +.. _git commits: https://github.com/loophp/collection/commits/master +.. _the release changelogs: https://github.com/loophp/collection/releases .. toctree:: :hidden: diff --git a/docs/pages/api.rst b/docs/pages/api.rst index a519926b3..558ad09aa 100644 --- a/docs/pages/api.rst +++ b/docs/pages/api.rst @@ -1,3 +1,5 @@ +.. _api: + API ===