README

   1 NAME
   2     with - Lexically call methods with a default object.
   3
   4 VERSION
   5     Version 0.02
   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 scoping and source
  51     modification 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 has a prototype or is part of the core, the call is deferred to
  59     a corresponding wrapper generated in the "with" namespace. Some keywords
  60     that couldn't possibly be replaced are also completely skipped. "no
  61     with" undefines the hint and deletes the source filter, stopping any
  62     subsequent 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" error is thrown.
  71
  72 IGNORED KEYWORDS
  73     A call will never be dispatched to a method whose name is one 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 cmp
  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     When there's a function in the caller namespace that has a core function
  94     name, and when no method with the same name is present, the ambiguity is
  95     resolved in favor of the caller namespace. That's different from the
  96     usual perl semantics where "sub push; push @a, 1" gets resolved to
  97     CORE::push.
  98
  99     If a method has the same name as a prototyped function in the caller
 100     namespace, and if a called is deferred to the method, it will have its
 101     arguments passed by value.
 102
 103 DEPENDENCIES
 104     perl 5.9.4.
 105
 106     Carp (core module since perl 5).
 107
 108     Filter::Util::Call, Scalar::Util and Text::Balanced (core since 5.7.3).
 109
 110     Sub::Prototype::Util 0.08.
 111
 112 AUTHOR
 113     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 114
 115     You can contact me by mail or on #perl @ FreeNode (vincent or
 116     Prof_Vince).
 117
 118 BUGS
 119     Please report any bugs or feature requests to "bug-with at rt.cpan.org",
 120     or through the web interface at
 121     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=with>. I will be
 122     notified, and then you'll automatically be notified of progress on your
 123     bug as I make changes.
 124
 125 SUPPORT
 126     You can find documentation for this module with the perldoc command.
 127
 128         perldoc with
 129
 130 ACKNOWLEDGEMENTS
 131     A fair part of this module is widely inspired from Filter::Simple
 132     (especially "FILTER_ONLY"), but a complete integration was needed in
 133     order to add hints support and more placeholder patterns.
 134
 135 COPYRIGHT & LICENSE
 136     Copyright 2008 Vincent Pit, all rights reserved.
 137
 138     This program is free software; you can redistribute it and/or modify it
 139     under the same terms as Perl itself.
 140