SVK::Log::Filter(3)

SVK::Log::Filter(3) 💖

okay bestie, welcome to the User Contributed Perl Documentation corner of the world, because we're about to talk about SVK::Log::Filter — the base class for ALL the log filters. yes, all of them. she's the mother. 👑

---

✨ NAME ✨

SVK::Log::Filter — base class for all log filters 🫶

---

🌸 DESCRIPTION 🌸

so SVK::Log::Filter is a class for displaying or otherwise processing revision properties. the SVK log command uses filter classes to handle all the fiddly details of processing revision properties, and honestly? the bulk of this document is explaining how to write those filter classes. so if that's your goal, you're in the right place.

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 — like, she always shows up with something, no cap.

the methods, in order of invocation, are setup, header, revision, footer, teardown. each one is fully documented in the section METHOD REFERENCE. 📋

---

🎀 TUTORIAL 🎀

ngl, log filters which output and log filters which select are exactly the same kind of objects, but we generally conceptualize them separately, so the following tutorial gives you a cute simple example for each type of filter. 💅

🦋 OUTPUT

for our simple output filter example, we want to display something like this:

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

namely: the number of the revisions we've seen, then the actual revision number from the repository, then the author of that revision. and 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 things first: we have to 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 — either way, she'll find you. 💖

on line 2, we use SVK::Log::Filter as the base class so we can get the default method implementations. free stuff, we love that.

on lines 3-6 we get to the first meat 🍓. since we want to count the revisions we see, we have to store that info somewhere that persists between method calls. we just store it in the log filter object itself. and on line 6, our setup method is finished. the return value of the method is irrelevant — don't stress about it.

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, so you don't gotta worry about that. you'll notice 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. iconic. ✨

that's it. put SVK::Log::Filter::List somewhere in @INC and SVK will find it. periodt.

🌈 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 — and this is the dramatic part 😭 — 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 pipeline. 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 it can be processed and displayed. 🫶

---

💅 METHODS 💅

this is a list of all the methods that SVK::Log::Filter implements, plus a description of how they should be called. when you're defining a subclass, you only need to override those methods that are necessary for implementing the filter. all methods have sensible defaults (namely, do nothing — she's chill like that). 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 tells you 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 overridden instead. save yourself the work bestie.

💜 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 it lets the filter developer 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. it's giving main character energy for setup tasks. 👑

💜 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. this is the whole vibe of the operation fr fr. 🔥

💜 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. the goodbye text, if you will. 😭

💜 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. clean up your room bestie, we're leaving. 🧹

💜 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. that's the whole ride. 🎢

---

🦋 ARGUMENTS 🦋

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

💫 get_remoterev 💫

ok so if this argument's value is true, then bestie, that value is a coderef. and when you invoke that coderef with a single revision number as its argument, it hands you back the number of the equivalent revision in the upstream repository. ✨

heads up tho: the value of this key can be undefined if the logs are being processed for something other than a mirror. so like… vibe check it first, okay?

this little snippet right here might come in handy when you're 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. that object comes with methods that tell you which paths got changed by this revision, and like, approximately how they changed — modified file contents, modified file properties, etc. 💅

see the documentation for SVK::Log::ChangedPaths for the whole tea. 🫖

---

⭐ rev ⭐

the value of the 'rev' argument is the Subversion revision number for the current revision. that's it, that's the whole thing. simple. iconic. 😌

---

🔥 props 🔥

the value of the 'props' argument is a hash reference holding 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. so like, the author of a revision? that's right there in $args->{'svn:author'}. 💖

now listen up because this part is important:

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 even knowing it's translated. sneaky. genius. obsessed. ✨

---

🎀 stash 🎀

the value of the 'stash' argument is a reference to a hash. the stash persists throughout the entire log filtering process and gets handed to every method that the filter pipeline calls. so basically it's the group chat of filters — you can use it to pass info from one filter to another in the pipeline. 🫶

when you're creating new keys in the stash, bestie, please avoid unintentional name collisions with other filters in the pipeline. 😭 good practice is:

• preface the name of each stash key with the name of your filter: "myfilter_key"
• or create your own hash reference inside the stash: "$stash->{myfilter}{key}"

and if your filter puts information into the stash that other filters might wanna access, please document the location and format of that info for other filter authors. be a considerate queen. 👑

---

🌈 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. periodt. ✨

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. twin of quiet, no cap. 💜

---

and that's a wrap on the whole page, bestie!! 🎉 this one's from perl v5.42.0, dated 2025-07-25, and it's the SVK::Log::Filter(3) manpage — go forth and filter those logs like the main character you are. 💅🌸🦋