OUTPUT

    1. r3200 by john
    2. r3194 by tom
    3. r3193 by larry

Namely, the number the revisions we've seen, then show the actual revision number from the repository and indicate the author of that revision. We want this log filter to be accessible by a command like "svk log --output list" The code to accomplish that is

   1   package SVK::Log::Filter::List;
   2   use base qw( SVK::Log::Filter );
       
   3   sub setup {
   4       my ($self) = @_;
   5       $self->{count} = 1;
   6   }
       
   7   sub revision {
   8       my ($self, $args) = @_;
       
   9       printf "%d. r%d by %s\n",
  10           $self->{count}++,
  11           $args->{rev},
  12           $args->{props}{'svn:author'}
  13       ;
  14   }

First, we must establish the name of this filter. SVK looks for filters with the namespace prefix "SVK::Log::Filter". The final portion of the name can either have the first letter capitalized or all the letters capitalized. On line 2, we use SVK::Log::Filter as the base class so that we can get the default method implementations.

On lines 3-6, we get to the first meat. Since we want to count the revisions that we see, we have to store the information somewhere that will persist between method calls. We just store it in the log filter object itself. Finally, on line 6, our "setup" method is finished. The return value of the method is irrelevant.

The "revision" method on lines 7-14 does the real work of the filter. First (line 8) we extract arguments into a hashref $args. Then it simply prints what we want it to display. SVK takes care of directing output to the appropriate place. You'll notice that the revision properties are provided as a hash. The key of the hash is the name of the property and the value of the hash is the value of the property.

That's it. Put SVK::Log::Filter::List somewhere in @INC and SVK will find it.

SELECTION

   1   package SVK::Log::Filter::Parity;
   2   use base qw( SVK::Log::Filter );
       
   3   sub setup {
   4       my ($self) = @_;
       
   5       my $argument = lc $self->{argument};
   6       $self->{bit} = $argument eq 'even' ? 0
   7                    : $argument eq 'odd'  ? 1
   8                    : die "Parity argument not 'even' or 'odd'\n"
   9                    ;
  10   }
       
  11   sub revision {
  12       my ($self, $args) = @_;
       
  13       my $rev = $args->{rev};
  14       $self->pipeline('last') if $rev == 42;
  15       $self->pipeline('next') if $rev % 2 != $self->{bit};
  16   }

There are only a few differences between this implementation and the output filter implementation. The first difference is in line 5. When a log filter object is created, the default "new" method creates the 'argument' key which contains the command-line argument provided to your filter. In this case, the argument should be either 'even' or 'odd'. Based on the argument, we update the object to remind us what parity we're looking for.

The unique characteristics of "revision" are the calls to the "pipeline" method in lines 14 and 15. If we want to stop the pipeline entirely, call "pipeline" with the argument 'last' (think "this is the last revision"). The current revision and all subsequent revisions will not be processed by the filter pipelin. If the argument to "pipeline" is 'next' (think "go to the next revision"), the current revision will not be displayed and the pipeline will proceed with the next revision in sequence. If you don't call "pipeline", the current revision is passed down the remainder of the pipeline so that it can be processed and displayed.

new

setup

This method is called once just before the filter is used for the first time. It's conceptually similar to "new", but allows the filter developer to ignore the creation of the filter object. This is the place to do filter initialization, process command-line arguments, read configuration files, connect to a database, etc.

header

This method is called once just before the first revision is processed but after "setup" has completed. This is an ideal place to display information which should appear at the top of the log display.

revision

This method is called for each revision that SVK wants to process. The bulk of a log filter's code implements this method. Output filters may simply print the information that they want displayed. Other filters should either modify the revision properties (see "props") or use pipeline commands (see "pipeline") to skip irrelevant revisions.

footer

This method is similar to the "header" method, but it's called once after all the revisions have been displayed. This is the place to do any final output.

teardown

This method is called once just before the log filter is discarded. This is the place to disconnect from databases, close file handles, etc.

pipeline

paths

See the documentation for SVK::Log::ChangedPaths for more details.

rev

props

If you change values in the 'props' hashref, those changes are visible to all subsequent filters in the pipeline. This can be useful and dangerous. Dangerous if you accidentally modify a property, useful if you intentionally modify a property. For instance, it's possible to make a "selection" filter which uses Babelfish to translate log messages from one language to another (see SVK::Log::Filter::Babelfish on CPAN). By modifying the 'svn:log' property, other log filters can operate on the translated log message without knowing that it's translated.

stash

When creating new keys in the stash, it's important to avoid unintentional name collisions with other filters in the pipeline. A good practice is to preface the name of each stash key with the name of your filter ("myfilter_key") or to create your own hash reference inside the stash ("$stash->{myfilter}{key}"). If your filter puts information into the stash that other filters may want to access, please document the location and format of that information for other filter authors.