1SVK::Log::Filter(3) User Contributed Perl Documentation SVK::Log::Filter(3)
2
6 SVK::Log::Filter - base class for all log filters
7
9 SVK::Log::Filter is a class for displaying or otherwise processing
10 revision properties. The SVK "log" command uses filter classes to han‐
11 dle the details of processing the revision properties. The bulk of
12 this document explains how to write those filter classes.
13 A log filter is just a Perl class with special methods. At specific
15 points while processing log information, SVK calls these methods on the
16 filter object. SVK::Log::Filter provides sensible defaults for each of
17 the methods it calls. The methods (in order of invocation) are "set‐
18 up", "header", "revision", "footer", "teardown". Each is fully docu‐
19 mented in the section "METHOD REFERENCE".
20
22 Although log filters which output and log filters which select are
23 exactly the same kind of objects, they are generally conceptualized
24 separately. The following tutorial provides a simple example for each
25 type of filter.
26 OUTPUT
28 For our simple output filter example, we want to display something like
30 the following
31 1. r3200 by john
33 2. r3194 by tom
34 3. r3193 by larry
35 Namely, the number the revisions we've seen, then show the actual revi‐
37 sion number from the repository and indicate the author of that revi‐
38 sion. We want this log filter to be accessible by a command like "svk
39 log --output list" The code to accomplish that is
40 1 package SVK::Log::Filter::List;
42 2 use base qw( SVK::Log::Filter );
43 3 sub setup {
45 4 my ($self) = @_;
46 5 $self->{count} = 1;
47 6 }
48 7 sub revision {
50 8 my ($self, $args) = @_;
51 9 printf "%d. r%d by %s\n",
53 10 $self->{count}++,
54 11 $args->{rev},
55 12 $args->{props}{'svn:author'}
56 13 ;
57 14 }
58 First, we must establish the name of this filter. SVK looks for fil‐
60 ters with the namespace prefix "SVK::Log::Filter". The final portion
61 of the name can either have the first letter capitalized or all the
62 letters capitalized. On line 2, we use SVK::Log::Filter as the base
63 class so that we can get the default method implementations.
64 On lines 3-6, we get to the first meat. Since we want to count the
66 revisions that we see, we have to store the information somewhere that
67 will persist between method calls. We just store it in the log filter
68 object itself. Finally, on line 6, our "setup" method is finished.
69 The return value of the method is irrelevant.
70 The "revision" method on lines 7-14 does the real work of the filter.
72 First (line 8) we extract arguments into a hashref $args. Then it sim‐
73 ply prints what we want it to display. SVK takes care of directing
74 output to the appropriate place. You'll notice that the revision prop‐
75 erties are provided as a hash. The key of the hash is the name of the
76 property and the value of the hash is the value of the property.
77 That's it. Put SVK::Log::Filter::List somewhere in @INC and SVK will
79 find it.
80 SELECTION
82 Our simple selection filter example will pass revisions based on
84 whether the revision number is even or odd. The filter accepts a sin‐
85 gle argument 'odd' or 'even' indicating which revisions should be
86 passed down the pipeline. Additionally, if the filter ever encounters
87 the revision number "42" it will stop the entire pipeline and process
88 no more revisions. The invocation is something like "svk log --filter
89 'parity even'" to display all even revisions up to r42.
90 1 package SVK::Log::Filter::Parity;
92 2 use base qw( SVK::Log::Filter );
93 3 sub setup {
95 4 my ($self) = @_;
96 5 my $argument = lc $self->{argument};
98 6 $self->{bit} = $argument eq 'even' ? 0
99 7 : $argument eq 'odd' ? 1
100 8 : die "Parity argument not 'even' or 'odd'\n"
101 9 ;
102 10 }
103 11 sub revision {
105 12 my ($self, $args) = @_;
106 13 my $rev = $args->{rev};
108 14 $self->pipeline('last') if $rev == 42;
109 15 $self->pipeline('next') if $rev % 2 != $self->{bit};
110 16 }
111 There are only a few differences between this implementation and the
113 output filter implementation. The first difference is in line 5. When
114 a log filter object is created, the default "new" method creates the
115 'argument' key which contains the command-line argument provided to
116 your filter. In this case, the argument should be either 'even' or
117 'odd'. Based on the argument, we update the object to remind us what
118 parity we're looking for.
119 The unique characteristics of "revision" are the calls to the "pipe‐
121 line" method in lines 14 and 15. If we want to stop the pipeline
122 entirely, call "pipeline" with the argument 'last' (think "this is the
123 last revision"). The current revision and all subsequent revisions
124 will not be processed by the filter pipelin. If the argument to "pipe‐
125 line" is 'next' (think "go to the next revision"), the current revision
126 will not be displayed and the pipeline will proceed with the next revi‐
127 sion in sequence. If you don't call "pipeline", the current revision
128 is passed down the remainder of the pipeline so that it can be pro‐
129 cessed and displayed.
130
132 This is a list of all the methods that SVK::Log::Filter implements and
133 a description of how they should be called. When defining a subclass,
134 one need only override those methods that are necessary for implement‐
135 ing the filter. All methods have sensible defaults (namely, do noth‐
136 ing). The methods are listed here in the order in which they are
137 called by the pipeline.
138 All methods except "new" and "pipeline" receive a single hash reference
140 as their first argument (after the invocant, of course). The
141 'Receives' section in the documentation below indicates which named
142 arguments are present in that hash.
143 new
145 Builds a new object from a hash reference. The value of any arguments
147 provided to the log filter on the command line are placed in the 'argu‐
148 ment' attribute of the object. Generally, there is no need to override
149 the "new" method because the "setup" method can be overriden instead.
150 setup
152 Receives: "stash"
154 This method is called once just before the filter is used for the first
156 time. It's conceptually similar to "new", but allows the filter devel‐
157 oper to ignore the creation of the filter object. This is the place to
158 do filter initialization, process command-line arguments, read configu‐
159 ration files, connect to a database, etc.
160 header
162 Receives: "stash"
164 This method is called once just before the first revision is processed
166 but after "setup" has completed. This is an ideal place to display
167 information which should appear at the top of the log display.
168 revision
170 Receives: "paths", "rev", "props", "stash", "get_remoterev"
172 This method is called for each revision that SVK wants to process. The
174 bulk of a log filter's code implements this method. Output filters may
175 simply print the information that they want displayed. Other filters
176 should either modify the revision properties (see "props") or use pipe‐
177 line commands (see "pipeline") to skip irrelevant revisions.
178 footer
180 Receives: "stash"
182 This method is similar to the "header" method, but it's called once
184 after all the revisions have been displayed. This is the place to do
185 any final output.
186 teardown
188 Receives: "stash"
190 This method is called once just before the log filter is discarded.
192 This is the place to disconnect from databases, close file handles,
193 etc.
194 pipeline
196 This method is not called by the filter pipeline. Rather, it's used by
198 log filters to control the pipeline's behavior. It accepts a single
199 scalar as the argument. If the argument is 'next', the pipeline stops
200 processing the current revision (including any output filter) and
201 starts processing the next revision starting over at the beginning of
202 the pipeline. If the argument to "pipeline" is 'last', the pipeline is
203 stopped entirely (including any output filters). Once the pipeline has
204 stopped, the SVK log command finishes any final details and stops.
205
207 This section describes the possible keys and values of the hashref
208 that's provided to method calls.
209
211 If the value of this argument is true, the value is a coderef. When
212 the coderef is invoked with a single revision number as the argument,
213 it returns the number of the equivalent revision in the upstream repos‐
214 itory. The value of this key may be undefined if the logs are being
215 processed for something other than a mirror. The following code may be
216 useful when working with "get_remoterev"
217 my ( $stash, $rev, $get_remoterev)
219 = @{$args}{qw( stash rev get_remoterev )};
220 my $remote_rev = $get_remoterev ? $get_remoterev->($rev) : 'unknown';
221 print "The remote revision for r$rev is $remote_rev.\n";
222 paths
224 The value of the 'paths' argument is an SVK::Log::ChangedPaths object.
226 The object provides methods for indicating which paths were changed by
227 this revision and approximately how they were changed (modified file
228 contents, modified file properties, etc.)
229 See the documentation for SVK::Log::ChangedPaths for more details.
231 rev
233 The value of the 'rev' argument is the Subversion revision number for
235 the current revision.
236 props
238 The value of the 'props' argument is a hash reference containing all
240 the revision properties for the current revision. The keys of the hash
241 are the property names and the values of the hash are the property val‐
242 ues. For example, the author of a revision is available with
243 "$args->{'svn:author'}".
244 If you change values in the 'props' hashref, those changes are visible
246 to all subsequent filters in the pipeline. This can be useful and dan‐
247 gerous. Dangerous if you accidentally modify a property, useful if you
248 intentionally modify a property. For instance, it's possible to make a
249 "selection" filter which uses Babelfish to translate log messages from
250 one language to another (see SVK::Log::Filter::Babelfish on CPAN). By
251 modifying the 'svn:log' property, other log filters can operate on the
252 translated log message without knowing that it's translated.
253 stash
255 The value of the 'stash' argument is a reference to a hash. The stash
257 persists throughout the entire log filtering process and is provided to
258 every method that the filter pipeline calls. The stash may be used to
259 pass information from one filter to another filter in the pipeline.
260 When creating new keys in the stash, it's important to avoid uninten‐
262 tional name collisions with other filters in the pipeline. A good
263 practice is to preface the name of each stash key with the name of your
264 filter ("myfilter_key") or to create your own hash reference inside the
265 stash ("$stash->{myfilter}{key}"). If your filter puts information
266 into the stash that other filters may want to access, please document
267 the location and format of that information for other filter authors.
268
271 If the user included the "--quiet" flag when invoking "svk log" the
272 value of this key will be a true value. Otherwise, the value will be
273 false.
274
276 If the user included the "--verbose" flag when invoking "svk log" the
277 value of this key will be a true value. Otherwise, the value will be
278 false.
279perl v5.8.8 2006-12-28 SVK::Log::Filter(3)