NAME

Pad::Tie - tie an object to lexical contexts

VERSION

 Version 0.006

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.

METHODS

Most of the time you will only need to use new and call, or perhaps wrap. The names for call and wrap are chosen deliberately to match up with methods from Lexical::Persistence, which this module is build using.

new

  my $pad_tie = Pad::Tie->new($obj, \@methods);

Create a new binding for the given object.

See DESCRIPTION and CONFIGURATION.

TODO

• subclassing

  Work out and test interactions.

• method auto-discovery

  Provide method personality plugins for various object frameworks to avoid having to type a bunch.

• more method personalities

  e.g. Rose::Object::MakeMethods::Generic's different kinds of hash/array accessors, a scalar that calls different methods for FETCH and STORE ($url in examples/mech.pl).

• more options

  interface for configuring the underlying Lexical::Persistence object

• more documentation

  examples that aren't filled with 'foo', documentation on plugins

SEE ALSO

Pad::Tie::Plugin Lexical::Persistence Devel::LexAlias PadWalker Data::OptList

AUTHOR

Hans Dieter Pearcey, <hdp at cpan.org>

BUGS

Please report any bugs or feature requests to bug-pad-tie at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pad-Tie. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Pad::Tie

You can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Pad-Tie

• CPAN Ratings

  http://cpanratings.perl.org/d/Pad-Tie

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Pad-Tie

• Search CPAN

  http://search.cpan.org/dist/Pad-Tie

ACKNOWLEDGEMENTS

Thanks to Pobox.com, who sponsored the development of this module.

COPYRIGHT & LICENSE

Copyright 2007 Hans Dieter Pearcey, all rights reserved.

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

cpanm Pad::Tie

perl -MCPAN -e shell
install Pad::Tie