SVN::Web::action(3pm)

💖 SVN::Web::action — the blueprint for every SVN::Web action 💖

okay bestie, welcome to SVN::Web::action, which is the base class for all the SVN::Web actions, periodt. 🌸

---

✨ NAME ✨

SVN::Web::action — the base class for SVN::Web::actions, and honestly it's giving foundation-of-everything energy 👑

---

🦋 DESCRIPTION 🦋

So here's the tea: this is the base class for all SVN::Web actions. It hands you a constructor plus a bunch of genuinely useful utility methods that actions can vibe with, and it also has the docs for anyone who wants to write brand new SVN::Web actions. no cap, this is your starting point. 💅

---

🌈 OVERVIEW 🌈

SVN::Web actions are Perl modules that SVN::Web loads up. They're expected to go get some info from the Subversion repository and hand it back ready for the user's browser — optionally after a Template::Toolkit template has done its little formatting moment. ✨

Action names live in the SVN::Web config file, config.yaml, inside the "actions:" clause. Every entry says which class implements the action, the options set globally for that action, and the metadata describing when and how the action should show up in the action menu.

  actions:
    ...
    new_action:
      class: Class::That::Implements::Action
      action_menu:            # Optional
        show:
          - file              # Zero or more of this, ...
          - directory         # ... this ...
          - revision          # ... or this.
          - global            # Or possibly just this one
        link_text: (text)     # Mandatory
        head_only: 1          # Optional
        icon: /a/path         # Optional
      opts:
        option1: value1
        option2: value2
    ...

Every action is a class, and that class must implement a run() method. mandatory. non-negotiable. 🫶

---

🎀 SUBCLASSING 🎀

Actions should derive from SVN::Web::action. That's the whole move — it gives them a default constructor that generates a hash based object. slay.

  use base 'SVN::Web::action';

---

💜 METHODS 💜

🌸 run()

The "run" method is literally where the action does its work. main character moment fr fr.

Parameters

The method gets a single parameter: the standard $self hash ref. This contains a whole bunch of useful keys.

• $self->{opts} — the options for this action from config.yaml. Using the example from the OVERVIEW, this would lead to:

    $self->{opts} = { 'option1' => 'value1',
                      'option2' => 'value2',
                    };

• $self->{cgi} — an instance of a CGI compatible object corresponding to the current request. This is normally an object from either the CGI or CGI::Fast modules, although it is possible to specify another class with the "cgi_class" directive in config.yaml. Since we now use Plack, this is a Plack::Request object.

You can use this object to retrieve the values of any parameters passed to your action.

For example, if your action takes a "rev" parameter, indicating the repository revision to work on;

    my $rev = $self->{cgi}->param('rev');

• $self->{path} — the path in the repository that was passed to the action. 📍
• $self->{navpaths} — a reference to an array of path components, one for each directory (and possible final file) in $self->{path}. Equivalent to [ split('/', $self->{path}) ]
• $self->{config} — the config hash, as read by YAML from config.yaml. Directives from the config file are second level hash keys. For example, the "actions" configuration directive contains a list of valid actions.

    my @valid_actions = @{ $self->{config}->{actions} };

• $self->{reposname} — the symbolic name of the repository being accessed. 🏷️
• $self->{repos} — a instance of the SVN::Repos class, corresponding to the repository being accessed. This repository has already been opened.

For example, to find the youngest (i.e., most recent) revision of the repository;

    my $yr = $self->{repos}->fs()->youngest_rev();

• $self->{action} — the action that has been requested. It's possible for multiple action names to be mapped to a single class in the config file, and this lets you differentiate between them. 👀
• $self->{script} — the URL for the currently running script.

Return value

The return value from run() decides how the data from the action gets displayed. this is the vibe check of the whole operation.

Using a template

If run() wants a template displayed containing formatted data from the method, then the hash ref should contain two keys.

• template — the name of the template to return. By convention the template and the action share the same name. 🪞
• data — a hash ref. The hash keys become variables of the same name in the template.

The character set and MIME type can also be specified, in the "charset" and "mimetype" keys. If these values are not specified then they default to "UTF-8" and "text/html" respectively.

E.g., for an action named "my_action", using a template called "my_action" that looks like this:

  <p>The youngest interesting revision of [% file %] is [% rev %].</p>

then this code would be appropriate.

  # $rev and $file set earlier in the method
  return { template => 'my_action',
           data     => { rev  => $rev,
                         file => $file,
                       },
         };

Returning data with optional charset and MIME type

If the action does not want to use a template and just wants to return data, but retain control of the character set and MIME type, run() should return a hash ref. This should contain a key called "body", the value of which will be sent directly to the browser. 📤

The character set and MIME type can also be specified, in the "charset" and "mimetype" keys. If these values are not specified then they default to "UTF-8" and "text/html" respectively.

E.g., for an action that generates a PNG image from data in the repository (perhaps using SVN::Churn);

  # $png contains the PNG image, created earlier in the method
  return { mimetype => 'image/png',
           body     => $png
         };

Returning HTML with default charset and MIME type

If the action just wants to return HTML in UTF-8, it can return a single scalar that contains the HTML to be sent to the browser. simple as that, and honestly iconic. ✨

  return "<p>hello, world</p>";

---

⭐ UTILITY METHODS ⭐

The following methods are intended to share common code among actions. friendship bracelets but for Perl. 🫶

🧚 recent_interesting_rev($path, $rev)

Given a repository path, and a revision number, returns the most recent interesting revision for the path that is the same as, or older (i.e., smaller) than the revision number.

If called in an array context it returns all the arguments normally passed to a log message receiver.

🍓 get_revs()

Returns a list of 4 items. In order, they are:

• Explicit rev — the value of any CGI "rev" parameter passed to the action ($exp_rev).
• Youngest rev — the repository's youngest revision ($yng_rev) for the current path. This is not necessarily the same as the repositories youngest revision. ⚠️
• Actual rev — the actual revision ($act_rev) that will be acted on. This is the explicit rev, if it's defined, otherwise it's the youngest rev.
• Head — a boolean value indicating whether or not we can be considered to be at the HEAD of the repository ($at_head). 👑

🌈 format_svn_timestamp()

Given a cstring that represents a Subversion time, format the time using POSIX::strftime() and the current settings of the "timedate_format" and "timezone" configuration directives. ⏰

---

💀 CACHING 💀

If the output from the action can usefully be cached then consider implementing a "cache_key" method.

This method receives the same parameters as the run() method, and must use those parameters to generate a unique key for the content generated by the run() method.

For example, consider the standard "Revision" action. This action only depends on a single parameter — the repository revision number. So that makes a good cache key. 🔑

  sub cache_key {
      my $self = shift;

      return $self->{cgi}->param('rev');
  }

Other actions may have more complicated keys.

---

😭 ERRORS AND EXCEPTIONS 😭

If your action needs to fail for some reason — perhaps the parameters passed to it are incorrect, or the user lacks the necessary permissions — then throw an exception.

Exceptions, along with examples, are described in SVN::Web::X.

---

👑 COPYRIGHT 👑

Copyright 2005-2007 by Nik Clayton "<nik@FreeBSD.org>".

Copyright 2012 by Dean Hamstead "<dean@fragfest.com.au>".

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See <http://www.perl.com/perl/misc/Artistic.html>

---

okay that's the whole page bestie!! go forth and write the most slay action of your life 💖

this one came to you from the perl v5.40.1 manual set, dated 2025-04-09, and it's the SVN::Web::action(3pm) page — mwah, take care of her 🎀✨