VCS::LibCVS::Client - an implementation of the CVS client protocol
use VCS::LibCVS::Client; use VCS::LibCVS::Datum; my $conn = VCS::LibCVS::Client::Connection::Local->new(); my $client = VCS::LibCVS::Client->new($conn, "/cvs"); $client->connect(); my $request = VCS::LibCVS::Client::Request::Directory->new(["dir","/cvs/dir"])); my @responses = $client->submit_request($request);
VCS::LibCVS provides native Perl access to CVS. This is the CVS client protocol component of VCS::LibCVS. Do not use this directly, use VCS::LibCVS instead. However, if you really insist, this implementation does work stand-alone.
This documentation assumes you are already familiar with the cvsclient protocol which is documented in the cvsclient info node.
This module uses exceptions to report errors, except where otherwise noted.
This implementation is a very thin layer over the CVS client protocol, although in some places it does a little more, including the following:
When you call connect on the Client, it sends some required requests to the server, and receives some responses from the server. See the documentation of that routine for more details.
There is no Argumentx request, instead Client::Request::Argument handles strings with embedded newlines and issues the Argumentx request itself.
Throughout these docs, all classnames are relative to VCS::LibCVS::, unless they start with ::.
This is a summary of the classes in this implementation. For more details on each of the classes, please see the corresponding docs.
This is the main class of the implementation, its instances represent the client end of the CVS client protocol. In order to construct a Client, an instance of Client::Connection must be provided. After construction, a connect() must be called to connect the Client to the server. After a connection has been established, Client::Request's may be submitted to it, and Client::Response's will be received from it.
Instances of this class represent a connection to a particular CVS server. There are several possible types of connection, each with its own subclass, such as Client::Connection::Local. A Client::Connection can be ignored once it has been used to construct a Client and it should not be used to create more than one Client. Note that a CVS server, and thus a Client::Connection, can provide access to more than one CVS repository, for example, there could be repositories at /home/cvs and /home/user1/repository.
Instances of this class represent protocol requests which are to be sent to the server. It has subclasses, such as Client::Request::Directory, for each type of protocol request. Each subclass takes specific types of arguments, which are provided in the constructor, either with Datum instances of the appropriate type, or with data that could be used to construct those Datum instances. The routine Client->submit_request() is used to send Client::Request's to the server.
Instances of this class represent protocol responses which have been received from the server. It has subclasses, such as Client::Response::Merged for each type of protocol response. The arguments of the response are accessed as instances of subclasses of Datum. Client::Response's are returned by the Client->submit_request() routine.
The rest of this documentation is for the VCS::LibCVS::Client class itself.
$client = Client->new($conn, $root_dir)
A connection to the server which the client should use. It need not be connected already.
The root directory of the CVS repository which the client should use.
$client->connect()
Causes the Client to initiate a connection with the server, using the parameters provided when it was constructed.
First it establishes a connection to the server using its Connection object. Then it performs an initial negotiation with the server, by issuing the following requests:
Asks the server for a list of requests it supports. To find out what these are, use the valid_requests() routine.
Tells the server what responses this client supports. To configure these use the valid_responses() routine.
Tells the server which directory contains the repository we wish to use.
Tells the server which version of the protocol to use.
$client->disconnect()
Disconnects this client from the server.
$client->init_repository()
Creates a new repository at the Root specified when the client was constructed. The client must be disconnected when you call this routine.
@responses = $client->submit_request($request)
Returns responses in the order they were generated by the server. Some requests do not generate a response, in which case this will be an empty list. You can ask a Client::Request if it expects a response.
An instance of a subclass of Client::Request. This must be a request type which is supported by the server.
Sends the request to the server, and returns any responses from the server. No processing is done on the responses. The last request in the list will be an ok or error response, so use the following to check if the request succeeded:
pop(@responses)->isa("VCS::LibCVS::Client::Response::ok")
$valid_responses = $client->valid_responses()
Returns a hash ref of supported responses, as it will be reported to the server. What is sent to the server may be customized before opening the connection.
The keys of the hash are the names of the responses supported by the library, and are not to be modified. The values are booleans and indicate whether or not the client wants to report that response as valid, and may be modified. The initial state of the hash has a pre-defined list of responses turned on, those listed in the constant VCS::LibCVS::Client::DEFAULT_VALID_RESPONSES.
$valid_requests = $client->valid_requests()
Returns a hash ref of requests supported by the server. This must be called when the Client is connected to the server.
The keys of the hash are the names of all the requests supported by either the server or the client. The values are booleans indicating whether the particular request is supported by the server.
$testing_dir = $client->testing_dir($any_repo_dir)
When a connection is created, the Client tests if the connection can support multiple commands. This test requires a directory on the repository, in which it can create a lock file. Unfortunately the root directory of the repository is not always writable, so you can provide a directory which is writeable, before the connection is made using this method.
To install VCS::LibCVS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm VCS::LibCVS
CPAN shell
perl -MCPAN -e shell install VCS::LibCVS
For more information on module installation, please visit the detailed CPAN module installation guide.