README

   1 NAME
   2     with - Lexically call methods with a default object.
   3
   4 VERSION
   5     Version 0.01
   6
   7 SYNOPSIS
   8         package Deuce;
   9
  10         sub new { my $class = shift; bless { id = > shift }, $class }
  11
  12         sub hlagh { my $self = shift; print "Deuce::hlagh $self->{id}\n" }
  13
  14         package Pants;
  15
  16         sub hlagh { print "Pants::hlagh\n" }
  17
  18         our @ISA;
  19         push @ISA, 'Deuce';
  20         my $deuce = new Deuce 1;
  21
  22         hlagh;         # Pants::hlagh
  23
  24         {
  25          use with \$deuce;
  26          hlagh;        # Deuce::hlagh 1
  27          Pants::hlagh; # Pants::hlagh
  28
  29          {
  30           use with \Deuce->new(2);
  31           hlagh;       # Deuce::hlagh 2
  32          }
  33
  34          hlagh;        # Deuce::hlagh 1
  35
  36          no with;
  37          hlagh;        # Pants::hlagh
  38         }
  39
  40         hlagh;         # Pants::hlagh
  41
  42 DESCRIPTION
  43     This pragma lets you define a default object against with methods will
  44     be called in the current scope when possible. It is enabled by the "use
  45     with \$obj" idiom (note that you must pass a reference to the object).
  46     If you "use with" several times in the current scope, the default object
  47     will be the last specified one.
  48
  49 HOW DOES IT WORK
  50     The main problem to address is that lexical scope and source
  51     modifications can only occur at compile time, while object creation and
  52     method resolution happen at run-time.
  53
  54     The "use with \$obj" statement stores an address to the variable $obj in
  55     the "with" field of the hints hash "%^H". It also starts a source filter
  56     that replaces function calls with calls to "with::defer", passing the
  57     name of the original function as the first argument. When the replaced
  58     function is part of Perl core, the call is deferred to a corresponding
  59     wrapper generated in the "with" namespace. Some keywords that couldn't
  60     possibly be replaced are also completely skipped. "no with" undefines
  61     the hint and deletes the source filter, stopping any subsequent
  62     modification in the current scope.
  63
  64     When the script is executed, deferred calls first fetch the default
  65     object back from the address stored into the hint. If the object "->can"
  66     the original function name, a method call is issued. If not, the calling
  67     namespace is inspected for a subroutine with the proper name, and if
  68     it's present the program "goto"s into it. If that fails too, the core
  69     function with the same name is recalled if possible, or an "Undefined
  70     subroutine" warning is thrown.
  71
  72 IGNORED KEYWORDS
  73     A call will never dispatch to methods whose name is part of :
  74
  75         my our local sub do eval goto return
  76         if else elsif unless given when or and
  77         while until for foreach next redo last continue
  78         eq ne lt gt le ge
  79         map grep system exec sort print say
  80         new
  81         STDIN STDOUT STDERR
  82
  83 EXPORT
  84     No function or constant is exported by this pragma.
  85
  86 CAVEATS
  87     Most likely slow. Almost surely non thread-safe. Contains source
  88     filters, hence brittle. Messes with the dreadful prototypes. Crazy. Will
  89     have bugs.
  90
  91     Don't put anything on the same line of "use with \$obj" or "no with".
  92
  93 DEPENDENCIES
  94     perl 5.9.4.
  95
  96     Carp (core module since perl 5).
  97
  98     Filter::Util::Call, Scalar::Util and Text::Balanced (core since 5.7.3).
  99
 100     Sub::Prototype::Util 0.08.
 101
 102 AUTHOR
 103     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 104
 105     You can contact me by mail or on #perl @ FreeNode (vincent or
 106     Prof_Vince).
 107
 108 BUGS
 109     Please report any bugs or feature requests to "bug-with at rt.cpan.org",
 110     or through the web interface at
 111     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=with>. I will be
 112     notified, and then you'll automatically be notified of progress on your
 113     bug as I make changes.
 114
 115 SUPPORT
 116     You can find documentation for this module with the perldoc command.
 117
 118         perldoc with
 119
 120 ACKNOWLEDGEMENTS
 121     A fair part of this module is widely inspired from Filter::Simple
 122     (especially "FILTER_ONLY"), but a complete integration was needed in
 123     order to add hints support and more placeholder patterns.
 124
 125 COPYRIGHT & LICENSE
 126     Copyright 2008 Vincent Pit, all rights reserved.
 127
 128     This program is free software; you can redistribute it and/or modify it
 129     under the same terms as Perl itself.
 130