Added Await::trap()

[codecov[bot]]

Codecov Report

Patch coverage: 3.84% and project coverage change: -6.33 :warning:

Comparison is base (fcc0266) 99.45% compared to head (301906e) 93.12%.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #106 +/- ## ============================================ - Coverage 99.45% 93.12% -6.33% - Complexity 129 144 +15 ============================================ Files 10 10 Lines 367 393 +26 ============================================ + Hits 365 366 +1 - Misses 2 27 +25 ``` | [Impacted Files](https://codecov.io/gh/SOF3/await-generator/pull/106?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Jonathan+Chan+Kwan+Yin) | Coverage Δ | | |---|---|---| | [await-generator/src/SOFe/AwaitGenerator/Await.php](https://codecov.io/gh/SOF3/await-generator/pull/106?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Jonathan+Chan+Kwan+Yin#diff-YXdhaXQtZ2VuZXJhdG9yL3NyYy9TT0ZlL0F3YWl0R2VuZXJhdG9yL0F3YWl0LnBocA==) | `89.49% <3.84%> (-10.51%)` | :arrow_down: | Help us with your feedback. Take ten seconds to tell us [how you rate us](https://about.codecov.io/nps?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Jonathan+Chan+Kwan+Yin). Have a feature suggestion? [Share it here.](https://app.codecov.io/gh/feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=Jonathan+Chan+Kwan+Yin)

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Do you have feedback about the report comment? Let us know in this issue.

[ColinHDev]

I don't think it helps, but I came up with the following for the basic annotations

/**
 * Wraps a generator that executes some action before and after suspension points (`yield`s).
 * @phpstan-template TKey
 * @phpstan-template TValue
 * @phpstan-template TSend
 * @phpstan-template TReturn
 * @phpstan-param Generator<TKey, TValue, TSend, TReturn> $generator
 * @phpstan-param Closure(Generator, TValue, TKey): bool $beforeSuspend
 * @phpstan-param Closure(Generator, TValue, TKey, TSend): bool $afterSuspend
 * @phpstan-return Generator<TKey, TValue, TSend, TReturn>
 */
public static function trap(Generator $generator, Closure $beforeSuspend, Closure $afterSuspend) : Generator {

(https://github.com/ColinHDev/await-generator/blob/trap/await-generator/src/SOFe/AwaitGenerator/Await.php#L194-L201)

[SOF3]

I don't think it helps, but I came up with the following for the basic annotations

/**
 * Wraps a generator that executes some action before and after suspension points (`yield`s).
 * @phpstan-template TKey
 * @phpstan-template TValue
 * @phpstan-template TSend
 * @phpstan-template TReturn
 * @phpstan-param Generator<TKey, TValue, TSend, TReturn> $generator
 * @phpstan-param Closure(Generator, TValue, TKey): bool $beforeSuspend
 * @phpstan-param Closure(Generator, TValue, TKey, TSend): bool $afterSuspend
 * @phpstan-return Generator<TKey, TValue, TSend, TReturn>
 */
public static function trap(Generator $generator, Closure $beforeSuspend, Closure $afterSuspend) : Generator {

(https://github.com/ColinHDev/await-generator/blob/trap/await-generator/src/SOFe/AwaitGenerator/Await.php#L194-L201)

Please send a pull request

[Endermanbugzjfc]

How to use this? Does it run the closures for every yield in a generator?

[SOF3]

How to use this? Does it run the closures for every yield in a generator?

Yep, and you can intercept the signals to see what it is suspending for.

[Endermanbugzjfc]

No idea how to use sorry.

<?php

declare(strict_types=1);

require("../../vendor/autoload.php");

function gen() : Generator
{
    yield from gen2();
}

function gen2() : Generator
{
    yield from [];
}

\SOFe\AwaitGenerator\Await::f2c(function () : Generator {
    yield from \SOFe\AwaitGenerator\Await::trap(
        gen(),
        fn (...$args) => var_dump(
            "a1",
            $args
        ),
        fn (...$args) => var_dump(
            "a2",
            $args
        )
    );
});

/Users/Eurus/Documents/Dev/PocketMine-MP/4/bin/php7/bin/php /Users/Eurus/Documents/Dev/PocketMine-MP/projects/GlassPain/GlassPain/src/asd.php

Process finished with exit code 0

[SOF3]

No idea how to use sorry.

<?php

declare(strict_types=1);

require("../../vendor/autoload.php");

function gen() : Generator
{
    yield from gen2();
}

function gen2() : Generator
{
    yield from [];
}

\SOFe\AwaitGenerator\Await::f2c(function () : Generator {
    yield from \SOFe\AwaitGenerator\Await::trap(
        gen(),
        fn (...$args) => var_dump(
            "a1",
            $args
        ),
        fn (...$args) => var_dump(
            "a2",
            $args
        )
    );
});

/Users/Eurus/Documents/Dev/PocketMine-MP/4/bin/php7/bin/php /Users/Eurus/Documents/Dev/PocketMine-MP/projects/GlassPain/GlassPain/src/asd.php

Process finished with exit code 0

For example, the Traverser class can be implemented using Await::trap.

I am thinking about providing a better API so that I don't have to expose the internal constants like Await::ONCE. This pull request is just a preview for now.

[Endermanbugzjfc]

Oh I didn't realise there is a test file.