NAME
    methods::import - import methods to be used like keywords

SYNOPSIS
    The following calls `get` on the $ua object.

     use HTTP::Tiny;
 
     my $ua = HTTP::Tiny->new;
     for ($ua) {
       use methods::import qw(get post);
   
       my $response = get 'http://www.example.com/';
     }

    Alternative:

     use HTTP::Tiny;
     use methods::import qw(get post);
 
     my $ua = HTTP::Tiny->new;
 
     using $ua, sub {
       my $response = get 'http://www.example.com/';
     };

DESCRIPTION
    methods::import simplifies the task of calling a lot of methods on a
    single object.

    Instead of:

      $thing->set_foo(1);
      $thing->process();
      $thing->set_foo(2);
      $thing->set_bar(3);
      $thing->process;

    You can write:

     for ($thing) {
       use methods::import qw( set_foo set_bar process );
   
       set_foo 1;
       process;
       set_foo 2;
       set_bar 3;
       process;
     }
 
     # You cannot call process() here because it was lexical

    As well as `set_foo` and the other functions explicitly named in the
    import list, methods::import will always export a function called `using`.

    `using` can be used as an alternative to setting $_ to point to an object.

     use methods::import qw( set_foo set_bar process );
 
     using $thing, sub {
       set_foo 1;
       process;
       set_foo 2;
       set_bar 3;
       process;
     };

  Renaming Imports
    An equals sign allows you to rename the imported wrappers.

     use methods::import qw( set_foo=foo set_bar=bar process );
 
     using $thing, sub {
       foo 1;
       process;
       foo 2;
       bar 3;
       process;
     };

    Even the `using` function can be renamed:

     use methods::import qw( set_foo=foo set_bar=bar process using=processing );
 
     processing $thing, sub {
       foo 1;
       process;
       foo 2;
       bar 3;
       process;
     };

  How `using` Works
    When you import the wrappers, an scalar variable is created in the lexical
    scope of all the wrappers being imported. The wrappers will attempt to
    call the method on this scalar variable if it is defined, and fall back to
    $_ otherwise.

    `using` accepts an object and a coderef. It sets the scalar variable to
    point to the object, calls the coderef, then restores the scalar variable
    to whatever it was before (usally undef). It then returns the return value
    from calling the coderef.

    This means:

     use methods::import qw( foo using=using1 );
     use methods::import qw( bar using=using2 );
 
     using1 $something, sub {
       bar();
     };

    `bar()` is being called on an undefined object, because `using1` only sets
    the target object for `foo`, not `bar`.

    As a utility, if `using` is called with no parameters, it will simply
    return the current target object. Or if `using` is called with one
    parameter, it will set the target object and return any previous target
    object.

     use methods::import qw( set_foo set_bar process );
 
     using $thing;
     set_foo 1;
     process;
     set_foo 2;
     set_bar 3;
     process;
 
     using->some_other_method();

  Nested Imports
     use methods::import qw(get);
     using LWP::UserAgent->new, sub {
       use methods::import qw(headers using=using_response);
       using_response get('http://example.com'), sub {
         my $headers = headers();
       };
     };

  Currying
    It is possible to curry leading arguments to a method:

     use methods::import
       "foo",
       "foo" => { -as => "foo_123", -curry => [1,2,3] };
 
     using $thing;
     foo(1, 2, 3, 4);     # $thing->foo(1, 2, 3, 4)
     foo_123(4);          # same

    Note that the `-as` option has the same effect as `=` in the import list.
    `=` is just a shortcut.

  Prototypes
     use methods::import "foo" => { -prototype => '&' };
 
     using $thing;
     foo { ... };      # $thing->foo(sub { ... });

    There is a shortcut for this too:

     use methods::import qw( foo=foo=& );
     use methods::import qw( foo==& );     # leaves `-as` blank

  Call Stack
    methods::import doesn't make any attempt to hide the wrapper functions it
    exports. They will show up on the call stack.

  Lexical Exports
    methods::import uses namespace::clean to fake lexical imports.

     {
       use methods::import qw(foo);
       using $object;
       foo();
     }
     # Neither using() nor foo() are defined here.

    You can switch off this behaviour by passing `-keep` as the first option
    to `import`:

     {
       use methods::import qw(-keep foo);
       using $object;
       foo();
     }
     # using() and foo() are still defined here.

    Or it can be done on a function by function basis:

     use methods::import (
       "foo"    => { -keep => 1 },
       "bar"    => { -keep => 0 },
       "using"  => { -keep => 1 },
     );

  Inheriting from `methods::import`
    If your class inherits from methods::import it can provide a `method_list`
    function that supplies a default list of methods for `import`.

    For example:

     package HTTP::Tiny::Keywords;
     use HTTP::Tiny;
     use parent 'methods::import';
     sub method_list { qw( get post using=set_ua) }
     1;

    And a module using your HTTP::Tiny::Keywords might do this:

     use HTTP::Tiny::Keywords;
 
     set_ua HTTP::Tiny->new;
     my $response = get 'http://www.example.com/';

BUGS
    Please report any bugs to
    <http://rt.cpan.org/Dist/Display.html?Queue=methods-import>.

SEE ALSO
    `with`.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE
    This software is copyright (c) 2019 by Toby Inkster.

    This is free software; you can redistribute it and/or modify it under the
    same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.