2 with - Lexically call methods with a default object.
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
16 sub new { my $class = shift; bless { id = > shift }, $class }
18 sub hlagh { my $self = shift; print "Deuce::hlagh $self->{id}\n" }
23 sub hlagh { print "Pants::hlagh\n" }
27 my $deuce = new Deuce 1;
33 hlagh; # Deuce::hlagh 1
34 Pants::hlagh; # Pants::hlagh
37 use with \Deuce->new(2);
38 hlagh; # Deuce::hlagh 2
41 hlagh; # Deuce::hlagh 1
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.
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.
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.
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.
80 A call will never be dispatched to a method whose name is one of :
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
86 map grep system exec sort print say
91 No function or constant is exported by this pragma.
94 Most likely slow. Almost surely non thread-safe. Contains source
95 filters, hence brittle. Messes with the dreadful prototypes. Crazy. Will
98 Don't put anything on the same line of "use with \$obj" or "no with".
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
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.
113 Carp (core module since perl 5).
115 Filter::Util::Call, Scalar::Util and Text::Balanced (core since 5.7.3).
117 Sub::Prototype::Util 0.08.
120 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
122 You can contact me by mail or on "irc.perl.org" (vincent).
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.
132 You can find documentation for this module with the perldoc command.
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.
142 Copyright 2008,2017 Vincent Pit, all rights reserved.
144 This program is free software; you can redistribute it and/or modify it
145 under the same terms as Perl itself.