NAME

Pad::Tie - tie an object to lexical contexts

VERSION

Version 0.002

SYNOPSIS

use Pad::Tie;

my $obj = MyClass->new(...);
my $pad_tie = Pad::Tie->new(
  $obj,
  [
    scalar    => [qw(fooble quux)],
    array_ref => [qw(numbers)],
    hash_ref  => [qw(lookup)],
    'self',
  ]
);

$pad_tie->call(\&foo);
my $code = $pad_tie->wrap(\&bar);
$code->(1, 2, 3);

sub foo {
  my $fooble;

  print $fooble; # $obj->fooble
}

sub bar {
  my $quux = 17; # $obj->quux(17);
  my %lookup;

  for my $key (keys %lookup) {
    # keys %{ $obj->lookup }

    $lookup{$key} ||= 1;       
    # $obj->lookup->{$key} ||= 1
  }

  my @numbers = @_; 
  # $obj->numbers([ 1, 2, 3 ]); @_ is from above
}

DESCRIPTION

Pad::Tie lets you use your objects' methods as though they were lexical variables.

Alternately, it lets you use lexical variables to refer to your bound object methods. It's all a matter of perspective.

Creating a Pad::Tie object requires an object (the invocant) and a list of methods (with their personalities) that will be exposed to called subroutines.

There are a number of different calling conventions for methods in Perl. In order to accommodate as many as possible, Pad::Tie lets plugins handle them. See Pad::Tie::Plugin for details on writing new method personalities.

scalar

The simplest personality. Using the variable calls the method with no arguments. Assignments to the variable call the method with a single argument, the new value.

... Pad::Tie->new($obj, [ scalar => [ 'foo' ] ]);

sub double_nonzero_foo {
  my $foo;
  if ($foo) {        # $obj->foo
    $foo = $foo * 2; # $obj->foo($obj->foo * 2)
  }
}

array_ref

hash_ref

Nearly as simple as scalar. Using the variable bound to doesn't actually generate a method call; instead, it's retrieved once and the reference is used repeatedly.

... Pad::Tie->new($obj, [ array_ref => [ 'foo' ] ]);

sub add_to_foo {
  my @foo;
  push @foo, @_; # push @{ $obj->foo }, @_
}

list

Reading from a array bound to a 'list' method personality calls the method with no arguments in list context. Assigning to the array calls the method once with all of the assigned values. Reading individual array elements is ok, but setting individual array elements will croak.

... Pad::Tie->new($obj, [ list => [ 'foo' ] ]);

sub get_or_set_foo {
  my @foo;
  @foo = @_ if @_; # $obj->foo(@_)
  return @foo;     # $obj->foo
}

Because of the way this personality works, if you call the method directly or otherwise change its return values, those changes may not be reflected in bound array values.

In other words, continuing the example above, this is a bad idea:

sub dont_do_this {
  my @foo;
  @foo = (1, 2, 3);
  $obj->foo(4, 5, 6);
  print "@foo"; # probably prints '1 2 3'
}

self

This method personality takes no arguments and makes the invocant available as $self in any called subroutine. Note that it will not add $self to the sub if it's not there; you still need a my $self declaration in the scope of the sub.

... Pad::Tie->new($obj, [ 'self' ]);

sub who_am_i {
  my $self;
  return $self->name;
}

CONFIGURATION

Each Pad::Tie object is configured with a list of methods and personalities:

Pad::Tie->new($obj, [ $personality => \@methodnames, ... ])

The list of method names is actually just an argument to the plugin. See individual plugins and Pad::Tie::Plugin for details.

Note that this is an 'optlist'; see Data::OptList. The short version is that if you don't need arguments, such as for the self plugin, you don't need to pass an explicit undef value. See "SYNOPSIS".

More detail about methods and personalities is given above. See DESCRIPTION.

cpanm Pad::Tie

perl -MCPAN -e shell
install Pad::Tie