ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).



SVK::Log::Filter(3)                  User Contributed Perl Documentation                 SVK::Log::Filter(3)



NAME
       SVK::Log::Filter - base class for all log filters

DESCRIPTION
       SVK::Log::Filter is a class for displaying or otherwise processing revision properties.  The SVK
       "log" command uses filter classes to handle the details of processing the revision properties.  The
       bulk of this document explains how to write those filter classes.

       A log filter is just a Perl class with special methods.  At specific points while processing log
       information, SVK calls these methods on the filter object.  SVK::Log::Filter provides sensible
       defaults for each of the methods it calls.  The methods (in order of invocation) are "setup",
       "header", "revision", "footer", "teardown". Each is fully documented in the section "METHOD
       REFERENCE".

TUTORIAL
       Although log filters which output and log filters which select are exactly the same kind of objects,
       they are generally conceptualized separately.  The following tutorial provides a simple example for
       each type of filter.

       OUTPUT

       For our simple output filter example, we want to display something like the following

           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

       Our simple selection filter example will pass revisions based on whether the revision number is even
       or odd.  The filter accepts a single argument 'odd' or 'even' indicating which revisions should be
       passed down the pipeline.  Additionally, if the filter ever encounters the revision number "42" it
       will stop the entire pipeline and process no more revisions.  The invocation is something like "svk
       log --filter 'parity even'" to display all even revisions up to r42.

          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.

METHODS
       This is a list of all the methods that SVK::Log::Filter implements and a description of how they
       should be called.  When defining a subclass, one need only override those methods that are necessary
       for implementing the filter.  All methods have sensible defaults (namely, do nothing).  The methods
       are listed here in the order in which they are called by the pipeline.

       All methods except "new" and "pipeline" receive a single hash reference as their first argument
       (after the invocant, of course).  The 'Receives' section in the documentation below indicates which
       named arguments are present in that hash.

       new

       Builds a new object from a hash reference.  The value of any arguments provided to the log filter on
       the command line are placed in the 'argument' attribute of the object.  Generally, there is no need
       to override the "new" method because the "setup" method can be overriden instead.

       setup

       Receives: "stash"

       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

       Receives: "stash"

       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

       Receives: "paths", "rev", "props", "stash", "get_remoterev"

       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

       Receives: "stash"

       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

       Receives: "stash"

       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

       This method is not called by the filter pipeline.  Rather, it's used by log filters to control the
       pipeline's behavior.  It accepts a single scalar as the argument.  If the argument is 'next', the
       pipeline stops processing the current revision (including any output filter) and starts processing
       the next revision starting over at the beginning of the pipeline.  If the argument to "pipeline" is
       'last', the pipeline is stopped entirely (including any output filters).  Once the pipeline has
       stopped, the SVK log command finishes any final details and stops.

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

get_remoterev
       If the value of this argument is true, the value is a coderef.  When the coderef is invoked with a
       single revision number as the argument, it returns the number of the equivalent revision in the
       upstream repository.  The value of this key may be undefined if the logs are being processed for
       something other than a mirror.  The following code may be useful when working with "get_remoterev"

           my           ( $stash, $rev, $get_remoterev)
           = @{$args}{qw(  stash   rev   get_remoterev )};
           my $remote_rev = $get_remoterev ? $get_remoterev->($rev) : 'unknown';
           print "The remote revision for r$rev is $remote_rev.\n";

       paths

       The value of the 'paths' argument is an SVK::Log::ChangedPaths object.  The object provides methods
       for indicating which paths were changed by this revision and approximately how they were changed
       (modified file contents, modified file properties, etc.)

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

       rev

       The value of the 'rev' argument is the Subversion revision number for the current revision.

       props

       The value of the 'props' argument is a hash reference containing all the revision properties for the
       current revision.  The keys of the hash are the property names and the values of the hash are the
       property values.  For example, the author of a revision is available with "$args->{'svn:author'}".

       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

       The value of the 'stash' argument is a reference to a hash.  The stash persists throughout the entire
       log filtering process and is provided to every method that the filter pipeline calls.  The stash may
       be used to pass information from one filter to another filter in the pipeline.

       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.

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

verbose
       If the user included the "--verbose" flag when invoking "svk log" the value of this key will be a
       true value.  Otherwise, the value will be false.



perl v5.8.8                                      2006-12-28                              SVK::Log::Filter(3)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.