1SVK::Log::Filter(3)   User Contributed Perl Documentation  SVK::Log::Filter(3)
2
3
4

NAME

6       SVK::Log::Filter - base class for all log filters
7

DESCRIPTION

9       SVK::Log::Filter is a class for displaying or otherwise processing
10       revision properties.  The SVK "log" command uses filter classes to
11       handle the details of processing the revision properties.  The bulk of
12       this document explains how to write those filter classes.
13
14       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
18       "setup", "header", "revision", "footer", "teardown". Each is fully
19       documented in the section "METHOD REFERENCE".
20

TUTORIAL

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
27   OUTPUT
28       For our simple output filter example, we want to display something like
29       the following
30
31           1. r3200 by john
32           2. r3194 by tom
33           3. r3193 by larry
34
35       Namely, the number the revisions we've seen, then show the actual
36       revision number from the repository and indicate the author of that
37       revision.   We want this log filter to be accessible by a command like
38       "svk log --output list" The code to accomplish that is
39
40          1   package SVK::Log::Filter::List;
41          2   use base qw( SVK::Log::Filter );
42
43          3   sub setup {
44          4       my ($self) = @_;
45          5       $self->{count} = 1;
46          6   }
47
48          7   sub revision {
49          8       my ($self, $args) = @_;
50
51          9       printf "%d. r%d by %s\n",
52         10           $self->{count}++,
53         11           $args->{rev},
54         12           $args->{props}{'svn:author'}
55         13       ;
56         14   }
57
58       First, we must establish the name of this filter.  SVK looks for
59       filters with the namespace prefix "SVK::Log::Filter".  The final
60       portion of the name can either have the first letter capitalized or all
61       the letters capitalized.  On line 2, we use SVK::Log::Filter as the
62       base class so that we can get the default method implementations.
63
64       On lines 3-6, we get to the first meat.  Since we want to count the
65       revisions that we see, we have to store the information somewhere that
66       will persist between method calls.  We just store it in the log filter
67       object itself.  Finally, on line 6, our "setup" method is finished.
68       The return value of the method is irrelevant.
69
70       The "revision" method on lines 7-14 does the real work of the filter.
71       First (line 8) we extract arguments into a hashref $args.  Then it
72       simply prints what we want it to display.  SVK takes care of directing
73       output to the appropriate place.  You'll notice that the revision
74       properties are provided as a hash.  The key of the hash is the name of
75       the property and the value of the hash is the value of the property.
76
77       That's it.  Put SVK::Log::Filter::List somewhere in @INC and SVK will
78       find it.
79
80   SELECTION
81       Our simple selection filter example will pass revisions based on
82       whether the revision number is even or odd.  The filter accepts a
83       single argument 'odd' or 'even' indicating which revisions should be
84       passed down the pipeline.  Additionally, if the filter ever encounters
85       the revision number "42" it will stop the entire pipeline and process
86       no more revisions.  The invocation is something like "svk log --filter
87       'parity even'" to display all even revisions up to r42.
88
89          1   package SVK::Log::Filter::Parity;
90          2   use base qw( SVK::Log::Filter );
91
92          3   sub setup {
93          4       my ($self) = @_;
94
95          5       my $argument = lc $self->{argument};
96          6       $self->{bit} = $argument eq 'even' ? 0
97          7                    : $argument eq 'odd'  ? 1
98          8                    : die "Parity argument not 'even' or 'odd'\n"
99          9                    ;
100         10   }
101
102         11   sub revision {
103         12       my ($self, $args) = @_;
104
105         13       my $rev = $args->{rev};
106         14       $self->pipeline('last') if $rev == 42;
107         15       $self->pipeline('next') if $rev % 2 != $self->{bit};
108         16   }
109
110       There are only a few differences between this implementation and the
111       output filter implementation.  The first difference is in line 5.  When
112       a log filter object is created, the default "new" method creates the
113       'argument' key which contains the command-line argument provided to
114       your filter.  In this case, the argument should be either 'even' or
115       'odd'.  Based on the argument, we update the object to remind us what
116       parity we're looking for.
117
118       The unique characteristics of "revision" are the calls to the
119       "pipeline" method in lines 14 and 15.  If we want to stop the pipeline
120       entirely, call "pipeline" with the argument 'last' (think "this is the
121       last revision").  The current revision and all subsequent revisions
122       will not be processed by the filter pipelin.  If the argument to
123       "pipeline" is 'next' (think "go to the next revision"), the current
124       revision will not be displayed and the pipeline will proceed with the
125       next revision in sequence.  If you don't call "pipeline", the current
126       revision is passed down the remainder of the pipeline so that it can be
127       processed and displayed.
128

METHODS

130       This is a list of all the methods that SVK::Log::Filter implements and
131       a description of how they should be called.  When defining a subclass,
132       one need only override those methods that are necessary for
133       implementing the filter.  All methods have sensible defaults (namely,
134       do nothing).  The methods are listed here in the order in which they
135       are called by the pipeline.
136
137       All methods except "new" and "pipeline" receive a single hash reference
138       as their first argument (after the invocant, of course).  The
139       'Receives' section in the documentation below indicates which named
140       arguments are present in that hash.
141
142   new
143       Builds a new object from a hash reference.  The value of any arguments
144       provided to the log filter on the command line are placed in the
145       'argument' attribute of the object.  Generally, there is no need to
146       override the "new" method because the "setup" method can be overriden
147       instead.
148
149   setup
150       Receives: "stash"
151
152       This method is called once just before the filter is used for the first
153       time.  It's conceptually similar to "new", but allows the filter
154       developer to ignore the creation of the filter object.  This is the
155       place to do filter initialization, process command-line arguments, read
156       configuration files, connect to a database, etc.
157
158   header
159       Receives: "stash"
160
161       This method is called once just before the first revision is processed
162       but after "setup" has completed.  This is an ideal place to display
163       information which should appear at the top of the log display.
164
165   revision
166       Receives: "paths", "rev", "props", "stash", "get_remoterev"
167
168       This method is called for each revision that SVK wants to process.  The
169       bulk of a log filter's code implements this method.  Output filters may
170       simply print the information that they want displayed.  Other filters
171       should either modify the revision properties (see "props") or use
172       pipeline commands (see "pipeline") to skip irrelevant revisions.
173
174   footer
175       Receives: "stash"
176
177       This method is similar to the "header" method, but it's called once
178       after all the revisions have been displayed.  This is the place to do
179       any final output.
180
181   teardown
182       Receives: "stash"
183
184       This method is called once just before the log filter is discarded.
185       This is the place to disconnect from databases, close file handles,
186       etc.
187
188   pipeline
189       This method is not called by the filter pipeline.  Rather, it's used by
190       log filters to control the pipeline's behavior.  It accepts a single
191       scalar as the argument.  If the argument is 'next', the pipeline stops
192       processing the current revision (including any output filter) and
193       starts processing the next revision starting over at the beginning of
194       the pipeline.  If the argument to "pipeline" is 'last', the pipeline is
195       stopped entirely (including any output filters).  Once the pipeline has
196       stopped, the SVK log command finishes any final details and stops.
197

ARGUMENTS

199       This section describes the possible keys and values of the hashref
200       that's provided to method calls.
201

get_remoterev

203       If the value of this argument is true, the value is a coderef.  When
204       the coderef is invoked with a single revision number as the argument,
205       it returns the number of the equivalent revision in the upstream
206       repository.  The value of this key may be undefined if the logs are
207       being processed for something other than a mirror.  The following code
208       may be useful when working with "get_remoterev"
209
210           my           ( $stash, $rev, $get_remoterev)
211           = @{$args}{qw(  stash   rev   get_remoterev )};
212           my $remote_rev = $get_remoterev ? $get_remoterev->($rev) : 'unknown';
213           print "The remote revision for r$rev is $remote_rev.\n";
214
215   paths
216       The value of the 'paths' argument is an SVK::Log::ChangedPaths object.
217       The object provides methods for indicating which paths were changed by
218       this revision and approximately how they were changed (modified file
219       contents, modified file properties, etc.)
220
221       See the documentation for SVK::Log::ChangedPaths for more details.
222
223   rev
224       The value of the 'rev' argument is the Subversion revision number for
225       the current revision.
226
227   props
228       The value of the 'props' argument is a hash reference containing all
229       the revision properties for the current revision.  The keys of the hash
230       are the property names and the values of the hash are the property
231       values.  For example, the author of a revision is available with
232       "$args->{'svn:author'}".
233
234       If you change values in the 'props' hashref, those changes are visible
235       to all subsequent filters in the pipeline.  This can be useful and
236       dangerous.  Dangerous if you accidentally modify a property, useful if
237       you intentionally modify a property.  For instance, it's possible to
238       make a "selection" filter which uses Babelfish to translate log
239       messages from one language to another (see SVK::Log::Filter::Babelfish
240       on CPAN).  By modifying the 'svn:log' property, other log filters can
241       operate on the translated log message without knowing that it's
242       translated.
243
244   stash
245       The value of the 'stash' argument is a reference to a hash.  The stash
246       persists throughout the entire log filtering process and is provided to
247       every method that the filter pipeline calls.  The stash may be used to
248       pass information from one filter to another filter in the pipeline.
249
250       When creating new keys in the stash, it's important to avoid
251       unintentional name collisions with other filters in the pipeline.  A
252       good practice is to preface the name of each stash key with the name of
253       your filter ("myfilter_key") or to create your own hash reference
254       inside the stash ("$stash->{myfilter}{key}").  If your filter puts
255       information into the stash that other filters may want to access,
256       please document the location and format of that information for other
257       filter authors.
258

STASH REFERENCE

quiet

261       If the user included the "--quiet" flag when invoking "svk log" the
262       value of this key will be a true value.  Otherwise, the value will be
263       false.
264

verbose

266       If the user included the "--verbose" flag when invoking "svk log" the
267       value of this key will be a true value.  Otherwise, the value will be
268       false.
269
270
271
272perl v5.12.4                      2008-08-05               SVK::Log::Filter(3)
Impressum