.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SVN::Web::action 3pm"
.TH SVN::Web::action 3pm "2012-10-17" "perl v5.18.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SVN::Web::action \- base class for SVN::Web::actions
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the base class for all SVN::Web actions.  It provides a
constructor and some useful utility methods that actions may find
useful.  It also contains documentation for anyone interested in
writing new SVN::Web actions.
.SH "OVERVIEW"
.IX Header "OVERVIEW"
SVN::Web actions are Perl modules loaded by SVN::Web.  They are
expected to retrieve some information from the Subversion repository,
and return that information ready for the user's browser, optionally
via formatting by a Template::Toolkit template.
.PP
Action names are listed in the SVN::Web configuration file,
\&\fIconfig.yaml\fR, in the \f(CW\*(C`actions:\*(C'\fR clause.  Each entry specifies the
class that implements the action, options that are set globally
for that action, and metadata that describes when and how the action
should appear in the action menu.
.PP
.Vb 10
\&  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
\&    ...
.Ve
.PP
Each action is a class that must implement a \f(CW\*(C`run()\*(C'\fR method.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
Actions should derive from SVN::Web::action.  This gives them a
default constructor that generates a hash based object.
.PP
.Vb 1
\&  use base \*(AqSVN::Web::action\*(Aq;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "\fIrun()\fP"
.IX Subsection "run()"
The \f(CW\*(C`run\*(C'\fR method is where the action carries out its work.
.PP
\fIParameters\fR
.IX Subsection "Parameters"
.PP
The method is passed a single parameter, the standard \f(CW$self\fR hash
ref.  This contains numerous useful keys.
.ie n .IP "$self\->{opts}" 4
.el .IP "\f(CW$self\fR\->{opts}" 4
.IX Item "$self->{opts}"
The options for this action from \fIconfig.yaml\fR.  Using the example from the
\&\s-1OVERVIEW\s0, this would lead to:
.Sp
.Vb 3
\&  $self\->{opts} = { \*(Aqoption1\*(Aq => \*(Aqvalue1\*(Aq,
\&                    \*(Aqoption2\*(Aq => \*(Aqvalue2\*(Aq,
\&                  };
.Ve
.ie n .IP "$self\->{cgi}" 4
.el .IP "\f(CW$self\fR\->{cgi}" 4
.IX Item "$self->{cgi}"
An instance of a \s-1CGI\s0 compatible object corresponding to the current request.  This is normally an object from either the \s-1CGI\s0 or CGI::Fast modules, although it is possible to specify another class with the \f(CW\*(C`cgi_class\*(C'\fR directive in
\&\fIconfig.yaml\fR. Since we now use Plack, this is a Plack::Request object.
.Sp
You can use this object to retrieve the values of any parameters passed to
your action.
.Sp
For example, if your action takes a \f(CW\*(C`rev\*(C'\fR parameter, indicating the
repository revision to work on;
.Sp
.Vb 1
\&  my $rev = $self\->{cgi}\->param(\*(Aqrev\*(Aq);
.Ve
.ie n .IP "$self\->{path}" 4
.el .IP "\f(CW$self\fR\->{path}" 4
.IX Item "$self->{path}"
The path in the repository that was passed to the action.
.ie n .IP "$self\->{navpaths}" 4
.el .IP "\f(CW$self\fR\->{navpaths}" 4
.IX Item "$self->{navpaths}"
A reference to an array of path components, one for each directory
(and possible final file) in \f(CW$self\fR\->{path}.  Equivalent to \f(CW\*(C`[\ split(\*(Aq/\*(Aq,\ $self\->{path})\ ]\*(C'\fR
.ie n .IP "$self\->{config}" 4
.el .IP "\f(CW$self\fR\->{config}" 4
.IX Item "$self->{config}"
The config hash, as read by \s-1YAML\s0 from \fIconfig.yaml\fR.  Directives
from the config file are second level hash keys.  For example, the
\&\f(CW\*(C`actions\*(C'\fR configuration directive contains a list of valid actions.
.Sp
.Vb 1
\&  my @valid_actions = @{ $self\->{config}\->{actions} };
.Ve
.ie n .IP "$self\->{reposname}" 4
.el .IP "\f(CW$self\fR\->{reposname}" 4
.IX Item "$self->{reposname}"
The symbolic name of the repository being accessed.
.ie n .IP "$self\->{repos}" 4
.el .IP "\f(CW$self\fR\->{repos}" 4
.IX Item "$self->{repos}"
A instance of the SVN::Repos class, corresponding to the repository
being accessed.  This repository has already been opened.
.Sp
For example, to find the youngest (i.e., most recent) revision of the
repository;
.Sp
.Vb 1
\&  my $yr = $self\->{repos}\->fs()\->youngest_rev();
.Ve
.ie n .IP "$self\->{action}" 4
.el .IP "\f(CW$self\fR\->{action}" 4
.IX Item "$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.
.ie n .IP "$self\->{script}" 4
.el .IP "\f(CW$self\fR\->{script}" 4
.IX Item "$self->{script}"
The \s-1URL\s0 for the currently running script.
.PP
\fIReturn value\fR
.IX Subsection "Return value"
.PP
The return value from \f(CW\*(C`run()\*(C'\fR determines how the data from the action is
displayed.
.PP
Using a template
.IX Subsection "Using a template"
.PP
If \f(CW\*(C`run()\*(C'\fR wants a template to be displayed containing formatted data
from the method then the hash ref should contain two keys.
.IP "template" 4
.IX Item "template"
This is the name of the template to return.  By convention the template and
the action share the same name.
.IP "data" 4
.IX Item "data"
This is a hash ref.  The hash keys become variables of the same name in the
template.
.PP
The character set and \s-1MIME\s0 type can also be specified, in the
\&\f(CW\*(C`charset\*(C'\fR and \f(CW\*(C`mimetype\*(C'\fR keys.  If these values are not specified
then they default to \f(CW\*(C`UTF\-8\*(C'\fR and \f(CW\*(C`text/html\*(C'\fR respectively.
.PP
E.g., for an action named \f(CW\*(C`my_action\*(C'\fR, using a template called
\&\f(CW\*(C`my_action\*(C'\fR that looks like this:
.PP
.Vb 1
\&  <p>The youngest interesting revision of [% file %] is [% rev %].</p>
.Ve
.PP
then this code would be appropriate.
.PP
.Vb 6
\&  # $rev and $file set earlier in the method
\&  return { template => \*(Aqmy_action\*(Aq,
\&           data     => { rev  => $rev,
\&                         file => $file,
\&                       },
\&         };
.Ve
.PP
Returning data with optional charset and \s-1MIME\s0 type
.IX Subsection "Returning data with optional charset and MIME type"
.PP
If the action does not want to use a template and just wants to return
data, but retain control of the character set and \s-1MIME\s0 type, \f(CW\*(C`run()\*(C'\fR
should return a hash ref.  This should contain a key called \f(CW\*(C`body\*(C'\fR,
the value of which will be sent directly to the browser.
.PP
The character set and \s-1MIME\s0 type can also be specified, in the
\&\f(CW\*(C`charset\*(C'\fR and \f(CW\*(C`mimetype\*(C'\fR keys.  If these values are not specified
then they default to \f(CW\*(C`UTF\-8\*(C'\fR and \f(CW\*(C`text/html\*(C'\fR respectively.
.PP
E.g., for an action that generates a \s-1PNG\s0 image from data in the
repository (perhaps using SVN::Churn);
.PP
.Vb 4
\&  # $png contains the PNG image, created earlier in the method
\&  return { mimetype => \*(Aqimage/png\*(Aq,
\&           body     => $png
\&         };
.Ve
.PP
Returning \s-1HTML\s0 with default charset and \s-1MIME\s0 type
.IX Subsection "Returning HTML with default charset and MIME type"
.PP
If the action just wants to return \s-1HTML\s0 in \s-1UTF\-8,\s0 it can return a single
scalar that contains the \s-1HTML\s0 to be sent to the browser.
.PP
.Vb 1
\&  return "<p>hello, world</p>";
.Ve
.SH "UTILITY METHODS"
.IX Header "UTILITY METHODS"
The following methods are intended to share common code among actions.
.ie n .SS "recent_interesting_rev($path, $rev)"
.el .SS "recent_interesting_rev($path, \f(CW$rev\fP)"
.IX Subsection "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.
.PP
If called in an array context it returns all the arguments normally passed
to a log message receiver.
.SS "\fIget_revs()\fP"
.IX Subsection "get_revs()"
Returns a list of 4 items.  In order, they are:
.IP "Explicit rev" 4
.IX Item "Explicit rev"
The value of any \s-1CGI \s0\f(CW\*(C`rev\*(C'\fR parameter passed to the action ($exp_rev).
.IP "Youngest rev" 4
.IX Item "Youngest rev"
The repository's youngest revision ($yng_rev) for the current path.
This is not necessarily the same as the repositories youngest
revision.
.IP "Actual rev" 4
.IX Item "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.
.IP "Head" 4
.IX Item "Head"
A boolean value indicating whether or not we can be considered to be
at the \s-1HEAD\s0 of the repository ($at_head).
.SS "\fIformat_svn_timestamp()\fP"
.IX Subsection "format_svn_timestamp()"
Given a cstring that represents a Subversion time, format the time using
\&\fIPOSIX::strftime()\fR and the current settings of the \f(CW\*(C`timedate_format\*(C'\fR and
\&\f(CW\*(C`timezone\*(C'\fR configuration directives.
.SH "CACHING"
.IX Header "CACHING"
If the output from the action can usefully be cached then consider
implementing a \f(CW\*(C`cache_key\*(C'\fR method.
.PP
This method receives the same parameters as the \f(CW\*(C`run()\*(C'\fR method, and
must use those parameters to generate a unique key for the content
generated by the \f(CW\*(C`run()\*(C'\fR method.
.PP
For example, consider the standard \f(CW\*(C`Revision\*(C'\fR action.  This action
only depends on a single parameter \*(-- the repository revision number.
So that makes a good cache key.
.PP
.Vb 2
\&  sub cache_key {
\&      my $self = shift;
\&
\&      return $self\->{cgi}\->param(\*(Aqrev\*(Aq);
\&  }
.Ve
.PP
Other actions may have more complicated keys.
.SH "ERRORS AND EXCEPTIONS"
.IX Header "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.
.PP
Exceptions, along with examples, are described in SVN::Web::X.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2005\-2007 by Nik Clayton \f(CW\*(C`<nik@FreeBSD.org>\*(C'\fR.
.PP
Copyright 2012 by Dean Hamstead \f(CW\*(C`<dean@fragfest.com.au>\*(C'\fR.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
See <http://www.perl.com/perl/misc/Artistic.html>