Provided by: kgb-client_1.60-1_all bug

NAME

       App::KGB::Client - relay commits to KGB servers

SYNOPSIS

           use App::KGB::Client;
           my $client = App::KGB::Client( <parameters> );
           $client->run;

DESCRIPTION

       App::KGB::Client is the backend behind kgb-client(1). It handles the repository-
       independent parts of sending the notifications to the KGB server, kgb-bot(1). Details
       about extracting change from commits, branches and modules is done by sub-classes specific
       to the version control system in use.

CONFIGURATION

       The following parameters are accepted in the constructor:

       repo_id repository name
           Short repository identifier. Will be used for identifying the repository to the KGB
           daemon, which will also use this for IRC notifications. Mandatory.

       uri URI
           URI of the KGB server. Something like "http://some.server:port". Mandatory either as a
           top-level parameter or as a sub-parameter of servers array.

       proxy URI
           URI of the SOAP proxy. If not given, it is the value of the uri option, with
           "?session=KGB" added.

       password password
           Password for authentication to the KGB server. Mandatory either as a top-level
           parameter or as a sub-parameter of servers array.

       timeout seconds
           Timeout for server communication. Default is 15 seconds, as we want instant IRC and
           commit response.

       servers
           An array of servers, each an instance of App::KGB::Client::ServerRef class.

           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.

           When shuffling, preference is added to the last server used by the client, or by other
           clients (given "status_dir" is configured).

       batch_messages
           If true, the notifications are sent as a batch in one request to the server.  Useful
           with VCS that send many changes a time (e.g. Git).

           Defaults to false, but will be changed later after some grace period for server
           upgrade.

       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.

           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 KGB server.

               Example: ^/(trunk)/([^/]+)/
                        # /trunk/module/file
                        ^/branches/([^/]+)/([^/]+)/
                        # /branches/test/module/file

       mod_br_re
           Same as br_mod_re, but captures module name first and branch name second.

               Example: ^/branches/([^/]+)/([^/]+)/
                        # /branches/test/module/file

       ignore_branch
           When most of the development is in one branch, transmitting it to the KGB server and
           seeing it on IRC all the time can be annoying. Therefore, if you define ignore_branch,
           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.

       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.

       single_line_commits off|forced|auto
           Request different modes of commit message processing:

           off No processing is done. The commit message is printed as was given, with each line
               in a separate IRC message, blank lines omitted. This is the only possible
               behaviour in versions before 1.14.

           forced
               Only the first line is sent to IRC, regardless of whether it is followed by a
               blank line or not.

           auto
               If the first line is followed by an empty line, only the first line is sent to IRC
               and the rest is ignored. This is the default since version 1.14.

       use_irc_notices
           If true signals the server that it should use IRC notices instead of regular messages.
           Use this if regular messages are too distracting for your channel.

       use_color
           If true (the default) signals the server that it should use colors for commit
           notifications.

       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.

           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.

       verbose
           Print diagnostic information.

       protocol version
           Use specified protocol version. If "auto" (the default), the version of the protocol
           2, unless web_link is also given, in which case protocol version 3 is default;

       web_link template
           A web link template to be sent to the server. The following items are expanded:

           ${branch}
           ${module}
           ${commit}
           ${project}
       short_url_service service
           A WWW::Shorten service to use for shortening the web_link. See WWW::Shorten for the
           list of supported services.

       msg_template string
           Provides a way to customize the notifications' appearance on IRC. 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 IRC.

           The following special items are recognized and replaced with the respective commit
           elements.

           ${project_id}
               The ID of the project.

           ${author_login}
               The login of the author (e.g. "joe").

           ${author_name}
               The name of the commit author (e.g. "Joe Random")

           ${author_via}
               The name of the commit author, plus the name of the committer if that is different
               (e.g. "Joe Random" or "Joe Random (via Max Random)")

           ${branch}
               The branch of the commit.

           ${module}
               The module of the commit.

           ${commit} =item ${revision}
               The ID of the commit.

           ${path}
               The changed path(s).

           ${log}
               The log message of the commit.

           ${web}
               The web link associated with the commit. Replaced with the empty string unless the
               web_link option is also given.

       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. use_color must be true
           for this to have any effect. Used only when msg_template is also given.

           revision =item commit_id
               Commit ID. Default: none.

           path
               Changed path. Default: teal.

               Depending on the action performed to the path, additional coloring is made:

               addition
                   Used for added paths. Default: green.

               modification
                   Used for modified paths. Default: teal.

               deletion
                   Used for deleted paths. Default: bold red.

               replacement Used for replaced paths (a Subversion concept). Default: brown.
               prop_change
                   Used for paths with changed properties (a Subversion concept), combined with
                   other colors depending on the action -- addition, modification or replacement.
                   Default: underline.

           author
               Commit author. Default: green.

           branch
               Commit branch. Default: brown.

           module
               Project module. Default: purple.

           web URL to commit information. Default: silver.

           separator
               The separator before the commit log. Default: none.

