manpagez: man pages & more
man SVK::Log::Filter(3)
Home | html | info | man
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.10.0                      2008-08-04               SVK::Log::Filter(3)

Mac OS X 10.6 - Generated Thu Sep 17 20:15:20 CDT 2009
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.