Implement Value::peek()

munusphp · Dec 16, 2019 · 233ce55 · 233ce55
1 parent 9678480
commit 233ce55
Show file tree

Hide file tree

Showing 21 changed files with 340 additions and 80 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,12 @@
+* text=auto
+
+/tests export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/.php_cs export-ignore
+/buddy.yml export-ignore
+/CONTRIBUTING.md export-ignore
+/phpstan.neon export-ignore
+/phpunit.xml export-ignore
+/psalm.baseline.xml export-ignore
+/psalm.xml export-ignore
diff --git a/.php_cs b/.php_cs
@@ -12,7 +12,7 @@ return PhpCsFixer\Config::create()
         '@Symfony' => true,
         'array_syntax' => ['syntax' => 'short'],
         'no_superfluous_elseif' => true,
-        'no_superfluous_phpdoc_tags' => true,
+        'no_superfluous_phpdoc_tags' => ['allow_mixed' => true],
         'no_unreachable_default_argument_value' => true,
         'no_useless_else' => true,
         'no_useless_return' => true,

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,14 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+- Value: Lazy, Either, Option, TryTo
+- Traversable: Stream, Set, Map, GenericList
+- Tuple
+- Stream collectors
+- Iterators
+- Value comparator
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,56 @@
+# Contributing to Munus
+
+Munus is an open source project. If you'd like to contribute, please read the following text. Before we can merge your 
+pull request, here are some guidelines that you need to follow. These guidelines exist not to annoy you, but to keep the 
+code base clean, unified and future proof.
+
+## Branch
+
+You should only open pull requests against the `master` branch.
+
+## Unit Tests
+
+Please try to add a test for your pull request. You can run the unit-tests by calling:
+
+```bash
+vendor/bin/phpunit
+```
+
+## Build
+
+GitHub automatically run your pull request through GitHub Action.
+If you break the tests, we cannot merge your code, so please make sure that your code is working before opening up a pull request.
+
+## Merge
+
+Please give us time to review your pull requests. We will give our best to review everything as fast as possible.
+
+## Coding Standards & Static Analysis
+
+When contributing code to Munus, you must follow its coding standards. To do that, just run:
+
+```bash
+composer fix-cs
+```
+[More about Php-Cs-fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer)
+
+Code has to also pass static analysis by [PHPStan](https://github.com/phpstan/phpstan):
+
+```bash
+composer phpstan
+```
+
+and by [Psalm](https://github.com/vimeo/psalm):
+
+```bash
+composer psalm
+```
+
+## Documentation
+
+Please update the documentation pages if necessary.
+You can find them in this repository [munusphp/website](https://github.com/munusphp/website)
+
+---
+
+Thank you very much for contribution!
diff --git a/psalm.xml b/psalm.xml
@@ -20,109 +20,109 @@
 
         <!-- level 3 issues - slightly lazy code writing, but provably low false-negatives -->
 
-        <DeprecatedMethod errorLevel="info"/>
-        <DeprecatedProperty errorLevel="info"/>
-        <DeprecatedClass errorLevel="info"/>
-        <DeprecatedConstant errorLevel="info"/>
-        <DeprecatedFunction errorLevel="info"/>
-        <DeprecatedInterface errorLevel="info"/>
-        <DeprecatedTrait errorLevel="info"/>
-
-        <InternalMethod errorLevel="info"/>
-        <InternalProperty errorLevel="info"/>
-        <InternalClass errorLevel="info"/>
+        <DeprecatedMethod errorLevel="error"/>
+        <DeprecatedProperty errorLevel="error"/>
+        <DeprecatedClass errorLevel="error"/>
+        <DeprecatedConstant errorLevel="error"/>
+        <DeprecatedFunction errorLevel="error"/>
+        <DeprecatedInterface errorLevel="error"/>
+        <DeprecatedTrait errorLevel="error"/>
+
+        <InternalMethod errorLevel="error"/>
+        <InternalProperty errorLevel="error"/>
+        <InternalClass errorLevel="error"/>
 
         <MissingClosureReturnType errorLevel="info"/>
         <MissingReturnType errorLevel="info"/>
         <MissingPropertyType errorLevel="info"/>
-        <InvalidDocblock errorLevel="info"/>
-        <MisplacedRequiredParam errorLevel="info"/>
+        <InvalidDocblock errorLevel="error"/>
+        <MisplacedRequiredParam errorLevel="error"/>
 
-        <PropertyNotSetInConstructor errorLevel="info"/>
-        <MissingConstructor errorLevel="info"/>
+        <PropertyNotSetInConstructor errorLevel="error"/>
+        <MissingConstructor errorLevel="error"/>
         <MissingClosureParamType errorLevel="info"/>
-        <MissingParamType errorLevel="info"/>
+        <MissingParamType errorLevel="error"/>
 
-        <RedundantCondition errorLevel="info"/>
+        <RedundantCondition errorLevel="error"/>
 
-        <DocblockTypeContradiction errorLevel="info"/>
-        <RedundantConditionGivenDocblockType errorLevel="info"/>
+        <DocblockTypeContradiction errorLevel="error"/>
+        <RedundantConditionGivenDocblockType errorLevel="error"/>
 
-        <UnresolvableInclude errorLevel="info"/>
+        <UnresolvableInclude errorLevel="error"/>
 
-        <RawObjectIteration errorLevel="info"/>
+        <RawObjectIteration errorLevel="error"/>
 
-        <InvalidStringClass errorLevel="info"/>
+        <InvalidStringClass errorLevel="error"/>
 
         <!-- level 4 issues - points to possible deficiencies in logic, higher false-positives -->
 
         <MoreSpecificReturnType errorLevel="info"/>
-        <LessSpecificReturnStatement errorLevel="info"/>
+        <LessSpecificReturnStatement errorLevel="error"/>
         <TypeCoercion errorLevel="info"/>
 
-        <PossiblyFalseArgument errorLevel="info"/>
-        <PossiblyFalseIterator errorLevel="info"/>
-        <PossiblyFalseOperand errorLevel="info"/>
-        <PossiblyFalsePropertyAssignmentValue errorLevel="info"/>
-        <PossiblyFalseReference errorLevel="info"/>
-        <PossiblyInvalidArgument errorLevel="info"/>
-        <PossiblyInvalidArrayAccess errorLevel="info"/>
-        <PossiblyInvalidArrayAssignment errorLevel="info"/>
-        <PossiblyInvalidArrayOffset errorLevel="info"/>
-        <PossiblyInvalidCast errorLevel="info"/>
-        <PossiblyInvalidFunctionCall errorLevel="info"/>
-        <PossiblyInvalidIterator errorLevel="info"/>
-        <PossiblyInvalidMethodCall errorLevel="info"/>
-        <PossiblyInvalidOperand errorLevel="info"/>
-        <PossiblyInvalidPropertyAssignment errorLevel="info"/>
-        <PossiblyInvalidPropertyAssignmentValue errorLevel="info"/>
-        <PossiblyInvalidPropertyFetch errorLevel="info"/>
-        <PossiblyNullArgument errorLevel="info"/>
-        <PossiblyNullArrayAccess errorLevel="info"/>
-        <PossiblyNullArrayAssignment errorLevel="info"/>
-        <PossiblyNullArrayOffset errorLevel="info"/>
-        <PossiblyNullFunctionCall errorLevel="info"/>
-        <PossiblyNullIterator errorLevel="info"/>
-        <PossiblyNullOperand errorLevel="info"/>
-        <PossiblyNullPropertyAssignment errorLevel="info"/>
-        <PossiblyNullPropertyAssignmentValue errorLevel="info"/>
-        <PossiblyNullPropertyFetch errorLevel="info"/>
-        <PossiblyNullReference errorLevel="info"/>
-        <PossiblyUndefinedGlobalVariable errorLevel="info"/>
-        <PossiblyUndefinedVariable errorLevel="info"/>
-        <PossiblyUndefinedArrayOffset errorLevel="info"/>
-        <PossiblyUndefinedMethod errorLevel="info"/>
-        <PossibleRawObjectIteration errorLevel="info"/>
+        <PossiblyFalseArgument errorLevel="error"/>
+        <PossiblyFalseIterator errorLevel="error"/>
+        <PossiblyFalseOperand errorLevel="error"/>
+        <PossiblyFalsePropertyAssignmentValue errorLevel="error"/>
+        <PossiblyFalseReference errorLevel="error"/>
+        <PossiblyInvalidArgument errorLevel="error"/>
+        <PossiblyInvalidArrayAccess errorLevel="error"/>
+        <PossiblyInvalidArrayAssignment errorLevel="error"/>
+        <PossiblyInvalidArrayOffset errorLevel="error"/>
+        <PossiblyInvalidCast errorLevel="error"/>
+        <PossiblyInvalidFunctionCall errorLevel="error"/>
+        <PossiblyInvalidIterator errorLevel="error"/>
+        <PossiblyInvalidMethodCall errorLevel="error"/>
+        <PossiblyInvalidOperand errorLevel="error"/>
+        <PossiblyInvalidPropertyAssignment errorLevel="error"/>
+        <PossiblyInvalidPropertyAssignmentValue errorLevel="error"/>
+        <PossiblyInvalidPropertyFetch errorLevel="error"/>
+        <PossiblyNullArgument errorLevel="error"/>
+        <PossiblyNullArrayAccess errorLevel="error"/>
+        <PossiblyNullArrayAssignment errorLevel="error"/>
+        <PossiblyNullArrayOffset errorLevel="error"/>
+        <PossiblyNullFunctionCall errorLevel="error"/>
+        <PossiblyNullIterator errorLevel="error"/>
+        <PossiblyNullOperand errorLevel="error"/>
+        <PossiblyNullPropertyAssignment errorLevel="error"/>
+        <PossiblyNullPropertyAssignmentValue errorLevel="error"/>
+        <PossiblyNullPropertyFetch errorLevel="error"/>
+        <PossiblyNullReference errorLevel="error"/>
+        <PossiblyUndefinedGlobalVariable errorLevel="error"/>
+        <PossiblyUndefinedVariable errorLevel="error"/>
+        <PossiblyUndefinedArrayOffset errorLevel="error"/>
+        <PossiblyUndefinedMethod errorLevel="error"/>
+        <PossibleRawObjectIteration errorLevel="error"/>
 
         <!-- level 5 issues - should be avoided at most costs... -->
 
-        <ForbiddenCode errorLevel="info"/>
-        <ImplicitToStringCast errorLevel="info"/>
+        <ForbiddenCode errorLevel="error"/>
+        <ImplicitToStringCast errorLevel="error"/>
         <InvalidScalarArgument errorLevel="info"/>
-        <InvalidToString errorLevel="info"/>
-        <InvalidOperand errorLevel="info"/>
-        <NoInterfaceProperties errorLevel="info"/>
-        <TooManyArguments errorLevel="info"/>
-        <TypeDoesNotContainType errorLevel="info"/>
-        <TypeDoesNotContainNull errorLevel="info"/>
-        <MissingDocblockType errorLevel="info"/>
+        <InvalidToString errorLevel="error"/>
+        <InvalidOperand errorLevel="error"/>
+        <NoInterfaceProperties errorLevel="error"/>
+        <TooManyArguments errorLevel="error"/>
+        <TypeDoesNotContainType errorLevel="error"/>
+        <TypeDoesNotContainNull errorLevel="error"/>
+        <MissingDocblockType errorLevel="error"/>
         <ImplementedReturnTypeMismatch errorLevel="info"/>
-        <ImplementedParamTypeMismatch errorLevel="info"/>
+        <ImplementedParamTypeMismatch errorLevel="error"/>
 
         <!-- level 6 issues - really bad things -->
 
-        <InvalidNullableReturnType errorLevel="info"/>
-        <NullableReturnStatement errorLevel="info"/>
-        <InvalidFalsableReturnType errorLevel="info"/>
-        <FalsableReturnStatement errorLevel="info"/>
+        <InvalidNullableReturnType errorLevel="error"/>
+        <NullableReturnStatement errorLevel="error"/>
+        <InvalidFalsableReturnType errorLevel="error"/>
+        <FalsableReturnStatement errorLevel="error"/>
 
         <MoreSpecificImplementedParamType errorLevel="info"/>
         <LessSpecificImplementedReturnType errorLevel="info"/>
 
-        <InvalidReturnStatement errorLevel="info"/>
-        <InvalidReturnType errorLevel="info"/>
-        <UndefinedThisPropertyAssignment errorLevel="info"/>
-        <UndefinedInterfaceMethod errorLevel="info"/>
+        <InvalidReturnStatement errorLevel="error"/>
+        <InvalidReturnType errorLevel="error"/>
+        <UndefinedThisPropertyAssignment errorLevel="error"/>
+        <UndefinedInterfaceMethod errorLevel="error"/>
 
         <!-- level 7 issues - even worse -->
 

diff --git a/src/Collection/Map.php b/src/Collection/Map.php
@@ -48,6 +48,11 @@ public static function fromArray(array $array): self
         return self::fromPointer($map);
     }
 
+    /**
+     * @param array<string,V> $map
+     *
+     * @return Map<string,V>
+     */
     private static function fromPointer(array &$map): self
     {
         $newMap = new self();

diff --git a/src/Collection/Set.php b/src/Collection/Set.php
@@ -62,6 +62,11 @@ public function length(): int
         return count($this->elements);
     }
 
+    /**
+     * @param T $element
+     *
+     * @return Set<T>
+     */
     public function add($element): self
     {
         if ($this->contains($element)) {
@@ -74,6 +79,11 @@ public function add($element): self
         return self::fromPointer($elements);
     }
 
+    /**
+     * @param T $element
+     *
+     * @return Set<T>
+     */
     public function remove($element): self
     {
         if (!$this->contains($element)) {

diff --git a/src/Collection/Stream.php b/src/Collection/Stream.php
@@ -7,6 +7,7 @@
 use Munus\Collection\Stream\Collector;
 use Munus\Collection\Stream\Cons;
 use Munus\Collection\Stream\EmptyStream;
+use Munus\Value;
 
 /**
  * @template T
@@ -17,7 +18,7 @@ abstract class Stream extends Traversable
     /**
      * @param array<int,T> $elements
      *
-     * @return Cons<T>
+     * @return Stream<T>
      */
     public static function of(...$elements): self
     {
@@ -48,7 +49,7 @@ public static function empty(): self
     }
 
     /**
-     * @return Cons<int>
+     * @return Stream<int>
      */
     public static function range(int $start = 1, ?int $end = null): self
     {
@@ -128,6 +129,25 @@ public static function cons($head, callable $supplier): self
      */
     abstract public function tail();
 
+    /**
+     * @param callable(T):void $action
+     *
+     * @return Stream<T>
+     */
+    public function peek(callable $action): self
+    {
+        if ($this->isEmpty()) {
+            return $this;
+        }
+
+        $head = $this->head();
+        $action($head);
+
+        return new Cons($head, function () use ($action) {
+            return $this->tail()->peek($action);
+        });
+    }
+
     /**
      * @template U
      *

diff --git a/src/Control/Either.php b/src/Control/Either.php
@@ -20,11 +20,21 @@ private function __construct()
     {
     }
 
+    /**
+     * @param L $left
+     *
+     * @return Either<L,R>
+     */
     final public static function left($left): self
     {
         return new Left($left);
     }
 
+    /**
+     * @param R $right
+     *
+     * @return Either<L,R>
+     */
     final public static function right($right): self
     {
         return new Right($right);