CONSTRUCTOR

   new ( { initial values } )
       Standard constructor with initial values in a hashref.

           my $c = App::KGB::Client->new(
               {   repo_id => 'my-repo',
                   servers => \@servers,
                   ...
               }
           );

       See  above.

METHODS

       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 br_mod_re and mod_br_re and if a regular expression that
           matches all the changed paths and returns the branch and module.

               ( $branch, $module ) = $client->detect_branch_and_module($changes);

       shuffle_servers
           Returns a shuffled variant of "$self->servers". 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 "status_dir" and picks the last server noted there, if it was
           used in the last 5 minutes.

       expand_link ($string, \%data)
           Expands items in the form ${item} in $string, using the data in the supplied hash
           reference.

           Passing

            "http://git/${module}.git?commit=${commit}",
            { module => 'dh-make-perl', commit => '225ceca' }

           would result in "http://git/dh-make-perl.git?commit=225ceca".

       shorten_url (url)
           Uses the configured short_url_service to shorten the given URL. If no shortening
           service is configured, the original URL is returned.

       note_last_server($srv)
           If "status_dir" is configured, notes $srv as the last used server to be used in
           subsequent requests.

       init_painter
           Creates an internal instance of App::KGB::Painter used to color message elements.

           Does nothing if use_color is false or if painter has been already created.

       colorize category => text
           Returns a colored version of text. If there is no painter, returns just text.

       colorize_change change
           returns a colorized string representing a single change

       colorize_changes \@changes
           returns a colorized string of all commit's changes

       format_message $template %details
           Returns a formatted message, ready to be sent to the servers. The message is formatted
           according to the message_format configuration parameter, honouring colors and
           use_color.

       process_commit ($commit)
           Processes a single commit, returning something for sending to the remote server.
           Something 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.

           If $commit is a plain scalar (not a reference), then it is assumed to be an already
           processed string and is returned directly.

       process
           The main processing method. Calls describe_commit and while it returns true values,
           gives them to process_commit and send the result to the server.

           If batch_messages flag is true, relays accumulated messages after processing.

       send_changes \@args
           Tries to send the changes described in the given array reference to all configured
           servers.

       relay_message message
           Send a simple message to servers for relaying. Implements the --relay-msg command line
           option.

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.

       Repository classes must provide the following method:

       dsescribe_commit
           This method returns an App::KGB::Commit object that represents a single commit of the
           repository.

           describe_commit is called several times, until it returns "undef". The idea is that a
           single App::KGB::Client run can be used to process several commits (for example if the
           repository is git(1)). If this is the case each call to describe_commit shall return
           information about the next commit in the series. For svn(1), this module is expected
           to return only one commit, subsequent calls shall return "undef".

SEE ALSO

       App::KGB::Client::Subversion
       App::KGB::Client::Git