GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  VCS_DEV (3)

.ds Aq ’

NAME

VCS_dev - Information for VCS::* developers

CONTENTS

SYNOPSIS

VCS_dev provides internal API information for generic <B>VCS::*B> programming access in Perl. This document is for VCS::* developers, not necessarily for users of VCS itself.

DESCRIPTION

VCS is an API for abstracting access to all version control systems from Perl code. This is achieved in a similar fashion to the DBI suite of modules. There are container classes, VCS::Dir, VCS::File, and VCS::Version, and implementation classes, such as VCS::Cvs::Dir, VCS::Cvs::File, and VCS::Cvs::Version, which are subclasses of their respective container classes.

The container classes are instantiated with URLs. There is a URL scheme for entities under version control. The format is as follows:



    vcs://localhost/VCS::Cvs/fs/path/?query=1



The query part is ignored for now. The path must be an absolute path, meaningful to the given class. The class is an implementation class, such as VCS::Cvs.

The container classes work as follows: when the new method of a container class is called, it will parse the given URL, using the VCS->parse_url method. It will then call the new of the implementation’s appropriate container subclass, and return the result. For example,



    VCS::Version->new(vcs://localhost/VCS::Cvs/fs/path/file/1.2);



will return a VCS::Cvs::Version.

Imp IMPLEMENTATION

For the purposes of concretely illustrating the layout of an implementation suppose that there is a need for a VCS::Imp or $Imp implementation.

An implementation class is recognised as follows: its name starts with VCS::, and require "VCS/Imp.pm" will load the appropriate implementation classes corresponding to the container classes - VCS::Imp::Dir, VCS::Imp::File and VCS::Imp::Version..

Hence in MANIFEST, or Unix file specificaton, syntax the Imp implementation ought to be composed of at least these files:



    VCS/Imp.pm
    VCS/Imp/Dir.pm
    VCS/Imp/File.pm
    VCS/Imp/Version.pm



In addition to the usual module distribution files such as MANIFEST, Makefile.PL, etc.

Implementation classes must include documentation for their special requirements, such as mandatory environment variables. See VCS::Cvs for an example.

If a method, or an argument to a method makes no sense for a particular implementation, then the implementation may ignore it, but must do so quietly.

The modules that make up a VCS implementation might act as wrappers around a command language interpreter (CLI or shell) command, or might directly look at files or talk over the network. It is recommended that before implementing a VCS::*::* class that implements direct access, the developer first implement a version that uses the CLI tools, and writes appropriate tests for it. Doing this will ensure that the direct-access version, which passes the tests, will be correct.
o VCS/Imp.pm

The variable $LOG_CMD is the CLI command for obtaining revision history logs. This module typically implements five distinct non-public sub routines: sub _boiler_plate_info {}, sub _split_log {}, sub _parse_log_rev {}, sub _parse_log_header {}, sub _read_pipe {} is for reading from the CLI.

o VCS/Imp/Dir.pm

This module implements three public sub routines/methods: sub new {}, sub name {}, sub content {}.

o VCS/Imp/File.pm

Revisions should be returned in reverse time order (latest first, oldest last). This module implements three public sub routines/methods: sub new {}, sub name {}, sub versions {}.

o VCS/Imp/Version.pm

The variable $DIFF_CMD is the CLI command for doing diffs. The variable $UPDATE_CMD is the CLI command for doing updates. This module implements nine public sub routines/methods: sub new {}, sub name {}, sub version {}, sub tags {}, sub text {}, sub diff {}, sub author {}, sub date {}, sub reason {}.

EXAMPLES

If you prefer there is a pod stub in Imp_pod.tpl that you could catenate onto the tail of your VCS/$Imp.pm file, making sure to edit the template with s/Imp/$Your_VCS_Name/g. For simple version control system APIs (i.e. with a CLI interface and no need for XS, C, or header file worries) an easy way to get started would be to use <B>h2xsB> like so:



    h2xs -AXf -n VCS::Imp



then add a VCS/Imp/VCS directory and put appropriate File.pm, Dir.pm and Version.pm modules in it (add them the the MANIFEST as well). If calling in to your version control system requires XS then omit the -X and -f switches and specify the header file name.

You might also be interested in looking at the other implementations for tips on how to map your version control systems’ CLI commands to VCS::* methods. For parsing details it can prove helpful to see an example of the output of some of the other version control systems. (e.g. the output of the $LOG_CMD in typical usage).

    Cvs

o VCS/Cvs.pm

The variable $LOG_CMD is cvs log.

o VCS/Cvs/Dir.pm
o VCS/Cvs/File.pm
o VCS/Cvs/Version.pm

The variable $DIFF_CMD is cvs diff -u2. The variable $UPDATE_CMD is cvs update -p.

    Rcs

o VCS/Rcs.pm

The variable $LOG_CMD is rlog.

o VCS/Rcs/Dir.pm
o VCS/Rcs/File.pm
o VCS/Rcs/Version.pm

The variable $DIFF_CMD is rcsdiff -u2. The variable $UPDATE_CMD is co -p.

    Hms

o VCS/Hms.pm

The variable $LOG_CMD is flog.

o VCS/Hms/Dir.pm
o VCS/Hms/File.pm
o VCS/Hms/Version.pm

The variable $DIFF_CMD is fdiff. The variable $UPDATE_CMD is fco -p. <B>flogB> output is reversed here.

TODO

Where are the wrappers around rcs’s <B>ciB> or CVS’s <B>cvs ciB>? (This is listed as a known BUG in that VCS is currently read only).

Does Hms have a <B>fciB> command?

See the pod in VCS/File.pm for other unimplemented things.

SEE ALSO

VCS, and the generic implementation in VCS::Dir, VCS::File, and VCS::Version.

The CVS implementation is in VCS::Cvs along with the unpodded VCS/Cvs/*.pm modules.

The Hms implementation is in VCS::Hms along with the unpodded VCS/Hms/*.pm modules.

The rcs implementation is in VCS::Rcs along with the unpodded VCS/Rcs/*.pm modules.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 VCS_DEV (3) 2004-01-02

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.