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.

cpanm methods::import

perl -MCPAN -e shell
install methods::import