.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) .\" .\" 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" '' '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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" 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 "2011-09-15" "perl v5.12.4" "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( ); \& $client\->run; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBApp::KGB::Client\fR is the backend behind \fIkgb\-client\fR\|(1). It handles the repository-independent parts of sending the notifications to the \s-1KGB\s0 server, \&\fIkgb\-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 "\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 2 \& Example: ([^/]+)/([^/]+)/ \& # branch/module .Ve .IP "\fBbr_mod_re_swap\fR \fI1\fR" 4 .IX Item "br_mod_re_swap 1" If you can only provide the module name in the first capture and the branch name in the second, use this option to signal the fact to \fBkgb-client\fR. .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-1ORC\s0 all the time can be annoing. 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, regardles 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 "\fBstatus_dir\fR" 4 .IX Item "status_dir" Specifies a directory to store information about the last server contacted successfuly. 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. .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 if a regular expression that matches all the changed paths and returns the branch and module. .Sp In case the module detected is the same as \fBignore_module\fR, \f(CW\*(C`undef\*(C'\fR is returned for 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 successfuly 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 "process_commit ($commit)" 4 .IX Item "process_commit ($commit)" Processes a single commit, trying to send the changes summary to each of the servers, defined inn \fBservers\fR, until some server is successfuly notified. .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. .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 Git). If this is the case each call to \&\fBdescribe_commit\fR shall return information about the next commit in the series. For Subversion, 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"