.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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 "App::KGB::Client 3pm"
.TH App::KGB::Client 3pm "2024-01-01" "perl v5.36.0" "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"
App::KGB::Client \- relay commits to KGB servers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use App::KGB::Client;
\&    my $client = App::KGB::Client( <parameters> );
\&    $client\->run;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBApp::KGB::Client\fR is the backend behind \fBkgb\-client\fR\|(1). It handles
the repository-independent parts of sending the notifications to the \s-1KGB\s0 server,
\&\fBkgb\-bot\fR\|(1). Details about extracting change from commits, branches and
modules is done by sub-classes specific to the version control system in use.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The following parameters are accepted in the constructor:
.IP "\fBrepo_id\fR \fIrepository name\fR" 4
.IX Item "repo_id repository name"
Short repository identifier. Will be used for identifying the repository to the
\&\s-1KGB\s0 daemon, which will also use this for \s-1IRC\s0 notifications. \fBMandatory\fR.
.IP "\fBuri\fR \fI\s-1URI\s0\fR" 4
.IX Item "uri URI"
\&\s-1URI\s0 of the \s-1KGB\s0 server. Something like \f(CW\*(C`http://some.server:port\*(C'\fR. \fBMandatory\fR
either as a top-level parameter or as a sub-parameter of \fBservers\fR array.
.IP "\fBproxy\fR \fI\s-1URI\s0\fR" 4
.IX Item "proxy URI"
\&\s-1URI\s0 of the \s-1SOAP\s0 proxy. If not given, it is the value of the \fBuri\fR option, with
\&\f(CW\*(C`?session=KGB\*(C'\fR added.
.IP "\fBpassword\fR \fIpassword\fR" 4
.IX Item "password password"
Password for authentication to the \s-1KGB\s0 server. \fBMandatory\fR either as a
top-level parameter or as a sub-parameter of \fBservers\fR array.
.IP "\fBtimeout\fR \fIseconds\fR" 4
.IX Item "timeout seconds"
Timeout for server communication. Default is 15 seconds, as we want instant \s-1IRC\s0
and commit response.
.IP "\fBservers\fR" 4
.IX Item "servers"
An array of servers, each an instance of App::KGB::Client::ServerRef class.
.Sp
When several servers are configured, the list is shuffled and then the servers
are tried one after another until a successful request is done, or the list is
exhausted, in which case an exception is thrown.
.Sp
When shuffling, preference is added to the last server used by the client, or
by other clients (given \f(CW\*(C`status_dir\*(C'\fR is configured).
.IP "\fBbatch_messages\fR" 4
.IX Item "batch_messages"
If true, the notifications are sent as a batch in one request to the server.
Useful with \s-1VCS\s0 that send many changes a time (e.g. Git).
.Sp
Defaults to false, but will be changed later after some grace period for server
upgrade.
.IP "\fBbr_mod_re\fR" 4
.IX Item "br_mod_re"
A list of regular expressions (simple strings, not qr objects) that serve
for detection of branch and module of commits. Each item from the list is tried
in turn, until an item is found that matches all the paths that were modified
by the commit. Regular expressions must have two captures: the first one giving
the branch name, and the second one giving the module name.
.Sp
All the paths that were modified by the commit must resolve to the same branch
and module in order for the branch and module to be transmitted to the \s-1KGB\s0
server.
.Sp
.Vb 4
\&    Example: ^/(trunk)/([^/]+)/
\&             # /trunk/module/file
\&             ^/branches/([^/]+)/([^/]+)/
\&             # /branches/test/module/file
.Ve
.IP "\fBmod_br_re\fR" 4
.IX Item "mod_br_re"
Same as \fBbr_mod_re\fR, but captures module name first and branch name second.
.Sp
.Vb 2
\&    Example: ^/branches/([^/]+)/([^/]+)/
\&             # /branches/test/module/file
.Ve
.IP "\fBignore_branch\fR" 4
.IX Item "ignore_branch"
When most of the development is in one branch, transmitting it to the \s-1KGB\s0
server and seeing it on \s-1IRC\s0 all the time can be annoying. Therefore, if you
define \fBignore_branch\fR, and a given commit is in a branch with that name, the
branch name is not transmitted to the server. Module name is still transmitted.
.IP "\fBmodule\fR" 4
.IX Item "module"
Forces explicit module name, overriding the branch and module detection. Useful
in Git-hosted sub-projects that want to share single configuration file, but
still want module indication in notifications.
.IP "\fBsingle_line_commits\fR \fIoff|forced|auto\fR" 4
.IX Item "single_line_commits off|forced|auto"
Request different modes of commit message processing:
.RS 4
.IP "\fIoff\fR" 4
.IX Item "off"
No processing is done. The commit message is printed as was given, with each
line in a separate \s-1IRC\s0 message, blank lines omitted. This is the only possible
behaviour in versions before 1.14.
.IP "\fIforced\fR" 4
.IX Item "forced"
Only the first line is sent to \s-1IRC,\s0 regardless of whether it is followed by a
blank line or not.
.IP "\fIauto\fR" 4
.IX Item "auto"
If the first line is followed by an empty line, only the first line is sent to
\&\s-1IRC\s0 and the rest is ignored. This is the default since version 1.14.
.RE
.RS 4
.RE
.IP "\fBuse_irc_notices\fR" 4
.IX Item "use_irc_notices"
If true signals the server that it should use \s-1IRC\s0 notices instead of regular
messages. Use this if regular messages are too distracting for your channel.
.IP "\fBuse_color\fR" 4
.IX Item "use_color"
If true (the default) signals the server that it should use colors for commit
notifications.
.IP "\fBstatus_dir\fR" 4
.IX Item "status_dir"
Specifies a directory to store information about the last server contacted
successfully. The client would touch files in that directory after successful
completion of a notification with remote server.
.Sp
Later, when asked to do another notification, the client would start from the
most recently contacted server. If that was contacted too far in the past, the
information in the directory is ignored and a random server is picked, as
usual.
.IP "\fBverbose\fR" 4
.IX Item "verbose"
Print diagnostic information.
.IP "\fBprotocol\fR \fIversion\fR" 4
.IX Item "protocol version"
Use specified protocol version. If \f(CW\*(C`auto\*(C'\fR (the default), the version of the
protocol \f(CW2\fR, unless \fBweb_link\fR is also given, in which case protocol version
\&\f(CW3\fR is default;
.IP "\fBweb_link\fR \fItemplate\fR" 4
.IX Item "web_link template"
A web link template to be sent to the server. The following items are expanded:
.RS 4
.IP "${branch}" 4
.IX Item "${branch}"
.PD 0
.IP "${module}" 4
.IX Item "${module}"
.IP "${commit}" 4
.IX Item "${commit}"
.IP "${project}" 4
.IX Item "${project}"
.RE
.RS 4
.RE
.IP "\fBshort_url_service\fR \fIservice\fR" 4
.IX Item "short_url_service service"
.PD
A WWW::Shorten service to use for shortening the \fBweb_link\fR. See
WWW::Shorten for the list of supported services.
.IP "\fBmsg_template\fR \fIstring\fR" 4
.IX Item "msg_template string"
Provides a way to customize the notifications' appearance on \s-1IRC.\s0 When present,
all message construction is done on the client and the prepared messages
(possibly with colors etc) are sent to the server for relaying to \s-1IRC.\s0
.Sp
The following special items are recognized and replaced with the respective
commit elements.
.RS 4
.IP "${project_id}" 4
.IX Item "${project_id}"
The \s-1ID\s0 of the project.
.IP "${author_login}" 4
.IX Item "${author_login}"
The login of the author (e.g. \*(L"joe\*(R").
.IP "${author_name}" 4
.IX Item "${author_name}"
The name of the commit author (e.g. \*(L"Joe Random\*(R")
.IP "${author_via}" 4
.IX Item "${author_via}"
The name of the commit author, plus the name of the committer if that is
different (e.g. \*(L"Joe Random\*(R" or \*(L"Joe Random (via Max Random)\*(R")
.IP "${branch}" 4
.IX Item "${branch}"
The branch of the commit.
.IP "${module}" 4
.IX Item "${module}"
The module of the commit.
.IP "${commit} =item ${revision}" 4
.IX Item "${commit} =item ${revision}"
The \s-1ID\s0 of the commit.
.IP "${path}" 4
.IX Item "${path}"
The changed path(s).
.IP "${log}" 4
.IX Item "${log}"
The log message of the commit.
.IP "${web}" 4
.IX Item "${web}"
The web link associated with the commit. Replaced with the empty string unless
the \fBweb_link\fR option is also given.
.RE
.RS 4
.RE
.IP "\fBstyle\fR \fIhash reference\fR" 4
.IX Item "style hash reference"
Provides a color map for different parts of the message. The following keys are
supported. Defaults are used when keys are missing in the hash. \fBuse_color\fR
must be true for this to have any effect. Used only when \fBmsg_template\fR is
also given.
.RS 4
.IP "revision =item commit_id" 4
.IX Item "revision =item commit_id"
Commit \s-1ID.\s0 Default: none.
.IP "path" 4
.IX Item "path"
Changed path. Default: teal.
.Sp
Depending on the action performed to the path, additional coloring is made:
.RS 4
.IP "addition" 4
.IX Item "addition"
Used for added paths. Default: green.
.IP "modification" 4
.IX Item "modification"
Used for modified paths. Default: teal.
.IP "deletion" 4
.IX Item "deletion"
Used for deleted paths. Default: bold red.
.IP "replacement Used for replaced paths (a Subversion concept). Default: brown." 4
.IX Item "replacement Used for replaced paths (a Subversion concept). Default: brown."
.PD 0
.IP "prop_change" 4
.IX Item "prop_change"
.PD
Used for paths with changed properties (a Subversion concept), combined with
other colors depending on the action \*(-- addition, modification or replacement.
Default: underline.
.RE
.RS 4
.RE
.IP "author" 4
.IX Item "author"
Commit author. Default: green.
.IP "branch" 4
.IX Item "branch"
Commit branch. Default: brown.
.IP "module" 4
.IX Item "module"
Project module. Default: purple.
.IP "web" 4
.IX Item "web"
\&\s-1URL\s0 to commit information. Default: silver.
.IP "separator" 4
.IX Item "separator"
The separator before the commit log. Default: none.
.RE
.RS 4
.RE
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new ( { \fIinitial values\fP } )"
.IX Subsection "new ( { initial values } )"
Standard constructor with initial values in a hashref.
.PP
.Vb 6
\&    my $c = App::KGB::Client\->new(
\&        {   repo_id => \*(Aqmy\-repo\*(Aq,
\&            servers => \e@servers,
\&            ...
\&        }
\&    );
.Ve
.PP
See  above.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "detect_branch_and_module ( $changes )" 4
.el .IP "detect_branch_and_module ( \f(CW$changes\fR )" 4
.IX Item "detect_branch_and_module ( $changes )"
Given a set of changes (an arrayref of App::KGB::Change objects), runs all
the regular expressions as listed in \fBbr_mod_re\fR and \fBmod_br_re\fR and if a
regular expression that matches all the changed paths and returns the branch
and module.
.Sp
.Vb 1
\&    ( $branch, $module ) = $client\->detect_branch_and_module($changes);
.Ve
.IP "shuffle_servers" 4
.IX Item "shuffle_servers"
Returns a shuffled variant of \f(CW\*(C`$self\->servers\*(C'\fR. It considers the last
successfully used server by this client instance and puts it first. If there is
no such server, it considers the state in \f(CW\*(C`status_dir\*(C'\fR and picks the last
server noted there, if it was used in the last 5 minutes.
.IP "expand_link ($string, \e%data)" 4
.IX Item "expand_link ($string, %data)"
Expands items in the form \fI${item}\fR in \fI\f(CI$string\fI\fR, using the data in the
supplied hash reference.
.Sp
Passing
.Sp
.Vb 2
\& "http://git/${module}.git?commit=${commit}",
\& { module => \*(Aqdh\-make\-perl\*(Aq, commit => \*(Aq225ceca\*(Aq }
.Ve
.Sp
would result in \f(CW\*(C`http://git/dh\-make\-perl.git?commit=225ceca\*(C'\fR.
.IP "shorten_url (url)" 4
.IX Item "shorten_url (url)"
Uses the configured \fIshort_url_service\fR to shorten the given \s-1URL.\s0 If no
shortening service is configured, the original \s-1URL\s0 is returned.
.IP "note_last_server($srv)" 4
.IX Item "note_last_server($srv)"
If \f(CW\*(C`status_dir\*(C'\fR is configured, notes \f(CW$srv\fR as the last used server to be used
in subsequent requests.
.IP "init_painter" 4
.IX Item "init_painter"
Creates an internal instance of App::KGB::Painter used to color message
elements.
.Sp
Does nothing if \fIuse_color\fR is false or if painter has been already created.
.IP "colorize \fIcategory\fR => \fItext\fR" 4
.IX Item "colorize category => text"
Returns a colored version of \fItext\fR. If there is no painter, returns just
\&\fItext\fR.
.IP "colorize_change \fIchange\fR" 4
.IX Item "colorize_change change"
returns a colorized string representing a single change
.IP "colorize_changes \e@changes" 4
.IX Item "colorize_changes @changes"
returns a colorized string of all commit's changes
.ie n .IP "format_message $template %details" 4
.el .IP "format_message \f(CW$template\fR \f(CW%details\fR" 4
.IX Item "format_message $template %details"
Returns a formatted message, ready to be sent to the servers. The message is
formatted according to the \fBmessage_format\fR configuration parameter, honouring
\&\fBcolors\fR and \fBuse_color\fR.
.IP "process_commit ($commit)" 4
.IX Item "process_commit ($commit)"
Processes a single commit, returning something for sending to the remote
server. \fISomething\fR is either a reference to array of arguments to be passed
to App::KGB::ServerRef's send_changes method, or, in message-relay mode, a
plain scalar string representing the commit.
.Sp
If \f(CW$commit\fR is a plain scalar (not a reference), then it is assumed to be an
already processed string and is returned directly.
.IP "process" 4
.IX Item "process"
The main processing method. Calls \fBdescribe_commit\fR and while it returns true
values, gives them to \fBprocess_commit\fR and send the result to the server.
.Sp
If \fBbatch_messages\fR flag is true, relays accumulated messages after
processing.
.IP "send_changes \e@args" 4
.IX Item "send_changes @args"
Tries to send the changes described in the given array reference to all
configured servers.
.IP "relay_message \fImessage\fR" 4
.IX Item "relay_message message"
Send a simple message to servers for relaying. Implements the \-\-relay\-msg
command line option.
.SH "PROVIDING REPOSITORY-SPECIFIC FUNCTIONALITY"
.IX Header "PROVIDING REPOSITORY-SPECIFIC FUNCTIONALITY"
App::KGB::Client is a generic class providing repository-agnostic
functionality. All repository-specific methods are to be provided by classes,
inheriting from App::KGB::Client. See App::KGB::Client::Subversion and
App::KGB::Client::Git.
.PP
Repository classes must provide the following method:
.IP "\fBdsescribe_commit\fR" 4
.IX Item "dsescribe_commit"
This method returns an App::KGB::Commit object that
represents a single commit of the repository.
.Sp
\&\fBdescribe_commit\fR is called several times, until it returns \f(CW\*(C`undef\*(C'\fR. The idea
is that a single App::KGB::Client run can be used to process several commits
(for example if the repository is \fBgit\fR\|(1)). If this is the case each call to
\&\fBdescribe_commit\fR shall return information about the next commit in the
series. For \fBsvn\fR\|(1), this module is expected to return only one commit,
subsequent calls shall return \f(CW\*(C`undef\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "App::KGB::Client::Subversion" 4
.IX Item "App::KGB::Client::Subversion"
.PD 0
.IP "App::KGB::Client::Git" 4
.IX Item "App::KGB::Client::Git"