NAME

    PerlX::ScopeFunction - new keywords for creating scopes.

SYNOPSIS

        use PerlX::ScopeFunction qw( let with );
        use List::Util qw( sum0 );
        use List::MoreUtils qw( part minmax );
    
        with ( part { $_ % 2 } @input ) {
            my ($evens, $odds) = @_;
            say "There are " . scalar(@$evens) . " even numbers: " . join(" ", @$evens);
            say "There are " . scalar(@$odds) .  " odd numbers: " . join(" ", @$odds);
        }
    
        let ( ($min,$max) = minmax(@input); $mean = sum0(@input)/@input ) {
            ...
        }

DESCRIPTION

    Scope functions can be used to create small lexical scope, inside which
    the results of an given expression are used, but not outside.

    This module provide extra keywords / methods / symbols for creating
    scopes that help grouping related statements together, or generally
    help on making the code look more fluent.

    By use-ing this module without a import list, all keywords are
    imported. To import only wanted keywords, specify them in the import
    list:

        # Import all keywords
        use PerlX::ScopeFunction;
    
        # Import just `let`
        use PerlX::ScopeFunction qw(let);
    
        # Import just `with`, and name it differently
        use PerlX::ScopeFunction 'with' => { -as 'withThese' }

    Imported keywords can be removed by a no statement.

        no PerlX::ScopeFunction;

Importable keywords / methods / symbols.

 with

    The with keyword can be used to bring the result of an given EXPR to a
    smaller scope (code block):

        with ( EXPR ) BLOCK

    The EXPR are evaluated in list context, and the result (a list) is
    available inside BLOCK as @_. The conventional topic variable $_ is
    also assigned the last value of the list ($_[-1]).

 let

    The let keyword can be used to create readonly my- variables in a
    smaller scope (code block).

    The keyword let should be followed by a list of variable declarations,
    then a block.

        let ( DECLARATIONS ) BLOCK

    The word DECLARATIONS here means a list of variable declaration
    statements seperated by semicolons, except there must be a RHS. They
    must be given without any of my, our, state keywords.

    For example, if in the BLOCK you would do these to prepare 3 convenient
    variables:

        my $mean = mean(@input);
        my ($min, $max) = minmax(@input);

    With let statements, you do this instead:

        let (
            $mean = mean(@input);
            ($min,$max) = minmax(@input);
        ) {
            ...
        }

    Declaration are evaluated in the same order as they are given and all
    variables declarated by this are made readonly inside the BLOCK. The
    underlying library to make variables readonly is Const::Fast. Variables
    created in the beginning of this list of can be used in the latter
    positions.

    If in the current scope, there are variables with identical names as
    the ones in the DECLARATIONS, they are masked in the let-block.

    For example, in the following example code, 3 new variables are created
    in the let-block and they the ones with identical names outside of the
    let-block.

        my ($foo, $bar, $baz) = (10, 20, 30);
        let ($foo = 1; $bar = 2; $baz = $foo + $bar) {
            say "$foo $bar $baz"; #=> 1 2 3
        }
        say "$foo $bar $baz"; #=> 10 20 30

    Array and Hash can also be created:

        let (@foo = (1,2,3); %bar = (bar => 1); $baz = 42) {
            ...
        }

 $do

    $do is a method that can be used as a call on any objects. It takes a
    CodeRef, evaluates the CodeRef on the context of the object being
    called on, and returns the result.

    Syntax-wise, $do is used like this:

        EXPR -> $do(sub BLOCK)

    For example, the following code would take an object and compute a sha1
    digest:

        my $digest = $o->$do(sub {
            sha1($_->header->title . $_->body->content)
        });

    Inside the CodeRef BLOCK, both $_ and $_[0] are an alias to the object
    being called on.

 $tap, and $also

    $tap is a method that takes a CodeRef can be inserted of into a chain
    of method calls, do some side actions, then resume.

    $also is an alternative name of $tap. They are completely identical.
    Import and use which ever that is more comprehensible to you.

    Syntax-wise $tap is supposed to used like these:

        EXPR -> $tap(sub BLOCK)
        EXPR -> $tap(sub BLOCK) -> EXPR

    For example, the following code would produce a warning message before
    calling send() method on object $o:

        my $o = Example::Mail->new( body => $args{body}, to => $args{to} )
            ->$tap(sub { warn "Mail sening to: " . $_->to ) })
            ->send();

    In side the tap code block, $_ (and $_[0]) refers to the object from
    the EXPR beforehand. The return value of tap code block is thrown away,
    and the $tap itself always evaulates to the same object $_ it is called
    on. This makes it easier to do some side-effects in the middle of a
    call chain, but without having to rewrite the call chain as 2 separate
    statements. It can also be useful to work around methods with
    "inconvenient" return values, or to group a sequence of object-setup
    statements together, in a tighter scope:

    For example, here we construct an Example::Mail, fill it a recipient
    and body, but we want to check some external factors before actully
    send it:

        my $o = Example::Mail->new()
            ->$tap(sub {
                $_->set_body( $args{body} );
                $_->set_to( $args{to} );
    
                $_->ping_mail_server() or die "No internet";
                $_->check_recipient_mood() or die "Bad timing";
            })
            ->send();

    The $tap can be think as a method that can be invoked on any objects.
    But it would not work on plain scalar values, or anything you couldn't
    call methods on.

    Since it is just a scalar variable, it can also be copied to a lexical
    variable, under whatever more sensible names:

        sub run ($self) {
            my $byTheWay = $PerlX::ScopeFunction::tap;
    
            $self->$byTheWay(sub { warn "Star running" })
                ->do_run();
        }

    See also the tap method from Mojo::Base. Or the scope function also in
    Kotlin programming language: Kotlin Scope Function
    <https://kotlinlang.org/docs/scope-functions.html>

Importing as different names

    Since the keywords provided in this module are commonly defined in
    other CPAN modules, this module also provides a way to let users to
    import those keywords as different names, with a conventional spec also
    seen in Sub::Exporter.

    For example, to import with as given_these, you say:

        use PerlX::ScopeFunction "with" => { -as => "given_these" };

    Basically HashRef in import list becomes modifiers of their previous
    entries. However, This module supports only the modifier -as but not
    other ones as seen in Sub::Exporter.

CAVEATS

    Due to the fact this module hooks into perl parser, the keywords cannot
    be used without being imported into current namespace. Statements like
    the following do not compile:

         PerlX::ScopeFunction::let( ... ) {
             ...
         }
    
         PerlX::ScopeFunction::with( ... ) {
             ...
         }

AUTHOR

    Kang-min Liu <gugod@gugod.org>

LICENCE

    The MIT License

DISCLAIMER OF WARRANTY

    BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
    FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
    WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
    PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
    EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
    ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
    YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
    NECESSARY SERVICING, REPAIR, OR CORRECTION.

    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
    WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
    REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
    TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
    SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
    RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
    FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
    SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
    DAMAGES.