README

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