Class::Trigger(3pm)

1Class::Trigger(3)     User Contributed Perl Documentation    Class::Trigger(3)
2
3
4

NAME

6       Class::Trigger - Mixin to add / call inheritable triggers
7

SYNOPSIS

9         package Foo;
10         use Class::Trigger;
11
12         sub foo {
13             my $self = shift;
14             $self->call_trigger('before_foo');
15             # some code ...
16             $self->call_trigger('middle_of_foo');
17             # some code ...
18             $self->call_trigger('after_foo');
19         }
20
21         package main;
22         Foo->add_trigger(before_foo => \&sub1);
23         Foo->add_trigger(after_foo => \&sub2);
24
25         my $foo = Foo->new;
26         $foo->foo;            # then sub1, sub2 called
27
28         # triggers are inheritable
29         package Bar;
30         use base qw(Foo);
31
32         Bar->add_trigger(before_foo => \&sub);
33
34         # triggers can be object based
35         $foo->add_trigger(after_foo => \&sub3);
36         $foo->foo;            # sub3 would appply only to this object
37

DESCRIPTION

39       Class::Trigger is a mixin class to add / call triggers (or hooks) that
40       get called at some points you specify.
41

METHODS

43       By using this module, your class is capable of following methods.
44
45       add_trigger
46             Foo->add_trigger($triggerpoint => $sub);
47             $foo->add_trigger($triggerpoint => $sub);
48
49
50             Foo->add_trigger( name => $triggerpoint,
51                               callback => sub {return undef},
52                               abortable => 1);
53
54             # no further triggers will be called. Undef will be returned.
55
56           Adds triggers for trigger point. You can have any number of
57           triggers for each point. Each coderef will be passed a reference to
58           the calling object, as well as arguments passed in via
59           call_trigger. Return values will be captured in list context.
60
61           If add_trigger is called with named parameters and the "abortable"
62           parameter is passed a true value, a false return value from trigger
63           code will stop processing of this trigger point and return a
64           "false" value to the calling code.
65
66           If "add_trigger" is called without the "abortable" flag, return
67           values will be captured by call_trigger, but failures will be
68           ignored.
69
70           If "add_trigger" is called as object method, whole current trigger
71           table will be copied onto the object and the new trigger added to
72           that. (The object must be implemented as hash.)
73
74             my $foo = Foo->new;
75
76             # this trigger ($sub_foo) would apply only to $foo object
77             $foo->add_trigger($triggerpoint => $sub_foo);
78             $foo->foo;
79
80             # And not to another $bar object
81             my $bar = Foo->new;
82             $bar->foo;
83
84       call_trigger
85             $foo->call_trigger($triggerpoint, @args);
86
87           Calls triggers for trigger point, which were added via
88           "add_trigger" method. Each triggers will be passed a copy of the
89           object as the first argument.  Remaining arguments passed to
90           "call_trigger" will be passed on to each trigger.  Triggers are
91           invoked in the same order they were defined.
92
93           If there are no "abortable" triggers or no "abortable" trigger
94           point returns a false value, "call_trigger" will return the number
95           of triggers processed.
96
97           If an "abortable" trigger returns a false value, call trigger will
98           stop execution of the trigger point and return undef.
99
100       last_trigger_results
101               my @results = @{ $foo->last_trigger_results };
102
103           Returns a reference to an array of the return values of all
104           triggers called for the last trigger point. Results are ordered in
105           the same order the triggers were run.
106

TRIGGER POINTS

108       By default you can make any number of trigger points, but if you want
109       to declare names of trigger points explicitly, you can do it via
110       "import".
111
112         package Foo;
113         use Class::Trigger qw(foo bar baz);
114
115         package main;
116         Foo->add_trigger(foo  => \&sub1); # okay
117         Foo->add_trigger(hoge => \&sub2); # exception
118

FAQ

120       Acknowledgement: Thanks to everyone at POOP mailing-list
121       (http://poop.sourceforge.net/).
122
123       Q.  This module lets me add subs to be run before/after a specific
124           subroutine is run.  Yes?
125
126       A.  You put various call_trigger() method in your class.  Then your
127           class users can call add_trigger() method to add subs to be run in
128           points just you specify (exactly where you put call_trigger()).
129
130       Q.  Are you aware of the perl-aspects project and the Aspect module?
131           Very similar to Class::Trigger by the look of it, but its not
132           nearly as explicit.  Its not necessary for foo() to actually say
133           "triggers go *here*", you just add them.
134
135       A.  Yep ;)
136
137           But the difference with Aspect would be that Class::Trigger is so
138           simple that it's easy to learn, and doesn't require 5.6 or over.
139
140       Q.  How does this compare to Sub::Versive, or Hook::LexWrap?
141
142       A.  Very similar. But the difference with Class::Trigger would be the
143           explicitness of trigger points.
144
145           In addition, you can put hooks in any point, rather than pre or
146           post of a method.
147
148       Q.  It looks interesting, but I just can't think of a practical example
149           of its use...
150
151       A.  (by Tony Bowden)
152
153           I originally added code like this to Class::DBI to cope with one
154           particular case: auto-upkeep of full-text search indices.
155
156           So I added functionality in Class::DBI to be able to trigger an
157           arbitary subroutine every time something happened - then it was a
158           simple matter of setting up triggers on INSERT and UPDATE to
159           reindex that row, and on DELETE to remove that index row.
160
161           See Class::DBI::mysql::FullTextSearch and its source code to see it
162           in action.
163

AUTHORS

165       Original idea by Tony Bowden <tony@kasei.com> in Class::DBI.
166
167       Code by Tatsuhiko Miyagawa <miyagawa@bulknews.net>.
168
169       Jesse Vincent added a code to get return values from triggers and
170       abortable flag.
171
172       This library is free software; you can redistribute it and/or modify it
173       under the same terms as Perl itself.
174